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.