NFCom via API: como integrar a emissão ao seu sistema de faturamento

Integrar a NFCom via API significa fazer o seu sistema de faturamento enviar os dados das notas a um emissor por chamadas HTTP (REST, em JSON), em vez de digitar ou importar arquivos. O emissor cuida da parte fiscal: monta o XML modelo 62, assina com o certificado digital, transmite à SEFAZ, trata o retorno e gera o DANFE-COM. O seu sistema só precisa autenticar, enviar as notas, acompanhar o status e buscar os arquivos autorizados.

Este guia mostra quando a API é a melhor escolha, como é o fluxo completo na API de NFCom da SyncNFe e quais boas práticas evitam os problemas mais caros de uma integração: notas duplicadas, reenvios em excesso e status desencontrados. Para o panorama geral, veja o guia completo de NFCom.

NFCom via API ou integração nativa: qual escolher?

Nem todo provedor precisa de API. Se o faturamento roda em um sistema de gestão que já tem integração pronta com o emissor, a integração nativa costuma ser mais rápida de colocar em produção.

Uma vantagem importante da API é que o seu sistema não precisa gerar o XML. Montar o XML na mão exige acompanhar schema, notas técnicas e regras de assinatura, como mostra o exemplo comentado de XML da NFCom. Pela API, você envia dados estruturados e o emissor faz o resto.

Como integrar a NFCom via API: visão geral do fluxo

1. Autenticar e obter o token de acesso.
2. Inserir as notas da competência, várias por chamada.
3. Liberar o envio à SEFAZ (na inserção ou depois, em lote).
4. Acompanhar o status até autorização ou rejeição.
5. Baixar XML e PDF e enviar ao assinante por e-mail.
6. Tratar exceções: corrigir rejeitadas, cancelar quando necessário.

As rotas citadas abaixo são as da documentação pública da API de Integração SyncNFe, que oferece servidores de produção e de sandbox e trabalha com JSON em UTF-8. Nomes de campos, métodos e formatos exatos devem ser sempre conferidos na documentação.

1. Autenticação com token Bearer

A autenticação é feita em POST /V1/autenticacao/login, que devolve um token do tipo Bearer. Esse token vai no cabeçalho Authorization das chamadas seguintes e expira em 3.600 segundos (uma hora).

• Guarde o token em memória ou cache e reutilize até perto da expiração; não faça login a cada nota.
• Renove de forma proativa ou ao receber resposta de não autorizado, e repita a chamada original uma única vez.
• Credenciais ficam em variáveis de ambiente ou cofre de segredos, nunca no código-fonte ou em logs.

2. Inserir notas (várias por chamada)

A rota /V1/nfcom/notas-fiscais/inserir aceita várias notas na mesma requisição, o que reduz o número de chamadas no fechamento da competência. A opção liberarEnvioAoInserir define se as notas já seguem para a SEFAZ ou se ficam aguardando uma liberação posterior (rotas liberar-envio e liberar-envio-lote).

Um esqueleto ilustrativo da chamada, só para visualizar o formato:

POST {servidor}/V1/nfcom/notas-fiscais/inserir
Authorization: Bearer {token}
Content-Type: application/json; charset=utf-8

{
  "liberarEnvioAoInserir": false,
  "...": "lista de notas e demais campos conforme a documentação da API"
}

Inserir sem liberar o envio é útil para conferir o lote antes de transmitir: o financeiro revisa, o sistema libera tudo de uma vez e só então as notas vão à SEFAZ. Enquanto não foram enviadas, as notas podem ser ajustadas (alterar) ou removidas (excluir).

3. Consultar o status das notas

A transmissão à SEFAZ é assíncrona do ponto de vista do seu sistema: a nota é enfileirada, processada em segundo plano e, depois, fica autorizada, rejeitada ou pendente. Para acompanhar, a API oferece:

• consultar: lista notas com filtros;
• detalhar/{guid}: dados completos de uma nota pelo seu identificador;
• consultar-status-sefaz: situação do serviço da SEFAZ;
• contadores-status: totais por situação, úteis para um painel de acompanhamento.

