API — erro por erro: o que cada mensagem quer dizer e como investigar

O QUE É ESTE APLICATIVO

O aplicativo API é a porta para o sistema do cliente conversar com o ERP. No catálogo ele aparece como "API", com o resumo "Integração com seu app via API, acessível de qualquer lugar", em duas linhas: uma para a modalidade ERP e outra para FIS.

Toda chamada precisa de dois cabeçalhos: access-token e secret-access-token. Os dois valores nascem quando o cliente cria uma chave de API na tela Credenciais do aplicativo (Meus aplicativos › Ver todos os aplicativos › API). A conta pode ter várias chaves; o Secret Access Token de cada uma aparece só na criação. Criar outra chave não derruba as existentes; revogar uma chave derruba na hora quem a usava.

Nunca peça, nunca repita e nunca cole token, senha ou chave na conversa. Para conferir, peça ao cliente que compare o valor na tela dele.

COMO A API DEVOLVE UM ERRO

Quando a chamada chega ao sistema, a resposta é JSON. Nos endpoints antigos o erro vem com code, status, error e message; nos endpoints mais novos, com success, message, data e meta. O que interessa para o diagnóstico é a frase em message e o código HTTP.

Antes de a chamada chegar ao que foi pedido existe uma etapa que confere token, usuário, domínio, IP, horário, plano, loja e o parâmetro da URL. Se ela reprovar, a chamada não executa nada e o cliente recebe uma destas frases.

AS MENSAGENS DA ETAPA DE AUTENTICAÇÃO, UMA A UMA

Esta lista cobre a etapa de autenticação. Se a frase que o cliente colou não está aqui, ela veio da própria operação pedida (cadastro, nota, pedido) e se responde pela fonte daquele assunto.

Access Token não informado! (401). O cabeçalho access-token não chegou ou chegou vazio. Quase sempre é o nome do cabeçalho escrito errado no código do cliente, ou um proxy que remove cabeçalhos personalizados.

Secret Access Token não informado! (401). A mesma coisa com o cabeçalho secret-access-token. Mandar só um dos dois é o erro mais comum de quem está começando.

Access Token e/ou Secret Access Token incorreto(s)! (401). O sistema procura uma chave que tenha exatamente os dois valores juntos e não achou. Causas reais: a chave foi revogada na tela e a integração continua com o par antigo; espaço, quebra de linha ou aspas coladas no valor; par misturado, o Access Token de uma chave com o Secret de outra.

Usuário inválido! O usuário ligado ao token não foi encontrado na empresa. Acontece quando esse usuário foi excluído ou trocado.

Domínio não habilitado! Na prática o cliente costuma ver a frase com o endereço no meio: "O domínio tal não está habilitado!". O endereço usado na chamada não está cadastrado como domínio nem como subdomínio do sistema. Causa real: o integrador montou a URL com um endereço próprio ou com o endereço errado.

Este usuário não está habilitado ao acesso por este IP! (403). O usuário do token tem IPs cadastrados e o IP de onde a chamada saiu não está na lista. Atenção: vale o IP do servidor que faz a chamada, não o do computador do cliente.

Este usuário não está habilitado ao acesso neste horário! (403). O sistema compara a hora atual com a hora de entrada, a hora de saída, o intervalo de almoço e os dias de acesso do usuário do token. Rotina que roda de madrugada ou no fim de semana bate exatamente nisso.

Seu plano expirou. Por favor, renove a sua assinatura! (401). O vencimento do plano da empresa, já somado o prazo de prorrogação, ficou para trás. É assunto de assinatura, não de integração.

O seu plano atual não lhe permite integrar com a API. Por favor, contrate outro plano! (401). A integração por API não está liberada para a empresa. Essa conferência só vale para o token do tipo API. Nos endpoints mais novos a frase é parecida, "O seu plano atual não permite integrar com API. Por favor, contrate outro plano!", e vem com código 402.

Antes de falar em contratar qualquer coisa por causa dessa frase, abra Meus aplicativos › Ver todos os aplicativos e veja o que o botão do card da API mostra hoje. Se estiver Testar grátis, você mesmo liga na hora e usa por 7 dias, sem precisar falar com ninguém. Se mostrar Acessar e mesmo assim não abrir, o teste já foi usado ou o prazo acabou — aí sim é caso de contratação, com quem cuida do plano.

Ocorreu um erro interno! (401). Sai quando o sistema não encontra o plano da empresa. Não é problema do código do cliente; trate como pendência de cadastro/assinatura.

Loja inválida! A loja informada não confere com a empresa do token. Costuma ser um loja_id de outra empresa, ou um número inventado na URL.

O parametro ID é inválido! (400). Duas situações. Ao consultar um registro, editar ou excluir, o id na URL precisa ser número. E ao criar é o contrário: se vier um id dentro do corpo do envio, também é recusado.

Token expirado! (401). A chave de API foi criada com validade (30, 60 ou 90 dias, 6 meses ou 1 ano) e a data passou. A tela Credenciais marca a chave como expirada. Não há renovação: o cliente cria outra chave e troca o par na integração. Chave criada com "Nunca expira" não recebe essa mensagem. A mesma frase também existe nas rotas /mobile/ do aplicativo, por outro motivo.

Bloqueado: As chamadas à nossa API são limitadas a no máximo (número) requisições por segundo e no máximo (número) requisições por dia. Entre em contato com o suporte para efetuar o desbloqueio! (429). Vem do contador de bloqueios do token e aparece quando esse contador chega a dez. O desbloqueio é feito pelo suporte, não pelo cliente.

