3 - Cadastrar um endpoint

A aba Endpoints tem a lista de endereços cadastrados à esquerda e o formulário Configuração do Endpoint à direita. Uma filial pode ter vários endpoints — cada um com seus próprios filtros, autenticação e política de tentativas.

1. Selecionar a filial

O campo Emitente/Filial, no topo da tela, define de quem são os endpoints listados. Ele vale para as duas abas. Trocar a filial recarrega a lista e o histórico.

O endpoint pertence à filial, não à empresa. Se o cliente emite por três filiais e quer ser avisado das três, são três cadastros — ou o sistema dele só vai receber as notas de uma. É o engano mais comum na primeira configuração.

2. Os campos, um a um

Campo	Para que serve
Descrição	Texto livre para você identificar o cadastro na lista (ex.: "ERP do cliente — produção"). Não vai na notificação
URL	O endereço que receberá a chamada. Único campo obrigatório
Método HTTP	POST ou GET. Ver a seção 3
Nível detalhe	Resumido ou Completo — quanto de informação vai no corpo. Ver capítulo Eventos e o conteúdo enviado
Documentos	Lista marcável: NFe, NFCe, CTe, CTeOS, MDFe. Só os marcados notificam
Eventos	Lista marcável: Autorizacao, Cancelamento, Encerramento
Headers (JSON)	Cabeçalhos HTTP extras, em formato JSON. Ver a seção 4
Assinar corpo com HMAC-SHA256	Liga a assinatura do corpo. Ver a seção 5
HMAC secret	O segredo compartilhado usado na assinatura. Exibido mascarado
Timeout (s)	Quanto esperar pela resposta antes de considerar falha. Padrão 30
Tentativas máx.	Quantas tentativas antes de desistir. Padrão 5
Ativo	Desmarcado, o endpoint para de receber notificações — sem perder o cadastro

Os filtros Documentos e Eventos são cruzados: um endpoint com NFe + NFCe e Autorizacao recebe autorização de NF-e e de NFC-e, e nada mais. O Encerramento só ocorre em MDF-e, então marcá-lo sem marcar MDFe não tem efeito.

3. POST ou GET

	POST (recomendado)	GET
Como os dados vão	Corpo da requisição, em JSON	Query string na URL
Conteúdo	Payload completo, incluindo blocos aninhados (destinatário, valores)	Só os campos simples — o que está aninhado não vai
Assinatura HMAC	Disponível	Indisponível — não há corpo para assinar

Use GET apenas quando o sistema do cliente não souber receber POST. Além de perder a assinatura e os blocos aninhados, dados de nota fiscal passam a trafegar na URL — e URL costuma ser gravada em log de servidor, de proxy e de firewall.

4. Headers (JSON)

Serve para atender a autenticação que o endpoint do cliente exigir. O conteúdo é um objeto JSON simples, com um par por cabeçalho:

{ "Authorization": "Bearer eyJhbGciOi...", "x-api-key": "9f3c2b1e-..." }

Deixe em branco se o endpoint não exige autenticação. O Content-Type não precisa ser informado — o sistema já envia application/json no POST.

Se o JSON estiver malformado, os cabeçalhos são simplesmente ignorados e a chamada segue sem eles — o envio não quebra. Na prática isso aparece como 401 ou 403 vindo do endpoint. Ao investigar uma falha de autenticação, conferir este campo primeiro.

5. Assinatura HMAC-SHA256

Marcando Assinar corpo com HMAC-SHA256 e preenchendo o HMAC secret, cada chamada leva o cabeçalho X-TryERP-Signature com a assinatura do corpo.

Isso responde a uma pergunta que o sistema do cliente não consegue responder sozinho: "esta chamada veio mesmo do TryERP, ou alguém descobriu a URL?" Quem conhece o segredo consegue recalcular a assinatura; quem não conhece, não.

O segredo é combinado entre as duas pontas — pode ser qualquer texto longo e aleatório. Ele não trafega na chamada: o que viaja é o resultado do cálculo. O procedimento de validação está no capítulo Guia para o desenvolvedor do endpoint.

6. Testar envio

O botão Testar envio manda ao endereço informado uma notificação de exemplo, com "evento": "TESTE" e uma chave de acesso fictícia de 44 zeros. Usa exatamente o que está na tela — URL, método, headers, HMAC e timeout — mesmo que você ainda não tenha salvo.

O resultado aparece numa mensagem com o código HTTP e o início da resposta.

O teste não entra na fila e não aparece no histórico: é uma chamada avulsa, só para validar conectividade, autenticação e assinatura. Pode ser repetido à vontade sem sujar o registro de entregas.

7. Salvar, criar outro, excluir

• Salvar grava o endereço em edição. A URL é obrigatória e a filial precisa estar selecionada
• Novo limpa o formulário para um cadastro novo, já com todos os documentos e eventos marcados e os padrões de timeout e tentativas
• Excluir apaga o endpoint selecionado na lista, com confirmação

Para suspender temporariamente as notificações, desmarque Ativo em vez de excluir. Excluir perde a configuração, e o histórico das notificações daquele endpoint deixa de ter a quem se referir.

8. Faça e não faça

Faça	Não faça
Testar antes de salvar, na estação que vai emitir	Cadastrar e assumir que funciona porque a URL "está certa"
Marcar só os documentos e eventos que o cliente pediu	Deixar tudo marcado "por garantia" — gera chamada que o cliente descarta
Usar https://	Usar http:// na internet, ainda mais sem HMAC
Usar HMAC quando o endpoint é público	Confiar que ninguém vai descobrir a URL
Timeout curto (10–30 s)	Timeout alto, que prende o envio esperando um endpoint lento
Um cadastro por filial que emite	Um cadastro só, esperando receber de todas as filiais

---

Próximo capítulo: Eventos e o conteúdo enviado — o que exatamente sai em cada notificação.