Pular para o conteúdo

Para software houses e ERPs

Integre emissão fiscal ao seu ERP com uma API REST.

API para NF-e, NFC-e e NFS-e (Padrão Nacional; provedor São Paulo disponível na API), com OAuth2, processamento assíncrono, webhooks e recebimento de DF-e.

Em operação em produção (NF-e, NFC-e e NFS-e Nacional) · acesso assistido. Disponibilidade conforme documento e cenário; condições comerciais sob consulta.

Do envio ao resultadoHomologação
cURL · Requisição resumida
# Empresa configurada em homologação, com certificado A1
# Payload completo em arquivo local; obtenha antes o token
curl --request POST \
  "${BASE_URL}/api/v1/empresas/${EMPRESA_ID}/nfe" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data @nfe-homologacao.json

JSON · HTTP 202 — resposta resumida
{
  "id": 29,
  "status": "pendente"
}

Aceite para processamento não significa autorização fiscal.

cURL · Consulta do estado local
# Use o id retornado no envio
curl "${BASE_URL}/api/v1/nfe/${NOTA_ID}" \
  --header "Authorization: Bearer ${TOKEN}"

Consulta NF-e usa cStat; webhook fiscal usa recurso.cstat. Consulte também os arquivos disponíveis.

Exemplos resumidos, sem chamada à API. Confira pré-requisitos, campos e payloads na documentação. O ambiente é definido na empresa/documento.

  • REST / JSON
  • OAuth2 com scopes
  • Webhooks assinados
  • Motor fiscal próprio sobre NFePHP
Uma integração começa pela cobertura.

Implementação, homologação comprovada e liberação comercial são etapas distintas. Confirme documento, operação, UF ou município e ambiente.

Arquitetura e recursos

Feito para integrar

Recursos técnicos implementados. Homologação e liberação comercial dependem do documento e do cenário.

API REST + OAuth2

Autenticação client_credentials (Passport). Escopos por operação: emitir, consultar, cancelar e gerenciar.

Emissão assíncrona

A emissão aceita retorna 202 com o id; a transmissão ao autorizador é processada em fila.

Webhooks assinados

Notificação no status final da nota, com assinatura HMAC-SHA256 e auditoria de entregas.

Multi-tenant

Uma conta (integrador) com várias empresas. A credencial só enxerga as empresas da sua conta.

Arquivos fiscais

Armazenamento de XML e PDFs disponíveis. Retenção e condições sob confirmação; imutabilidade, cifragem e backup sob consulta.

Créditos de emissão

Débito no enfileiramento; estorno em erro, rejeição ou denegação; novo débito no reenvio. Estorno inicial de NFC-e a confirmar. Condições comerciais sob consulta.

Certificado A1 cifrado

Certificado e senha usam campos cifrados no banco e não são retornados pela API de cadastro.

Motor fiscal próprio

Integração fiscal própria com componentes NFePHP para montagem, assinatura e comunicação, conforme o documento.

Idempotência

request_id identifica uma emissão existente por empresa. Correção de nota rejeitada ou com erro usa a rota de reenvio.

Recebimento de DF-e

Receba as NF-e emitidas contra o seu CNPJ (Distribuição do Ambiente Nacional) e manifeste: ciência, confirmação, desconhecimento ou operação não realizada.

Validador de XML

Validação offline de estrutura, schema XSD e assinatura digital, conforme o tipo de XML. Não consulta o autorizador; condições de uso sob consulta.

E-mail automático

Envio configurável ao destinatário após autorização: XML e, para NF-e/NFC-e, PDF. Pacote mensal de XMLs ao contador depende de configuração e execução da rotina.

Documentos e cobertura

Implementação com limites explícitos

NF-e, NFC-e e NFS-e têm rotas implementadas. A disponibilidade depende do documento e do cenário, sob consulta.

NF-e

Modelo 55

Nota fiscal eletrônica de mercadoria. Emissão, consulta e DANFE em PDF, transmitida direto à SEFAZ. Eventos em implementação.