Excesso de requisições (429). Existe só nos endpoints mais novos. Vem do limite por usuário, explicado abaixo. A frase é sempre essa, mesmo quando a checagem interna tinha outro texto.

DUAS FRASES QUE NÃO SÃO DA AUTENTICAÇÃO, MAS CHEGAM MUITO

Este usuário não possui permissão para acessar este método! (403). O token está certo; o que falta é permissão do usuário ligado ao token para aquele módulo ou ação. Quem resolve é o ERP, no cadastro de permissões do usuário/grupo. É a confusão mais frequente com erro de token.

Este App foi descontinuado! (410). Sai em qualquer chamada cujo endereço tenha /api/v2/. Essa versão foi desligada e nenhuma chamada passa dela: nem token, nem plano, nem nada é conferido. Se a integração parou inteira de uma vez, confirme se a URL tem /v2/ e oriente migrar para os endereços atuais.

OS DOIS LIMITES SÃO DIFERENTES

Um é o limite do token: requisições por segundo e por dia, gravadas no próprio token. É dele que sai a mensagem que começa com "Bloqueado". O contador de uso é somado a cada chamada, mas a linha que grava esse contador está desativada no código, então o uso normal da integração não acumula bloqueio sozinho. Não prometa que "desbloqueia com o tempo": a saída é o suporte.

O outro é o limite por usuário, contado por usuário e por intervalo de tempo. Depois de dez bloqueios em 24 horas ele responde "Limite de requisições excedido, entre em contato com nossa equipe de suporte!".

E aqui vai o cuidado mais importante desta fonte. Nos endpoints antigos essa checagem por usuário só é chamada nas notas fiscais de produto e nas notas fiscais de serviço (em vários métodos delas), e mesmo ali o resultado é descartado: a chamada segue normalmente e o cliente não recebe erro nenhum por causa dela. Não atribua a esse limite uma emissão de nota que falhou. Nos endpoints mais novos, sim, o mesmo estouro vira 429 com "Excesso de requisições". E a frase "Limite de requisições excedido" costuma vir das telas do ERP, não da integração.

O LIMITE DE TEMPO E AS CONSULTAS PESADAS

Cada chamada da API roda com limite de dez segundos. Esse limite conta o processamento do sistema, não a espera do banco de dados — então nem toda lentidão cai nele, e não prometa que "passou de dez segundos, morreu".

O que dá para dizer com segurança: quando a chamada não volta nenhuma das frases acima e sim erro genérico do servidor, resposta vazia ou tempo esgotado, o suspeito é a consulta pesada — listagem larga, sem filtro, com muitos registros para montar.

Como reconhecer: acontece sempre no mesmo endereço, sempre na consulta mais larga, e melhora na hora em que o filtro estreita. A saída é filtrar (data, loja, situação) e paginar. A resposta traz um bloco de paginação com total de registros, total de páginas, página atual, limite por página e o endereço da próxima página. A página se pede pelo parâmetro pagina e o tamanho dela pelo parâmetro limite.

COMO INVESTIGAR O QUE ACONTECEU

São dois lugares, e eles não mostram a mesma coisa.

O primeiro é a consulta de logs da própria API. Ela devolve os registros com descrição, módulo, ação, número do registro, data, usuário, loja e IP, e aceita filtros de descrição, módulo, ação, loja, data de início, data de fim, usuário e número do registro, além da paginação. Não exige período. Por padrão vêm os registros da loja atual do usuário do token. Quando não encontra nada, a resposta é "Não há dados!" com sucesso, e isso não é erro.

O segundo é a tela de log de acessos aberta dentro do aplicativo API. Ela é a mesma tela de log de acessos do ERP, servida pelo mesmo lugar — não é um relatório exclusivo da integração. Sem período informado ela assume do primeiro ao último dia do mês atual, e recusa período maior que um ano ("O período máximo permitido é de 1 ano!"). A loja é a loja atual do usuário. Para abrir essa tela o usuário precisa da permissão de log de acessos no ERP; a consulta pela API não exige essa permissão.

O ponto que mais confunde no atendimento: na prática nenhuma das duas listagens separa o que entrou pela API do que foi feito nas telas do ERP. Ver um registro no log não prova que ele veio da integração. Confirme pelo horário, pela descrição e pelo IP.

Mais duas armadilhas. Só aparece no log o que grava log; consulta costuma não gerar registro, então log vazio não prova que a chamada não chegou. E chamada feita com token de loja virtual é gravada com a origem ecommerce, não com a origem API.

ORDEM DE DIAGNÓSTICO

Primeiro leia a frase exata que o cliente recebeu e ache-a na lista acima: ela já entrega a etapa que reprovou. Se a frase não está na lista, o problema está na própria operação pedida, não na autenticação. Se não veio frase nenhuma, suspeite de consulta pesada e peça para estreitar o filtro e paginar. Só depois disso vá ao log, para saber se a ação chegou a acontecer.

O QUE NÃO SE RESOLVE AQUI

Cadastro de IP, horário e dias de acesso do usuário, permissões, vencimento do plano e os dados em si (cliente, produto, nota, pedido) são do ERP. A API só repete a regra que já está lá. Bloqueio de navegador em chamada feita direto de um site tem fonte própria.