API de integração: visão geral

A API de integração deixa o seu sistema emitir NFS-e sem lidar com XML, assinatura digital ou mTLS. Ela está inclusa em todos os planos e usa os mesmos casos de uso do painel: as mesmas regras fiscais, a mesma cota e a mesma auditoria.

Recursos#

Todas as rotas ficam sob https://emitra.com.br/api/v1/integracao. A chave de API só alcança esse prefixo: ela não acessa as rotas do painel.

Convenções#

• JSON em UTF-8, com Content-Type: application/json.
• Campos em snake_case, em português (tomador_id, competencia, valor).
• Datas em ISO 8601 com fuso: 2026-11-11T10:15:32-03:00. Datas sem hora (competência) em AAAA-MM-DD.
• Dinheiro em string decimal: "1500.00". Nunca envie 1500.0 como número: ponto flutuante perde centavos.
• Envelope de resposta igual em todas as rotas:

{ "status": "success", "message": "Operação realizada com sucesso", "data": { } }

{ "status": "error", "message": "Chave de idempotência já usada com outro corpo", "code": "IDEMPOTENCY_KEY_REUSED", "details": null }

Decida sempre pelo code, que é estável. O message é para leitura humana e pode mudar. Veja Erros.

Fluxo de uma emissão#

Seu sistema                     Emitra                          Sefin Nacional
    │ POST /nfse (Idempotency-Key) │                                  │
    │─────────────────────────────►│ valida, reserva o número         │
    │◄──────── 202 {id, queued} ───│                                  │
    │                              │ monta, valida (XSD) e assina     │
    │                              │──────── DPS (mTLS) ─────────────►│
    │                              │◄─────── NFS-e ou rejeição ───────│
    │◄──── webhook nfse.authorized │                                  │
    │ GET /nfse/{id}/xml           │                                  │

1. Você envia a DPS e recebe 202 Accepted com o id e status: "queued".
2. A Emitra processa em fila: valida contra o XSD, assina e transmite.
3. Em falha técnica (timeout, indisponibilidade), a Emitra tenta de novo com espera crescente. Antes de reenviar, ela consulta a Sefin pelo Id da DPS, para nunca gerar nota em duplicidade.
4. O resultado chega por webhook ou por consulta a GET /nfse/{id}.

O que a API valida antes de aceitar#

O POST /nfse responde com erro imediato (sem 202) quando:

• o corpo é inválido (VALIDATION_ERROR) ou falta o Idempotency-Key;
• a empresa não tem certificado ativo e válido ou configuração fiscal;
• a cota do plano acabou (COTA_EXCEDIDA) ou a assinatura está bloqueada (TENANT_INADIMPLENTE);
• a chave não tem o escopo nfse:emit.

As regras fiscais da Sefin (alíquota, retenção, convênio do município etc.) só são conhecidas na transmissão. Elas aparecem como status: "rejected" com o código oficial.

OpenAPI#

O contrato formal fica em https://emitra.com.br/api/v1/integracao/openapi.json, que expõe só as rotas públicas.

Próximos passos#

• Autenticação e escopos
• Ambientes e URLs base
• Quickstart da API