Guia de Integrações

HTTP (HyperText Transfer Protocol) é o protocolo que dois sistemas usam para conversar pela internet: um lado (o cliente — seu ERP, ou o navegador) envia uma requisição e o outro lado (o servidor — a Sefaz, a Prefeitura, o ADN) devolve uma resposta. Toda integração fiscal — emissão de NFe, consulta de convênio, transmissão de CT-e — acontece por cima desse mesmo protocolo.

HTTPS é HTTP com uma camada de criptografia (TLS) por cima — é o que garante que ninguém no meio do caminho consiga ler ou alterar o conteúdo trafegado. Web services fiscais brasileiros normalmente exigem HTTPS com certificado do cliente (o certificado A1/A3 da empresa), não apenas o cadeado comum do navegador.

Uma URL (Uniform Resource Locator) é o endereço completo de um recurso na web. Ela é composta por partes bem definidas:

https://api.sefaz.uf.gov.br:443/nfe/autorizacao?ambiente=2
└──┬──┘  └──────┬──────────┘  └┬┘ └────┬───────┘ └───────┬───────┘
 protocolo     host          porta    path        query string (parâmetros)

Path (ou caminho) é a parte que identifica o recurso dentro do host, ex.: /nfe/autorizacao. Endpoint é o termo usado no dia a dia de integração para "a combinação de URL + método HTTP que expõe uma funcionalidade específica" — por exemplo, "o endpoint de autorização de NFe" ou "o endpoint de consulta de convênio do ADN". Uma mesma API costuma ter vários endpoints (autorização, consulta, cancelamento, inutilização), cada um com seu próprio path.

Dentro de uma mesma URL, a sensibilidade a maiúsculas/minúsculas varia por parte: o host não é case sensitive (API.sefaz.uf.gov.br resolve igual a api.sefaz.uf.gov.br), mas o path normalmente é — depende de como o servidor trata a rota, e a maioria trata /nfe/autorizacao e /NFe/Autorizacao como dois caminhos diferentes (o segundo provavelmente devolve 404). As chaves e valores da query string também são case sensitive por padrão: ?ambiente=2 não é o mesmo que ?Ambiente=2 para uma API que só reconhece o parâmetro em minúsculas.

Cada autorizador fiscal publica os seus próprios endereços — e eles mudam entre ambiente de produção e homologação, e entre UFs. Não adivinhe a URL: veja os endereços oficiais de Web Service de NFe & NFC-e por UF e ambiente.

Toda troca HTTP é um par: uma requisição (request) que o cliente envia, e uma resposta (response) que o servidor devolve. A requisição carrega um método (o verbo que diz a intenção) e o servidor responde com um código de status que diz o que aconteceu.

Métodos mais comuns:

GET

Buscar/consultar um recurso, sem alterar nada no servidor.

POST

Criar um recurso ou executar uma ação (ex.: autorizar uma NFe).

PUT / PATCH

Atualizar um recurso existente, total ou parcialmente.

DELETE

Remover um recurso.

Faixas de status code:

2xx — sucesso

Ex.: 200 OK, 201 Created. A operação foi concluída como esperado.

3xx — redirecionamento

O recurso está em outro endereço; o cliente deve seguir para lá.

4xx — erro do cliente

Ex.: 400 (payload inválido), 401 (não autenticado), 403 (sem permissão), 404 (não existe).

5xx — erro do servidor

O servidor falhou ao processar uma requisição válida — normalmente vale tentar de novo.

Uma requisição (e uma resposta) HTTP têm duas partes principais além da linha inicial:

Headers (cabeçalhos) são metadados sobre a mensagem — não são "o conteúdo em si", mas informações sobre ele: qual o formato do corpo (Content-Type), quem está fazendo a chamada (Authorization), o tamanho do payload, o encoding, etc.

Body (corpo) é o conteúdo de fato — o XML da NFe sendo enviada para autorização, o JSON com os dados de uma consulta, ou vazio (em muitos GET, o body não é usado).

