7 - Troubleshooting e glossário
Este capítulo reúne os erros que aparecem no dia a dia, os casos que costumam confundir, o glossário e o que reunir antes de abrir um chamado.
1. Onde olhar primeiro
Quase todo diagnóstico começa na aba Histórico de Notificações, filtrando por Falhou ou Descartado e lendo a coluna Último erro junto com a coluna HTTP. As duas juntas separam "não consegui chegar no endereço" de "cheguei e ele recusou".
| Coluna HTTP | Leitura |
|---|---|
| Vazia | Não houve resposta: DNS, firewall, proxy, endereço errado ou timeout |
| Preenchida | A chamada chegou. O problema está no que o endpoint respondeu |
2. Erros comuns
| Mensagem / sintoma | Causa provável | O que fazer |
|---|---|---|
| Timeout ao conectar/responder no endpoint (30s) | O endpoint não respondeu no prazo — ou está lento, ou processa tudo antes de responder | Pedir ao cliente que responda 200 primeiro e processe depois. Aumentar o Timeout é paliativo |
| HTTP 401 ou 403 | Autenticação. Header ausente, token vencido, ou o JSON do campo Headers está malformado e foi ignorado | Conferir o campo Headers (JSON) e validar com Testar envio. Se usa HMAC, conferir se o segredo é o mesmo dos dois lados |
| HTTP 404 | URL errada, ou a rota mudou do lado do cliente | Corrigir a URL e usar Reenviar selecionado no que ficou para trás |
| HTTP 500 | O endpoint recebeu e quebrou ao processar | É do lado do cliente. Passar o X-TryERP-Delivery da linha para ele localizar no log dele |
| Erro de conexão / nome não resolvido | DNS, firewall ou proxy da rede das estações | Testar da própria estação. Ver o capítulo Configuração inicial, seção 3 |
| Nada é gerado após autorizar | Sem endpoint ativo para aquela filial, ou o documento/evento não está marcado | Conferir a filial no topo, o Ativo, e as listas Documentos e Eventos |
| Cliente diz que recebeu duas vezes | Comportamento esperado do modelo "pelo menos uma vez" | O endpoint precisa tratar idempotência pelo X-TryERP-Delivery. Ver capítulo Guia para o desenvolvedor
|
| Fica em Pendente e não sai | Nenhum TryERP aberto para rodar a rotina de reenvio | Abrir o sistema. Confirmar que a estação não está com duas instâncias (só a primeira roda a rotina) |
| Testar envio funciona, mas as notificações falham | O teste roda na estação onde você está; a emissão pode ocorrer em outra, com regra de rede diferente | Repetir o teste na estação que emite |
3. Casos e cuidados
Endpoint cadastrado na filial errada. É o engano mais comum. O endpoint pertence à filial selecionada no topo da tela; documentos emitidos por outra filial não notificam. Empresa com três filiais emitindo precisa de três cadastros.
Rejeição não notifica. Se o cliente reclama que "a nota saiu e não chegou aviso", confirmar antes a situação do documento: só autorizada (100, 120, 150), cancelada (101) e encerrada (132) geram notificação. Rejeição e lote em processamento, não.
Nota autorizada com alerta (120) notifica normalmente. A situação foi criada pela NT 2026.002 e vale como autorizada. Se o sistema do cliente só trata 100, ele vai descartar uma nota válida — vale avisar na integração.
O reenvio manda o conteúdo original. Ele não recalcula o payload com o estado atual do documento. Uma notificação de AUTORIZADA reenviada depois do cancelamento continua dizendo AUTORIZADA — e está correto: ela relata o evento daquele momento. O cancelamento tem a notificação própria.
Trocar o HMAC secret quebra as notificações em trânsito. As que estiverem pendentes serão assinadas com o segredo novo. Combinar a troca com o cliente, e só depois salvar — senão o endpoint dele passa a recusar tudo com 401 até alguém perceber.
Excluir um endpoint não apaga o histórico dele, mas as notificações passam a apontar para um cadastro que não existe mais. Para parar de notificar, prefira desmarcar Ativo.
4. Limpeza do histórico
Notificações Enviado com mais de 30 dias são apagadas automaticamente. Pendente, Falhou e Descartado permanecem — de propósito, para que um problema não desapareça sozinho.
Se a aba Histórico acumula muito Descartado, isso é sinal de integração quebrada há tempo, não de histórico sujo. Resolver a causa e reenviar; não ignorar.
5. Glossário
| Termo | Significado |
|---|---|
| Webhook | Chamada HTTP que um sistema faz a um endereço de outro para avisar que algo aconteceu. O oposto de ficar consultando (polling) |
| Endpoint | O endereço (URL) que recebe a chamada, e o cadastro que o representa na tela |
| Payload | O conteúdo enviado na notificação — aqui, um JSON |
| Evento | O fato notificado: AUTORIZADA, CANCELADA ou ENCERRADA
|
| cStat | Código de situação devolvido pela SEFAZ. 100/120/150 autorizada, 101 cancelada, 132 encerrada |
| Chave de acesso | O identificador de 44 dígitos do documento fiscal perante a SEFAZ |
| HMAC-SHA256 | Cálculo que gera uma assinatura do conteúdo usando um segredo compartilhado. Permite ao destinatário confirmar a origem da chamada |
| Header | Cabeçalho HTTP — informação que acompanha a chamada, fora do corpo |
| Idempotência | Propriedade de processar a mesma mensagem duas vezes sem gerar efeito duplicado |
| Pelo menos uma vez | O modelo de entrega adotado: a notificação nunca se perde, mas pode chegar repetida |
| X-TryERP-Delivery | Número da entrega, repetido em todas as tentativas da mesma notificação. É a chave de idempotência |
| Timeout | Tempo máximo de espera pela resposta antes de considerar a tentativa falha |
| Backoff | O espaçamento crescente entre as tentativas de reenvio |
| Descartado | Situação da notificação que esgotou as tentativas. Só sai por reenvio manual |
| Nível de detalhe | Quanto vai no corpo: Resumido (identificação do documento) ou Completo (acrescenta destinatário, valor e dados de emissão) |
| Ambiente |
producao ou homologacao, conforme o ambiente em que o documento foi emitido |
6. Suporte
Em caso de dúvida ou comportamento inesperado:
- Conferir as seções "Erros comuns" e "Casos e cuidados" deste capítulo
- Abrir a aba Histórico de Notificações, filtrar por Falhou e Descartado e ler a coluna Último erro
- Confirmar o básico: filial correta, endpoint Ativo, documento e evento marcados
- Rodar Testar envio na estação que emite e guardar o resultado
- Confirmar com o cliente se o endpoint dele registrou a chamada (pelo
X-TryERP-Delivery) - Contatar o suporte com: filial, chave de acesso do documento, evento, print da aba Histórico com a linha em questão, o conteúdo da coluna Último erro na íntegra, o resultado do Testar envio, e o que esperava acontecer
Versão deste manual: Rev 1 — 2026-09-20 (notificação HTTP de autorização, cancelamento e encerramento de NF-e, NFC-e, CT-e, CT-e OS e MDF-e; cadastro de múltiplos endpoints por filial com filtro de documento e evento; payload resumido/completo; headers customizados e assinatura HMAC-SHA256; entrega imediata com rede de segurança a cada 2 minutos, backoff e limite de tentativas; histórico com reenvio manual e limpeza automática)