Como emitir NF-e por finalidade (purposeType)

Este guia mostra o payload completo para emitir NF-e em cada uma das 6 finalidades de emissão. Todas usam o mesmo endpoint:

POST /v2/companies/{companyId}/productinvoices

Para o contrato técnico completo de cada valor (campos, validações, códigos de erro), veja Finalidade de emissão da NF-e (purposeType). Para entender quando usar cada finalidade, veja Quando usar cada finalidade de emissão da NF-e.

Emissão normal

Use para qualquer venda ou operação que não precise referenciar um documento fiscal anterior.

POST .../productinvoices — purposeType Normal

{
  "purposeType": "Normal",
  "operationType": "Outgoing",
  "operationNature": "Venda de mercadoria",
  "items": [
    {
      "code": "P001",
      "description": "Produto exemplo",
      "ncm": "61091000",
      "cfop": "5102",
      "unit": "UN",
      "quantity": 1,
      "unitAmount": 100.00
    }
  ]
}

Checklist: nenhum campo adicional além dos exigidos em qualquer emissão.

Nota complementar

Use quando uma NF-e já autorizada ficou com valor ou informação faltando (ex.: diferença de preço, ajuste de imposto) e você precisa complementá-la — sem cancelar a original.

POST .../productinvoices — purposeType Complement

{
  "purposeType": "Complement",
  "operationType": "Outgoing",
  "operationNature": "Complemento de ICMS",
  "additionalInformation": {
    "taxDocumentsReference": [
      {
        "documentElectronicInvoice": {
          "accessKey": "3126064211841000018155001000000566189287266"
        }
      }
    ]
  },
  "items": [
    {
      "code": "P001",
      "description": "Complemento de valor de ICMS",
      "cfop": "5102",
      "unit": "UN",
      "quantity": 1,
      "unitAmount": 10.00
    }
  ]
}

Checklist:

• additionalInformation.taxDocumentsReference[].documentElectronicInvoice.accessKey com a chave de 44 dígitos da NF-e original — referência no cabeçalho, não por item.

Nota de ajuste

Use para ajustes que a legislação estadual prevê fora do fluxo normal de venda. Não identificamos, até o momento, exigência de referência a documento original para esta finalidade — confirme com o suporte antes de depender disso em produção.

POST .../productinvoices — purposeType Adjustment

{
  "purposeType": "Adjustment",
  "operationType": "Outgoing",
  "operationNature": "Ajuste de estoque",
  "items": [
    {
      "code": "P001",
      "description": "Ajuste",
      "cfop": "5949",
      "unit": "UN",
      "quantity": 1,
      "unitAmount": 0.01
    }
  ]
}

Checklist: nenhuma exigência adicional confirmada.

Nota de devolução

Use quando o cliente devolve mercadoria recebida em uma NF-e anterior. Diferente da nota complementar, a referência à NF-e original é por item, não no cabeçalho — e passou a ser obrigatória desde a NT 2025.002-RTC.

POST .../productinvoices — purposeType Devolution

{
  "purposeType": "Devolution",
  "operationType": "Incoming",
  "operationNature": "Devolução de mercadoria",
  "items": [
    {
      "code": "P001",
      "description": "Produto devolvido",
      "cfop": "5202",
      "unit": "UN",
      "quantity": 1,
      "unitAmount": 100.00,
      "referencedDFe": {
        "accessKey": "3126064211841000018155001000000566189287266",
        "itemNumber": 1
      },
      "tax": {
        "ipiDevol": {
          "percentage": 100,
          "amount": 18.25
        }
      }
    }
  ]
}

Checklist:

• items[*].referencedDFe.accessKey + items[*].referencedDFe.itemNumber em cada item devolvido — obrigatório em homologação desde 01/09/2026 e em produção desde 05/10/2026.
• items[*].tax.ipiDevol apenas se houver IPI a devolver — não é obrigatório em toda devolução.
• CFOP: não há CFOP único obrigatório imposto pela API. A escolha segue a tabela de CFOP vigente para devolução (ex.: 5202/6202 para devolução de compra para comercialização, 5411/6411 para devolução de compra para industrialização, 7202 para devolução em operação com o exterior) — confira com a sua área fiscal qual se aplica à operação. Veja mais em Quando usar cada finalidade de emissão da NF-e.

Não referencie pelo cabeçalho

Para devolução, não envie additionalInformation.taxDocumentsReference — a referência por cabeçalho é proibida nessa finalidade. Use apenas items[].referencedDFe.

Veja o contrato completo em Devolução de NF-e por item — NT 2025.002-RTC.

Nota de Crédito e Nota de Débito

São NF-e autônomas com numeração própria — não eventos sobre a nota original. Exigem um subtipo (creditType ou debitType) que qualifica o cenário, e a NFE.io não recalcula os tributos: o valor informado é o que vai para o XML.

POST .../productinvoices — purposeType CreditInvoice

{
  "purposeType": "CreditInvoice",
  "creditType": "RefusedDeliveryTotalOrNotFound",
  "operationType": "Incoming",
  "operationNature": "Retorno por recusa de mercadoria",
  "additionalInformation": {
    "taxDocumentsReference": [
      { "documentElectronicInvoice": { "accessKey": "31260642118410000181550010000005661892872660" } }
    ]
  }
}

Checklist:

• creditType (para CreditInvoice) ou debitType (para DebitInvoice) sempre presente — a API recusa a emissão sem o subtipo.
• Referência à NF-e original no formato exigido pelo subtipo (cabeçalho ou por item, dependendo do cenário).

Veja o contrato completo (todos os subtipos, payload de cada um, erros de validação) em Notas de Crédito e Notas de Débito.

Veja também

• Finalidade de emissão da NF-e (purposeType) — referência técnica do enum
• Quando usar cada finalidade de emissão da NF-e — casos de uso e CFOP de devolução
• Devolução de NF-e por item — NT 2025.002-RTC
• Notas de Crédito e Notas de Débito