POST /nfe/autorizacao HTTP/1.1
Host: api.sefaz.uf.gov.br
Content-Type: application/soap+xml; charset=utf-8
Authorization: Bearer eyJhbGciOiJI...

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope>...</soap:Envelope>

Diferente do path e da query string, nomes de header não são case sensitive — é uma regra explícita da especificação HTTP: Content-Type, content-type e CONTENT-TYPE são o mesmo cabeçalho, e a maioria dos clientes/servidores normaliza a caixa ao exibir ou logar. Já o valor do header e o body seguem a regra do formato que carregam — um Content-Type: application/json é só o rótulo; dentro do JSON, as chaves continuam case sensitive normalmente.

Um contrato de integração é o acordo formal entre quem envia e quem recebe uma mensagem: quais campos existem, quais são obrigatórios, que tipo e tamanho cada um tem, e em que ordem aparecem. Sem esse acordo, os dois lados só conseguem "adivinhar" o formato um do outro — e é exatamente isso que um schema resolve: um documento à parte, lido por máquina, que descreve o contrato e permite validar uma mensagem automaticamente antes de processá-la.

O mesmo conceito, formatos diferentes:

XSD (XML Schema Definition)

Descreve a estrutura de um XML — é o formato usado pela Sefaz e pelo ADN para publicar o layout oficial de NFe, NFC-e, CT-e e NFS-e.

WSDL

O contrato de um web service SOAP inteiro — quais operações existem (autorização, consulta...), o formato de entrada e saída de cada uma.

JSON Schema

O equivalente ao XSD para JSON — define campos, tipos e obrigatoriedade de um payload JSON.

OpenAPI (Swagger)

Descreve uma API REST inteira — todos os endpoints, métodos, parâmetros e o schema JSON de cada request/response.

Na prática fiscal, isso significa que o XML de uma NFe precisa validar contra o XSD publicado pela Sefaz antes de ser assinado e transmitido — um XML fora do schema é rejeitado no primeiro filtro, sem nem chegar às regras de negócio. Trate o schema como a fonte da verdade: quando o autorizador atualiza a versão do layout (ex.: NFe 4.00), o schema é o primeiro lugar a conferir.

Use o formatador e validador de XML para conferir se a estrutura do documento está bem formada antes de validar contra o schema oficial do autorizador.

JSON (JavaScript Object Notation) é um formato de texto leve para representar dados estruturados — pares de chave e valor, listas e objetos aninhados. É o formato dominante em APIs REST modernas por ser compacto e fácil de ler/gerar em qualquer linguagem.

{
  "cnpj": "12345678000199",
  "razaoSocial": "Empresa Exemplo LTDA",
  "ativo": true,
  "enderecos": [
    { "uf": "SP", "municipio": "São Paulo" }
  ]
}

Use o formatador de JSON desta ferramenta para validar e visualizar payloads antes de integrar. Para tipos, boas práticas e o uso de JSON no ADN, veja o artigo O que é JSON.

XML (eXtensible Markup Language) representa dados através de tags aninhadas, abertas e fechadas — <tag>valor</tag>. É o formato usado por praticamente todos os documentos fiscais eletrônicos brasileiros (NFe, NFC-e, CT-e, NFS-e nacional): a estrutura, os campos obrigatórios e os tipos de cada valor são definidos por um schema XSD publicado pelo órgão responsável, e o XML enviado precisa validar contra esse schema antes de ser assinado digitalmente e transmitido.

<NFe xmlns="http://www.portalfiscal.inf.br/nfe">
  <infNFe Id="NFe35240112345678000199550010000000011000000015" versao="4.00">
    <ide>
      <cUF>35</cUF>
      <natOp>Venda de mercadoria</natOp>
    </ide>
  </infNFe>
</NFe>

Use o formatador de XML para validar, comparar (diff) e converter XML de documentos fiscais. Para namespaces, assinatura digital, hash e charset, veja o artigo O que é XML.

