Guia: Emitir NFe

Guia completo para emitir uma Nota Fiscal Eletrônica (NFe) via Engine API. Todos os campos, regimes tributários e tratamento de erros.

Emitir NFe

Emita uma Nota Fiscal Eletrônica (NFe, modelo 55) e transmita para a SEFAZ em uma única chamada REST.

Endpoint: POST https://api.engineapi.com.br/nfe/emitir

Pré-requisitos

Conta criada

Registre-se em app.engineapi.com.br e obtenha seu token via POST /auth/login.

Empresa cadastrada

Cadastre o CNPJ emissor via POST /companies. Guarde o id retornado. Esse é o issuerId.

Certificado digital enviado

Faça upload do .pfx via POST /companies/{issuerId}/certificate. Sem certificado, a emissão falha.

Ambiente definido

Use environment: 2 na empresa para homologação e environment: 1 para produção.

Notas em homologação (environment: 2) são transmitidas para o SEFAZ de teste e não têm validade fiscal. Use para testar sem risco.

Exemplos de Request

bash

curl -X POST https://api.engineapi.com.br/nfe/emitir \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "issuerId": "ISSUER_ID",
    "naturezaOperacao": "VENDA DE MERCADORIA",
    "destinatario": {
      "cnpj": "99888777000155",
      "nome": "Cliente Exemplo SA",
      "endereco": {
        "logradouro": "Av Brasil",
        "numero": "500",
        "bairro": "Centro",
        "codigoMunicipio": "3550308",
        "municipio": "São Paulo",
        "uf": "SP",
        "cep": "01001000"
      },
      "indicadorIE": 1
    },
    "itens": [{
      "numero": 1,
      "codigo": "PROD001",
      "descricao": "Camiseta Algodão P",
      "ncm": "61091000",
      "cfop": "5102",
      "unidade": "UN",
      "quantidade": 2,
      "valorUnitario": 59.90,
      "valorTotal": 119.80,
      "icms": {
        "origem": 0,
        "cst": "00",
        "aliquota": 18,
        "baseCalculo": 119.80,
        "valor": 21.56
      }
    }],
    "pagamento": { "forma": "01", "valor": 119.80 }
  }'

ICMS por Regime Tributário

O campo icms muda conforme o regime da empresa emissora:

Campos de Referência

Raiz

| Campo | Tipo | Obrigatório | Descrição | |-------|------|-------------|-----------| | issuerId | string (UUID) | Sim | ID da empresa emissora | | naturezaOperacao | string | Sim | Ex: "VENDA DE MERCADORIA" | | destinatario | objeto | Sim | Dados do destinatário | | itens | array | Sim | Mínimo 1 item | | pagamento | objeto | Sim | Forma e valor | | observacoes | string | — | Informações adicionais |

Destinatário

| Campo | Tipo | Obrigatório | Descrição | |-------|------|-------------|-----------| | cnpj ou cpf | string | Sim (um) | Documento do destinatário | | nome | string | Sim | Razão social ou nome | | indicadorIE | número | Sim | 1=contribuinte, 2=isento, 9=não contribuinte | | inscricaoEstadual | string | — | IE quando indicadorIE: 1 | | endereco.* | objeto | Sim | Endereço completo |

Item

| Campo | Tipo | Obrigatório | Descrição | |-------|------|-------------|-----------| | numero | número | Sim | Sequencial do item (1, 2, 3...) | | codigo | string | Sim | Código interno do produto | | descricao | string | Sim | Descrição do produto | | ncm | string | Sim | 8 dígitos — Nomenclatura Comum do Mercosul | | cfop | string | Sim | 4 dígitos — ver CFOP | | unidade | string | Sim | UN, KG, MT, CX, etc. | | quantidade | número | Sim | Quantidade | | valorUnitario | número | Sim | Valor por unidade em R$ | | valorTotal | número | Sim | quantidade × valorUnitario | | icms | objeto | Sim | Dados tributários do item |

Ciclo de vida da NFe

mermaid

stateDiagram-v2
    [*] --> PROCESSING : POST /nfe/emitir
    PROCESSING --> AUTHORIZED : SEFAZ aprova
    PROCESSING --> REJECTED : SEFAZ rejeita
    AUTHORIZED --> CANCELLED : POST /nfe/{id}/cancelar (até 24h)
    REJECTED --> PROCESSING : Corrige e reenvia
    CANCELLED --> [*]
    AUTHORIZED --> [*] : XML + PDF disponíveis

    AUTHORIZED : ✅ AUTHORIZED
    REJECTED : ❌ REJECTED
    PROCESSING : ⏳ PROCESSING
    CANCELLED : 🚫 CANCELLED

Response de sucesso

json

{
  "success": true,
  "invoice": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "accessKey": "35260211222333000144550010000000011000000019",
    "number": 1,
    "series": 1,
    "status": "AUTHORIZED",
    "protocol": "135260000001234",
    "danfeUrl": "/nfe/3fa85f64.../danfe",
    "createdAt": "2026-04-26T18:30:00.000Z"
  }
}

| Status | Significado | Ação | |--------|-------------|------| | AUTHORIZED | Aprovada pela SEFAZ | Nenhuma. Nota válida | | REJECTED | Rejeitada | Corrija e reenvie | | PROCESSING | Em processamento | Consulte via GET /nfe/{id} | | CANCELLED | Cancelada | Nota cancelada |

Tratamento de Erros

Rejeição SEFAZ (422)

json

{
  "statusCode": 422,
  "message": "Rejeição 539: Duplicidade de NFe",
  "sefazCode": 539,
  "sefazMessage": "Duplicidade de NFe, com diferença na Chave de Acesso"
}

Rejeições SEFAZ retornam 422 com os campos sefazCode e sefazMessage. Use o sefazCode para consultar a tabela oficial de rejeições da Fazenda.

Webhook após emissão

A Engine API dispara automaticamente um evento invoice.authorized quando a SEFAZ aprova:

json

{
  "event": "invoice.authorized",
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "accessKey": "35260211222333000144550010000000011000000019",
    "status": "AUTHORIZED",
    "issuerId": "ISSUER_ID"
  },
  "timestamp": "2026-04-26T18:30:00.000Z"
}

Configure seus webhooks em Dashboard → Configurações → Webhooks ou via guia de webhooks.

Próximos passos

xmark

Cancelar NFe

Cancelamento em até 24h após a autorização

pencil

Carta de Correção

Corrija dados sem cancelar a nota

bell

Webhooks

Receba notificações automáticas em tempo real