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.
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.