HTML (HyperText Markup Language) também usa tags, mas serve a um propósito diferente do XML: em vez de descrever dados estruturados para troca entre sistemas, ele descreve a estrutura visual de uma página para ser renderizada em um navegador (títulos, parágrafos, tabelas, links). Em integrações fiscais, HTML aparece sobretudo em respostas de consulta pública pensadas para humanos — por exemplo, a página de consulta de uma NFC-e pelo QR Code — e não no fluxo de transmissão de documentos, que é sempre XML/SOAP.

Veja também o artigo O que é HTML.

SOAP (Simple Object Access Protocol) é um protocolo que empacota a requisição inteira dentro de um XML chamado envelope, com seções fixas de Header e Body. É o padrão usado pelos web services das Sefaz para autorização, consulta e cancelamento de NFe/CT-e — o contrato de cada serviço (operações disponíveis, formatos aceitos) costuma vir descrito em um arquivo WSDL.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Header/>
  <soap:Body>
    <nfeAutorizacaoLote xmlns="http://www.portalfiscal.inf.br/nfe/wsdl/NFeAutorizacao4">
      <nfeDadosMsg>...</nfeDadosMsg>
    </nfeAutorizacaoLote>
  </soap:Body>
</soap:Envelope>

REST (Representational State Transfer) é um estilo de arquitetura mais simples: cada recurso tem sua própria URL, o método HTTP (GET/POST/PUT/DELETE) já expressa a ação, e o corpo costuma ser JSON em vez de um envelope XML. O ADN (Ambiente de Dados Nacional) do NFS-e nacional, por exemplo, expõe APIs REST/JSON — diferente do modelo SOAP das Sefaz estaduais de NFe.

Na prática, isso significa dois "sotaques" diferentes a dominar dependendo do autorizador do outro lado: web services SOAP de CT-e por UF e a API REST de consulta pública do ADN (NFS-e nacional).

Os dois termos são frequentemente confundidos, mas respondem perguntas diferentes:

Autenticação (Authentication)

"Quem é você?" — prova de identidade. Ex.: certificado digital A1/A3, usuário e senha, token de sessão.

Autorização (Authorization)

"O que você pode fazer?" — permissões concedidas a essa identidade já autenticada. Ex.: essa empresa pode consultar convênio, mas não emitir em nome de outra.

Certificado digital é, na prática, o documento de identidade eletrônico de uma empresa: emitido por uma Autoridade Certificadora credenciada pela ICP-Brasil, ele prova de forma criptográfica que uma requisição realmente partiu do CNPJ que diz ser — sem depender de usuário e senha. Existem duas variantes, com uma diferença bem prática entre elas:

Certificado A1

Um arquivo digital (.pfx), protegido por senha, instalado direto no servidor. Validade de 1 ano. É o mais usado em integrações automatizadas, por não depender de hardware.

Certificado A3

A identidade fica guardada dentro de um cartão ou token USB, e nunca sai dali. Validade de até 3 anos, mais seguro, porém mais difícil de usar em servidores sem um equipamento físico conectado.

mTLS (mutual TLS, "TLS mútuo") é o mecanismo que usa esse certificado para autenticar a empresa já dentro da conexão segura, antes mesmo de qualquer requisição HTTP ser processada. No HTTPS comum, só o servidor se identifica — é o que garante ao seu navegador que ele está falando com a Sefaz de verdade, e não um site falso. No mTLS, o cliente (a empresa) também apresenta o seu próprio certificado, e o servidor o valida antes de aceitar a conexão. É assim que a Sefaz/ADN reconhece qual CNPJ está chamando sem pedir login: a identidade já vem embutida na própria conexão segura.

Nas consultas ao vivo do ADN feitas por esta plataforma — convênio, alíquota, regime especial, retenção & benefício e consolidação — é exatamente esse certificado de cliente que autentica a sua empresa. Já em APIs REST mais modernas (como o login desta própria plataforma), é comum usar OAuth 2.0 em vez de certificado: o cliente autentica uma vez e recebe um token Bearer, que passa a usar no header Authorization em cada requisição subsequente:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Entre com sua conta para testar uma consulta real de convênio e ver a autenticação por certificado (mTLS) em ação.

