API 2.2.0 • ESTÁVEL

Uma integração segura com o ADN para todas as empresas.

O gateway centraliza certificados A1, resolve matrizes e filiais e consulta a API do Ambiente de Dados Nacional da NFS-e por uma interface única.

Explorar no Swagger Primeira integração

MONITORAMENTO

Status em tempo real

GatewayConsultando...

Versão2.2.0

Resposta-

Última verificação: -

NF-E MODELO 55

Distribuição DF-e por NSU

POST/nfe/distribuicao-dfeAPI KEY

Executa uma única chamada mTLS ao serviço oficial NFeDistribuicaoDFe, na modalidade distNSU. O gateway não controla cursor, não persiste documentos e não interpreta nem descompacta o XML.

Conteúdo preservado: cada docZip é devolvido em Base64 como recebido da SEFAZ, acompanhado de nsu e schema.

Exemplo cURL

curl -X POST "https://adn-gateway.pes2b.com/nfe/distribuicao-dfe" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_CHAVE_OPERACIONAL" \
  -d '{
    "empresa_codigo": "JORGEPLA_CONTABILIDADE",
    "cnpj_consulta": "10576541000116",
    "ult_nsu": "000000000000000"
  }'

Resposta sem documentos

{
  "success": true,
  "cStat": "137",
  "xMotivo": "Nenhum documento localizado",
  "ultNSU": "000000000000000",
  "maxNSU": "000000000000000",
  "documentos": []
}

INTEGRAÇÃO

Primeiros passos

Solicite uma chave operacional à TI. Ela é diferente do token administrativo.

Envie a chave no cabeçalho X-API-Key em toda chamada a /adn/*.

Informe o código cadastrado da empresa, seu CNPJ e o NSU que deseja consultar.

URL base

https://adn-gateway.pes2b.com

SEGURANÇA

Autenticação

A API operacional usa uma chave exclusiva no cabeçalho HTTP. Não envie a chave no endereço, corpo ou parâmetros da requisição.

X-API-Key: SUA_CHAVE_OPERACIONAL

Importante: o token administrativo do Appsmith não deve ser usado em automações. Ele dá acesso ao cadastro de empresas e certificados.

ENDPOINT PRINCIPAL

Consultar documento fiscal

POST/adn/consultar-dfeAPI KEY

Consulta o ADN com o certificado A1 resolvido para a empresa. Para uma filial configurada para herdar o certificado, o gateway usa automaticamente o certificado da matriz e preserva o CNPJ consultado da filial.

Exemplo cURL

curl -X POST "https://adn-gateway.pes2b.com/adn/consultar-dfe" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_CHAVE_OPERACIONAL" \
  -d '{
    "empresa_codigo": "JORGEPLA_CONTABILIDADE",
    "cnpj_consulta": "10576541000116",
    "nsu": 2144
  }'

Resposta

{
  "sucesso": true,
  "empresa_codigo": "JORGEPLA_CONTABILIDADE",
  "nsu": 2144,
  "data": { "documentos": [] }
}

CONTRATO

Campos da consulta

Campo	Tipo	Rota	Descrição
`empresa_codigo`	texto	Ambas	Código único gerado no cadastro da empresa.
`cnpj_consulta`	texto	Ambas	CNPJ com 14 dígitos, sem pontuação.
`nsu`	inteiro	NFS-e	NSU inicial da busca; aceita zero.
`ult_nsu`	texto	NF-e	Último NSU com exatamente 15 dígitos.

AUTOMAÇÃO

Configuração no n8n

Crie uma única credencial do tipo Header Auth e reutilize-a nas rotas de NFS-e e NF-e. No nó HTTP Request, selecione essa credencial e envie o corpo como JSON.

Campo no n8n	Valor
Name	`X-API-Key`
Value	A chave operacional fornecida pela TI
Method	`POST`
URL	`https://adn-gateway.pes2b.com/adn/consultar-dfe`
Body Content Type	`JSON`

MULTIEMPRESA

Matrizes e filiais

O cadastro permite certificado dedicado ou compartilhado. Quando uma filial está marcada para usar o certificado A1 da matriz, nenhuma cópia do arquivo precisa ser enviada para ela. A consulta continua usando o CNPJ e o NSU próprios da filial.

DIAGNÓSTICO

Respostas de erro

Status	Significado	Ação
400	Campos inválidos ou ausentes	Revise código, CNPJ e NSU.
401	API Key ausente ou inválida	Confira a credencial Header Auth.
404	Rota ou cadastro não encontrado	Confira a URL e o código da empresa.
422	Certificado incompatível ou consulta recusada	Teste ou substitua o certificado no Appsmith.
503	Serviço ou autenticação indisponível	Acione a TI.

ACESSO RESTRITO

API administrativa

Os endpoints /admin/empresas e /admin/certificados sustentam a tela do Appsmith e usam Authorization: Bearer. Eles aparecem no Swagger para referência da equipe técnica, mas o token não deve ser compartilhado com integrações comuns.

RECURSOS

Downloads

JSONOpenAPIContrato completo para importar em ferramentas.Baixar POSTColeção PostmanExemplos operacionais prontos para testar.Baixar MDGuia técnicoDocumentação portátil em Markdown.Baixar

BOAS PRÁTICAS

Segurança

Certificados e senhas ficam criptografados no banco; a API nunca os devolve.
A chave operacional é armazenada no servidor somente como hash SHA-256.
Use uma credencial do n8n, nunca texto fixo dentro do workflow.
Ao suspeitar de exposição, solicite rotação imediata da chave.
O endpoint público /health não revela segredos.