Documentação da API

Referência da integração de parceiro: autenticar, criar aplicações, ativar o número por login do Facebook, enviar notificação e receber o status.

As duas superfícies

São dois conjuntos de credenciais com escopos diferentes. Entender essa separação resolve a maior parte dos erros de integração.

Autenticação

OAuth 2.0 com client_credentials. As credenciais vão em Basic auth e o token retornado segue no cabeçalho Authorization das chamadas seguintes.

curl -X POST "$CPW_API_BASE/oauth/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=$ESCOPOS"

Cada credencial nasce com um conjunto de escopos que delimita o que ela pode fazer: enviar notificação, ler notificação, ler modelos e ler canais, na API da aplicação, e provisionamento, na API do parceiro. Os escopos são definidos na criação e não mudam depois.

Ativação do número

Você gera um link de curta duração e envia para o responsável pelo número. Ele abre, entra com o login do Facebook, escolhe a conta comercial e o número, e a conexão é confirmada na hora. Sem token para copiar e sem QR Code.

curl -X POST "$CPW_API_BASE/api/v1/partner/tenants" \
  -H "Authorization: Bearer $PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Loja Centro",
    "scopes": ["$ESCOPO_DE_ENVIO", "$ESCOPO_DE_MODELOS"]
  }'

curl -X POST "$CPW_API_BASE/api/v1/partner/tenants/$APP_ID/whatsapp/integration-link" \
  -H "Authorization: Bearer $PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "returnUrl": "https://seu-sistema.com.br/integracoes/whatsapp" }'

A tela é hospedada por nós, roda o fluxo oficial da Meta e leva a sua marca.

curl -X POST "$CPW_API_BASE/api/v1/notifications" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5519999999999",
    "template": { "name": "pedido_enviado", "language": "pt_BR" },
    "variables": { "1": "João", "2": "12345" },
    "reference": "pedido-12345"
  }'

curl "$CPW_API_BASE/api/v1/templates?status=approved&category=UTILITY" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

As categorias seguem a classificação da Meta: UTILITY, MARKETING eAUTHENTICATION. A tarifa de cada mensagem entregue muda conforme essa categoria.

Webhooks de status

Em produção o caminho recomendado é receber, não consultar. Cadastre a sua URL e os eventos chegam assinados com HMAC-SHA256 no cabeçalho X-CPW-Signature, comX-CPW-Delivery para idempotência do seu lado.

Erros

Todos os erros seguem o mesmo formato, com código HTTP e um identificador estável.