Nem todo erro de integração vem com um código de status HTTP — muitos acontecem antes mesmo de uma resposta chegar, na camada de conexão TCP/TLS. Reconhecer a mensagem certa ajuda a diagnosticar mais rápido se o problema é seu, da rede, ou do lado do autorizador.

Erros de conexão (antes de qualquer resposta HTTP):

ECONNRESET

A conexão foi encerrada abruptamente pelo outro lado (ou por um proxy/firewall no meio do caminho) enquanto os dados ainda estavam sendo trocados. É comum em web services de Sefaz sob carga, ou quando o cliente demora demais para enviar o payload. Normalmente vale retentar com backoff.

socket hang up

O servidor fechou a conexão antes de enviar qualquer resposta (ou antes dela ser completada) — visto sobretudo em clientes Node.js. Causas típicas: o servidor caiu no meio do processamento, um keep-alive expirou, ou um balanceador/proxy encerrou a conexão ociosa.

ETIMEDOUT / timeout

Nenhuma resposta chegou dentro do tempo configurado. Pode ser lentidão real do autorizador (comum em picos, ex. véspera de fechamento fiscal) ou um timeout configurado baixo demais no seu cliente HTTP para o tipo de operação (lotes de NFe podem demorar mais que uma consulta simples).

ENOTFOUND / DNS

O nome do host não foi resolvido — geralmente URL digitada errada, ambiente trocado (produção vs. homologação) ou uma instabilidade momentânea de DNS. Confira sempre o endereço oficial do autorizador antes de assumir instabilidade.

Erro de handshake TLS / certificado

Falha ao validar o certificado — comum quando o certificado A1/A3 da empresa está vencido, não foi enviado na conexão (mTLS), ou a cadeia de certificação intermediária está incompleta do lado do cliente.

Códigos de status HTTP mais vistos em integrações fiscais:

401 — Unauthorized

Falha de autenticação: certificado não enviado/inválido, token ausente, expirado ou malformado. Não confundir com 403 — aqui o sistema nem reconheceu quem está chamando.

403 — Forbidden

A identidade foi reconhecida, mas não tem permissão para essa ação — ex.: certificado válido, mas de uma empresa que não tem procuração para consultar/emitir em nome de outra, ou tentativa de acessar um recurso fora do escopo autorizado.

404 — Not Found

O endpoint (path) não existe nesse host — normalmente URL errada ou versão de API desatualizada (ex.: endpoint antigo de NFe 3.10 removido após a migração para 4.00).

429 — Too Many Requests

Limite de requisições excedido (rate limit). O autorizador está protegendo a própria infraestrutura — a resposta correta é recuar e retentar com backoff, nunca insistir em loop apertado.

500 — Internal Server Error

Erro genérico do lado do servidor ao processar uma requisição que, pelo que se sabe, era válida. Geralmente vale registrar o payload e retentar; se persistir, é um indicativo de instabilidade do autorizador.

502 / 503 — Bad Gateway / Service Unavailable

O serviço está fora do ar, sobrecarregado ou em manutenção — comum em janelas de manutenção programada dos autorizadores. Normalmente inclui um Retry-After ou é resolvido apenas esperando e retentando.

Na dúvida entre "é erro meu" e "é instabilidade do autorizador": erros de conexão (ECONNRESET, socket hang up, timeout) e 5xx tendem a ser transitórios e justificam retry com backoff; erros 4xx (exceto 429) quase sempre indicam algo a corrigir na própria requisição — payload, credencial ou endpoint — e reenviar sem alterar nada só reproduz o mesmo erro.

• Sempre teste primeiro no ambiente de homologação antes de ir para produção.
• Trate os principais códigos de status (2xx, 4xx, 5xx) explicitamente — não assuma que tudo é sucesso.
• Valide o XML/JSON contra o schema oficial antes de enviar, para não gastar uma tentativa de transmissão com erro de formato.
• Nunca deixe credenciais (certificado, token) hardcoded no código-fonte ou em repositórios.
• Implemente timeout e retry com backoff para lidar com instabilidades momentâneas do lado do órgão.
• Guarde o payload de request e response de cada transmissão fiscal — é sua principal evidência em caso de contestação.