FAQ API

P: Fiz a chamada mas recebi erro de autenticação. O que verificar primeiro? R: O token de autenticação da API é o token da conexão — não é um token global da conta. Cada conexão tem o seu próprio token, configurado em Conexões → Integrações → Token da Conexão. O header da requisição deve ser Authorization: Bearer {seu_token_aqui}. Verifique se está usando o token da conexão correta para a operação desejada.

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 outra fila 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 a fila especificada.

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; (3) confira a URL completa; (4) o cabeçalho deve conter Authorization: Bearer {token_da_conexao}; (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: 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 até reconectar. ◽ 2. Segunda: o token mudou? Token é por conexão. Se a conexão foi recriada (excluída e readicionada), o token muda e o antigo passa a retornar 401.