API Fiscal para desenvolvedores: como integrar NF-e em 30 minutos

Integrar emissão de NF-e em um sistema próprio (ERP, e-commerce, PDV, SaaS) exige entender o protocolo da SEFAZ, assinar XML com certificado digital e tratar as 90+ rejeições do layout 4.01. A API REST da Délfica encapsula tudo isso em uma chamada HTTP — você envia JSON, recebe JSON, e nós cuidamos da complexidade fiscal.

O que dá para fazer via API

• Emitir NF-e, NFC-e, CT-e, MDF-e e NFS-e a partir de um JSON com dados do emitente, destinatário, produtos, transporte e pagamento.
• Cancelar, substituir (CCE) e inutilizar numeração de NF-e com protocolo de autorização.
• Consultar status em tempo real (autorizada, rejeitada, cancelada, denegada) por chave de acesso.
• Receber webhooks com eventos de emissão, rejeição, cancelamento, autorização e atualização de cadastro. Sem polling.
• Importar XMLs de fornecedores e classificá-los automaticamente (insumo, ativo, mercadoria, serviço).
• Simular regimes tributários e antecipar o impacto da Reforma Tributária 2026/2027.
• Usar a IA fiscal para sugerir CFOP, NCM e corrigir rejeições SEFAZ em linguagem natural.

Como integrar em 30 minutos

1. Crie uma conta de serviço

Acesse /developers.html e crie uma conta de serviço. Você recebe um client_id e client_secret com escopos restritos (emissão, leitura, webhook). Veja o fluxo OAuth 2.0 + PKCE em /developers/api/AUTH.md.

2. Faça a primeira chamada

Autentique via POST /oauth/token e obtenha um Bearer token. Em seguida, faça POST /v1/nfe com o JSON da nota:

curl -X POST https://api.delfica.com.br/v1/nfe \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ambiente": "producao",
    "empresa": { "cnpj": "12345678000199" },
    "destinatario": { "cnpj_cpf": "98765432000111", "nome": "Cliente LTDA" },
    "itens": [
      { "sku": "ABC-001", "descricao": "Caneta esferográfica azul", "ncm": "96086000",
        "cfop": "6102", "quantidade": 10, "valor_unitario": 1.50 }
    ],
    "pagamento": { "forma": "pix", "valor": 15.00 }
  }'

3. Receba a resposta

A API responde com 202 Accepted e o protocolo de envio. Em segundos, você recebe um webhook nfe.authorized com o XML, a chave de acesso e a DANFE em PDF. Para checar manualmente: GET /v1/nfe/{chave}.

4. Trate erros e retentativas

Use o SDK Python oficial, com retry exponencial, HMAC de webhook e helpers para as 90+ rejeições SEFAZ. O SDK já cuida de timeout, idempotência e circuit breaker em SEFAZ fora do ar.

Casos de uso comuns

ERP e SaaS contábil

Sincronize clientes, produtos e notas com a Délfica via API. Cada NF-e emitida no ERP vai para a SEFAZ sem o usuário perceber. O webhook customer.updated avisa quando o cadastro muda (novo IE, mudança de regime).

E-commerce e marketplaces

A cada pedido aprovado, emita NF-e automaticamente. Integre com Shopify (app oficial), Nuvemshop (Partners), VTEX (master_dados), Mercado Livre, Shopee, Amazon e Magalu via API + webhooks.

PDV e retaguarda

Para varejo, NFC-e com contingência offline (FS-DA). Quando a SEFAZ volta, a Délfica transmite a fila automaticamente. Para atacado, NF-e com múltiplos itens e transporte.

Segurança e conformidade

• OAuth 2.0 + PKCE para autenticação de usuários finais.
• Bearer tokens para contas de serviço, com escopos restritos.
• HMAC SHA-256 em webhooks para validar origem.
• OpenAPI 3.1 para descrição completa da API, com exemplos de request/response.
• LGPD: dados pessoais não ficam em logs, e há política de retenção mínima.

Quanto custa

A API está inclusa no plano único da Délfica (R$ 150/mês), com limite de 10.000 chamadas/mês e 1.000 webhooks/mês. Para volumes maiores, fale com nosso time para um pacote sob medida. Sem cobrança por NF-e emitida.

Veja a referência completa em /developers.html e baixe o SDK Python e o guia de integração de NF-e.