Em integrações de documentos fiscais há dois modelos para saber quando uma nota mudou de situação: polling (o seu sistema consulta periodicamente) e webhooks (o emissor avisa o seu sistema), quando disponíveis. Com polling, use intervalos crescentes e consulte só o que ainda está pendente; com qualquer modelo, trate a consulta como fonte da verdade antes de tomar decisões como reenviar ou cancelar.

4. Baixar XML e PDF e enviar ao assinante

Com a nota autorizada, o seu sistema pode:

• baixar o XML autorizado (baixar-xml) para arquivo e envio a clientes empresariais;
• baixar o DANFE-COM em PDF (baixar-impressao-pdf) para anexar à fatura ou à central do assinante;
• disparar o e-mail com os documentos pelo emissor (enviar-email ou enviar-emails-lote).

A mesma API também dá acesso aos arquivos DICI, SPED e Sintegra gerados a partir das notas, o que evita exportações manuais no fechamento do mês.

5. Cancelar notas

O cancelamento é feito por cancelar/{guid}, informando o motivoCancelamento, ou por cancelar-lote para várias notas. Por trás, o emissor registra na SEFAZ o evento de cancelamento (110111). O prazo para cancelar é definido pela legislação e pelo MOC e pode variar; depois dele, o caminho costuma ser a nota de substituição ou de ajuste. Os detalhes estão em como cancelar NFCom.

Sandbox: teste antes de produção

A API tem um servidor de sandbox separado do de produção. Use-o para validar autenticação, montagem das notas, tratamento de rejeições e o fluxo de reenvio. Boas práticas de teste:

• mantenha URL e credenciais de cada ambiente em configuração, nunca fixas no código;
• teste casos de erro de propósito (CPF inválido, município sem código IBGE, totais divergentes);
• simule falhas de rede e verifique se o seu sistema não duplica notas ao tentar de novo;
• só aponte para produção depois de um ciclo completo sem pendências.

Boas práticas para integrar a API de NFCom

Idempotência: uma cobrança, uma nota

Grave no seu banco, para cada fatura, o identificador (guid) devolvido pelo emissor. Antes de enviar de novo, verifique se aquela fatura já tem nota. Timeout de rede não significa que a nota não foi criada: consulte antes de repetir.

Não reenviar em duplicidade

Os retornos 204 e 539 indicam duplicidade: a nota já existe na SEFAZ. A reação correta é consultar pela chave e recuperar a situação, não gerar outro número.

Respeitar o 678 (consumo indevido)

O código 678 aparece quando há requisições repetidas em excesso. Aguarde antes de tentar de novo e aplique backoff (intervalos crescentes) nas consultas e reenvios.

Fila e processamento em segundo plano

Não prenda a tela do usuário esperando a SEFAZ. Enfileire o envio, processe em segundo plano e mostre o status. O emissor SyncNFe já trabalha com fila por empresa e reenvio automático em falhas transitórias, como serviço paralisado (108/109); do seu lado, evite criar um segundo mecanismo de reenvio que concorra com o do emissor.

Logs e rastreabilidade

Registre o identificador da nota, a fatura de origem, o status e o motivo de rejeição, sem gravar tokens ou dados sensíveis em texto aberto. Para interpretar e corrigir rejeições, use NFCom rejeitada: códigos e soluções.

Checklist de go-live da integração

• Token reaproveitado e renovado antes de expirar.
• Envio em lote com opção de revisão antes da liberação.
• Identificador de cada nota gravado junto da fatura (idempotência).
• Consulta antes de qualquer reenvio; tratamento de 204, 539 e 678.
• Download de XML e PDF e envio ao assinante automatizados.
• Cancelamento com motivo registrado e trilha de auditoria.
• Ciclo completo validado no sandbox.

Para organizar o fechamento mensal com muitos assinantes, veja também como emitir NFCom em lote. E, se quiser avaliar a API com os dados da sua operação, acesse a documentação da API de NFCom ou faça um teste grátis.

Conteúdo informativo. Regras de tributação, CFOP, CST e prazos variam por UF e mudam com novas notas técnicas; valide o enquadramento da sua operação com a contabilidade e a SEFAZ competente. Base normativa: Ajuste SINIEF 7/22 e Portal da NFCom (SVRS).