No código
Implementado
Homologação comprovada
Validação a confirmar
Produção / liberação comercial
Em operação

NFC-e

Modelo 65

Cupom fiscal eletrônico do consumidor. QR Code automático (CSC), múltiplas formas de pagamento e DANFE em cupom 58/80mm. Eventos em implementação.

No código
Implementado
Homologação comprovada
Validação a confirmar
Produção / liberação comercial
Em operação

NFS-e Nacional

Serviços · DPS/ADN

Emissão, consulta do estado local e XML. Não há geração de DANFSe. Cancelamento em implementação.

No código
Implementado
Homologação comprovada
Validação a confirmar
Produção / liberação comercial
Em operação

NFS-e São Paulo (Nota Paulistana)

Serviços · RPS

Provedor disponível na API (emissão, consulta e XML pelo RPS da Prefeitura de São Paulo). Prefeituras no CNC migram para o padrão nacional. Não há geração de DANFSe. Cancelamento em implementação.

No código
Implementado
Homologação comprovada
Validação a confirmar
Produção / liberação comercial
Disponível na API; prefeituras no CNC migram para o padrão nacional; sob consulta

Recebimento de DF-e

Distribuição e manifestação

Receba NF-e emitidas contra o CNPJ e manifeste ciência, confirmação, desconhecimento ou operação não realizada.

No código
Implementado
Homologação comprovada
Validação a confirmar
Produção / liberação comercial
Disponível na API, em validação; sob consulta
Em implementação

Eventos fiscais (cancelamento, carta de correção, inutilização e semelhantes) estão em implementação.

Futuro

CT-e, CT-e OS, MDF-e, NFCom, DC-e e consultas CEP/CNPJ são recursos futuros. Geração de DANFSe também é futura; a API de NFS-e serve PDF somente quando o arquivo já existe.

Do envio ao resultado fiscal

Fluxo técnico de integração

Acesso assistido. Os exemplos pressupõem empresa em homologação, com certificado e provedor configurados.

  1. Obtenha o token

    Troque seu client_id e client_secret por um token em /oauth/token.

  2. Cadastre a empresa

    Crie a empresa e envie o certificado A1 (cifrado). Configure o CSC se for emitir NFC-e.

  3. Emita o documento

    Envie o JSON para a rota do documento. A emissão aceita retorna o id para acompanhamento; autorização é uma etapa posterior.

  4. Receba o webhook

    Com webhook configurado, mudanças para status final geram callback assinado. Consulte o resultado e os arquivos disponíveis; NFS-e não gera DANFSe.

Multiempresa

Uma conta, várias empresas

A credencial só enxerga as empresas da sua conta. O ambiente fiscal acompanha a empresa/documento.

Diagnóstico

Separe processamento de resultado fiscal

O retorno 202 aceita o envio para a fila. Consulte o estado e o motivo fiscal antes de repetir uma emissão. request_id identifica uma emissão existente por empresa.

Consultar erros e rejeições

Webhooks assinados

Valide a assinatura HMAC-SHA256 e confirme a entrega com HTTP 2xx. Notificações acompanham o status final da nota.

Ver o contrato de webhooks

Créditos e condições

Condições comerciais sob consulta

Preços, suporte e condições de atendimento sob consulta. Retenção e condições dos arquivos sob confirmação; imutabilidade, cifragem e backup sob consulta.

Em operação em produção (NF-e, NFC-e e NFS-e Nacional) · acesso assistido.

Como a emissão movimenta créditos

Débito no enfileiramento; estorno em erro, rejeição ou denegação; novo débito no reenvio. Estorno inicial de NFC-e a confirmar.

402 indica saldo insuficiente, separado de rejeição fiscal. Em 429, respeite Retry-After.

Downloads não implementam débito por repetição; condições comerciais sob consulta.

Consultar créditos na documentação

Próximo passo

Consulte o contrato da API

Confira os pré-requisitos, as rotas e a cobertura do seu cenário. Em operação em produção (NF-e, NFC-e e NFS-e Nacional) · acesso assistido.