FAQ API

P: Fiz a chamada mas recebi erro de autenticação. O que verificar primeiro? R: São dois os tokens aceitos. O mais comum é o token da conexão, configurado em Conexões → Integrações → Token da Conexão — cada conexão tem o seu. Existe também o Token da Empresa, único para a empresa inteira, em Configurações → Token da Empresa. Nos dois casos o header da requisição deve ser Authorization: Bearer {seu_token_aqui}. Verifique se está usando o token correto para a operação desejada.

P: Autentiquei com o Token da Empresa e recebi erro 400 pedindo a conexão. Por quê? R: Porque o Token da Empresa não carrega a conexão dentro dele, e a plataforma não escolhe uma sozinha. Informe whatsappId, connectionId ou whatsappName na query string ou no corpo da requisição — em envio com arquivo, use a query string. A lista de IDs das suas conexões está em Configurações → Token da Empresa. Com o token da conexão esse erro não acontece.

P: Preciso habilitar algo antes de usar as APIs? R: Sim. Dois pré-requisitos obrigatórios: (1) a conexão precisa ter um token definido em Conexões → Integrações → Token da Conexão; (2) a funcionalidade API Externa precisa estar habilitada no plano. Se qualquer um dos dois estiver faltando, a chamada retorna erro. Entre em contato com o suporte da plataforma se precisar habilitar a API Externa.

P: Como confirmar que minhas credenciais estão corretas antes de testar endpoints complexos? R: Use o endpoint de Status da Conexão — ele só exige o token e retorna o estado atual da conexão (online/offline). Se retornar dados, autenticação e endpoint estão corretos. Se retornar erro, o problema está nas credenciais ou na URL base.

P: Qual a URL base das APIs e como montar o endpoint? R: A URL base é o backendURL da sua instância (disponível nas configurações da plataforma). Cada API tem seu path específico documentado. Estrutura completa: https://{backendURL}/api/{recurso}. Verifique sempre: (1) URL base correta para sua instância, (2) path exato do endpoint, (3) método HTTP correto (GET, POST, PUT, DELETE).

P: Posso usar o mesmo token em duas conexões diferentes? R: Não. Cada token deve ser único por conexão. Usar o mesmo token em duas conexões gera conflito e a API pode retornar erro ou responder de forma inesperada.

P: Como envio o payload? O formato importa? R: O payload deve ser JSON com Content-Type: application/json. Atenção ao tipo de cada campo. Payload malformado gera erro 422 ou similar. Sempre valide o JSON antes de enviar.

P: A API retornou erro 404. O que significa? R: O endpoint não foi encontrado. Causas mais comuns: URL base errada, path do endpoint com erro de digitação, ou o recurso buscado não existe. Verifique a URL completa caractere por caractere comparando com a documentação.

P: Tentei enviar mensagem e recebi Message Undeliverable. Por quê? R: A mensagem saiu do servidor mas não foi entregue ao destinatário. Causas: (1) o cliente bloqueou seu número; (2) o número não tem WhatsApp ativo; (3) para canais oficiais, a janela de 24h está fechada e você não usou Mensagem Template.

P: O que é a janela de 24 horas e quando ela bloqueia minha API? R: Em canais oficiais, a Meta só permite mensagens livres enquanto o cliente respondeu nos últimos 24h. Se a janela estiver fechada, apenas Mensagem Template aprovada pode ser enviada. Em canais não oficiais essa regra não se aplica formalmente.

P: Preciso enviar uma mensagem para um cliente que não interagiu há mais de 24h. Como fazer via API? R: Use a API de Mensagem Template (disponível para canais oficiais). O template precisa estar previamente aprovado pela Meta. Após o cliente responder, a janela de 24h reabre e mensagens livres voltam a funcionar.

P: Recebi erro #131008 Required parameter is missing. O que fazer? R: Esse erro é específico da API Oficial. Um campo obrigatório do Template não foi enviado. Verifique na Meta quantas variáveis o template aprovado exige e certifique-se de que o payload contém todas elas preenchidas.

P: Recebi erro #132000 Number of parameters does not match. O que fazer? R: Esse erro é específico da API Oficial. A quantidade de variáveis enviadas é diferente da quantidade que o template exige. Confira o template aprovado na Meta e ajuste o número de parâmetros no payload para bater exatamente.

P: Como transferir um ticket para outro Setor via API? R: Use o endpoint de atualização de ticket (PUT /api/tickets/updateAPI) passando o novo queueId. O ticket continua aberto e vai para o Setor especificado.

P: Como depurar uma chamada API que não está funcionando? R: Sequência recomendada: (1) verifique autenticação com o endpoint de Status da Conexão; (2) confirme método HTTP (POST, GET, PUT, DELETE); (3) confira a URL completa; (4) o cabeçalho deve conter Authorization: Bearer {seu_token_aqui}; (5) valide o JSON do payload; (6) teste com o mínimo de campos obrigatórios; (7) leia o corpo completo da resposta de erro — geralmente contém o motivo exato.

P: O cliente diz que a integração funcionava e parou de funcionar do nada.

1. Primeira checagem: status da conexão em Conexões. Se caiu para QR Code, toda a integração para — nenhuma mensagem sai nem entra até reconectar.

2. Segunda: o token mudou? O token da conexão é por conexão. Se a conexão foi recriada (excluída e readicionada), o token muda e o antigo passa a retornar 401.