Pular para o conteúdo principal

Autenticação

Toda chamada de ingestão leva a chave da conta em um header:

X-Api-Key: <chave-de-ingestao-da-conta>

Não há OAuth, não há token de sessão e não há login. Quem chama a ingestão é um sistema — discador, plataforma de WhatsApp —, não uma pessoa, e um fluxo de credencial de usuário aqui só criaria um token para renovar sem necessidade.

Sobre a chave​

É uma por conta (cliente). Não há chave por parceiro nem por integração. Se dois sistemas enviam para a mesma conta, os dois usam a mesma chave.

É gerada pelo administrador da conta dentro do QA Analytics e entregue a você pelo canal que o cliente preferir. A plataforma a exibe uma única vez, no momento da geração: depois disso só existe o hash, e não há como recuperá-la. Se você perder a chave, o cliente gera outra — o que invalida a anterior.

Rotacionar invalida a antiga na hora. Não há período de convivência entre a chave velha e a nova. Um integrador rodando com a chave anterior começa a receber 401 no primeiro request seguinte.

Combine a rotação antes

Rotação é a operação que mais causa incidente nesta integração, e o motivo é sempre o mesmo: o administrador gerou uma chave nova para testar e o webhook em produção parou. Trate a rotação como janela de manutenção combinada com o cliente.

Como guardar​

Como se guarda senha: em cofre de segredo ou variável de ambiente do servidor.

Nunca em query string, nunca em log de requisição, nunca em código versionado, nunca em front-end. A chave dá acesso de escrita à conta inteira de um cliente.

Quando falha​

Duas respostas possíveis, e as duas são iguais — de propósito.

Header ausente:

HTTP/1.1 401 Unauthorized
{ "messages": ["Header X-Api-Key ausente."] }

Chave inválida ou conta suspensa:

HTTP/1.1 401 Unauthorized
{ "messages": ["Chave de ingestão inválida."] }

A plataforma não distingue "esta chave não existe" de "esta chave existe mas a conta está suspensa". Distinguir permitiria descobrir chaves válidas de clientes inadimplentes por tentativa e erro.

Para você isso quer dizer uma coisa prática: 401 nunca se resolve com retry. Ou a chave está errada, ou a conta perdeu acesso, e nenhum dos dois melhora tentando de novo. Alerte a operação e fale com o cliente. Ver Erros e retry.

Ambientes​

O {BASE_URL} é fornecido pelo cliente (ou pelo Mais Contato) e é diferente por ambiente — homologação e produção têm hosts distintos e chaves distintas.

Uma chave de homologação não funciona em produção e vice-versa. Isso é bom: garante que um teste não suje a base real do cliente, e é o que permite você validar a integração antes do go-live sem consumir o limite de uso dele.