Docs/NF-e
NF-e — Nota Fiscal Eletrônica (produtos)
Endpoints para emissão, consulta e cancelamento de NF-e de produtos. A emissão é sempre em produção (SEFAZ tpAmb=1).
Headers
X-Api-Key
stringobrigatórioChave de API da conta (id do usuário).
X-Api-Secret
stringobrigatórioSegredo da chave de API.
Content-Type
stringobrigatórioapplication/json
Parâmetros do body
nature
stringopcionalNatureza da operação.
cfop
stringopcionalCFOP padrão dos itens.
items
arrayobrigatórioItens da nota. Aceita DNA fiscal completo (espelha a UI Novo produto). A emissão usa o DNA do item — sem herdar defaults da empresa.
description
stringobrigatórioTexto curto do item (máx. 120). Compat legado.
name
stringopcionalNome no catálogo (3–64). Default: slice de fiscalDescription/description.
fiscalDescription
stringopcionalDescrição na NF-e (xProd). Default: description.
category
stringopcionalCategoria (ex.: digital_book, software, other_product). Default: other_product.
sku
stringopcionalSKU do item.
ncm
stringopcionalNCM (8 dígitos).
commercialUnit
stringopcionalUnidade comercial (ex.: UN). Alias legado: unit.
cfopInternal
stringopcionalCFOP vendas dentro do estado. Alias legado: cfop.
cfopExternal
stringopcionalCFOP vendas fora do estado.
icmsCst
stringopcionalCST/CSOSN ICMS.
icmsTaxRate
numberopcionalAlíquota ICMS (%).
pisCst
stringopcionalCST PIS.
cofinsCst
stringopcionalCST COFINS.
taxClassification
stringopcionalClassificação tributária IBS/CBS.
icmsTaxBenefitCode
stringopcionalcBenef — código de benefício fiscal da UF (8 ou 10 caracteres, ou "SEM CBENEF"; algumas UFs, como SC, rejeitam o literal).
presumedCredits
arrayopcionalgCred — crédito presumido de ICMS da UF (até 4 por item). Vale só para esta nota (não grava no cadastro). Aceitação depende da UF (rejeições 507/664).
code
stringobrigatóriocCredPresumido — código da tabela da UF (8 ou 10 caracteres).
rate
numberobrigatóriopCredPresumido — percentual (0–100, até 4 casas decimais).
value
numberopcionalvCredPresumido — valor (até 2 casas). Ausente: calculado como (vProd − desconto rateado do item) × rate / 100.
quantity
numberobrigatórioQuantidade.
unitValue
numberobrigatórioValor unitário em reais.
recipient
objectobrigatórioDados do destinatário.
taxId
stringobrigatórioCPF ou CNPJ do destinatário.
name
stringobrigatórioNome do destinatário.
E-mail do destinatário. Obrigatório: o destinatário vira cadastro de cliente (sem e-mail → 422 em recipient.email).
phone
stringopcionalTelefone.
address
objectopcionalEndereço (se enviar um campo, envie todos): street, number, complement?, district, city, state, zipcode, cityCode? (IBGE).
paymentMethod
stringopcionalForma de pagamento (tPag): pix, credit_card, debit_card, cash, bank_slip, bank_transfer, other ou no_payment. Omitido: credit_card.
externalId
stringopcionalIdentificador externo para idempotência.
transport
objectopcionalDados de transporte inline. Não há cadastro de transportadora: os dados vão no payload e ficam congelados no snapshot da nota. freightModality é obrigatório quando carrier é enviado; noShipping com carrier retorna 422 (VALIDATION_ERROR).
freightModality
stringopcionalModalidade do frete: bySender, byRecipient, byThirdParties, ownBySender, ownByRecipient ou noShipping. Também aceita os códigos SEFAZ 0/1/2/3/4/9. Obrigatório quando carrier é enviado.
value
numberopcionalValor do frete (≥ 0). Compõe o total da nota quando o frete é por conta do emitente.
carrier
objectopcionalTransportadora (inline).
name
stringobrigatórioRazão social ou nome da transportadora.
taxId
stringobrigatórioCNPJ ou CPF válido da transportadora.
stateRegistration
stringopcionalInscrição estadual.
address
objectopcionalEndereço da transportadora.
street
stringopcionalLogradouro.
city
stringopcionalCidade.
state
stringopcionalUF (ex.: SP).
vehicle
objectopcionalVeículo do transporte.
plate
stringobrigatórioPlaca do veículo.
state
stringopcionalUF de registro do veículo.
rntc
stringopcionalRegistro nacional de transportador de carga (ANTT).
curl -X POST "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/nfe" \
-H "X-Api-Key: SUA_API_KEY" \
-H "X-Api-Secret: SUA_API_SECRET" \
-H "Idempotency-Key: pedido-100" \
-H "Content-Type: application/json" \
-d '{
"nature": "Venda de mercadoria",
"paymentMethod": "pix",
"items": [
{
"description": "Notebook modelo XYZ",
"ncm": "84713012",
"cfop": "5102",
"quantity": 2,
"unitValue": 3500.00
}
],
"recipient": {
"taxId": "390.533.447-05",
"name": "João Silva",
"email": "[email protected]"
},
"transport": {
"freightModality": "bySender",
"value": 45.90,
"carrier": {
"name": "Transportes Rápido LTDA",
"taxId": "11.222.333/0001-81",
"stateRegistration": "123456789",
"address": {
"street": "Rua das Cargas, 100",
"city": "São Paulo",
"state": "SP"
},
"vehicle": {
"plate": "ABC1D23",
"state": "SP",
"rntc": "12345678"
}
}
}
}'{
"success": true,
"data": {
"id": "018f6e3b-0000-0000-0000-000000000000",
"invoiceId": "018f6e3b-0000-0000-0000-000000000000",
"status": "processing",
"type": "nfe",
"externalId": "pedido-100",
"amount": 7000.00
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Um ou mais campos contém erros de validação. Por favor, revise os dados informados.",
"details": {
"fields": [{ "field": "items.0.ncm", "error": "..." }]
}
}
}Headers
X-Api-Key
stringobrigatórioChave de API da conta (id do usuário).
X-Api-Secret
stringobrigatórioSegredo da chave de API.
Content-Type
stringobrigatórioapplication/json
Query params
status
stringopcionalFiltra por status: pending, processing, authorized, rejected, cancelled. Aliases aceitos: canceled → cancelled; error/failed → rejected.
page
numberopcionalPágina atual. Padrão: 1.
pageSize
numberopcionalItens por página (1–100). Padrão: 20.
curl -X GET "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/nfe?status=authorized" \
-H "X-Api-Key: SUA_API_KEY" \
-H "X-Api-Secret: SUA_API_SECRET" \
{
"success": true,
"data": {
"items": [
{
"id": "018f6e3b-0000-0000-0000-000000000000",
"status": "authorized",
"type": "nfe",
"amount": 7000.00,
"emissionDate": "2026-07-06T10:30:00.000Z",
"createdAt": "2026-07-06T10:28:00.000Z"
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 1
}
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Um ou mais campos contém erros de validação. Por favor, revise os dados informados.",
"details": {
"fields": [{ "field": "items.0.ncm", "error": "..." }]
}
}
}Headers
X-Api-Key
stringobrigatórioChave de API da conta (id do usuário).
X-Api-Secret
stringobrigatórioSegredo da chave de API.
Content-Type
stringobrigatórioapplication/json
Parâmetros de rota
id
string (UUID)obrigatórioIdentificador único da NF-e.
curl -X GET "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/nfe/018f6e3b-0000-0000-0000-000000000000" \
-H "X-Api-Key: SUA_API_KEY" \
-H "X-Api-Secret: SUA_API_SECRET" \
{
"success": true,
"data": {
"id": "018f6e3b-0000-0000-0000-000000000000",
"status": "authorized",
"type": "nfe",
"amount": 7000.00,
"transport": null,
"emissionDate": "2026-07-06T10:30:00.000Z",
"cancellationDate": null,
"fiscal": {
"number": 1234,
"series": "1",
"accessKey": "35260700000000000000550010000012341000012345",
"protocol": "135260000000000"
},
"corrections": [],
"createdAt": "2026-07-06T10:28:00.000Z",
"updatedAt": "2026-07-06T10:30:00.000Z"
}
}{
"success": false,
"error": {
"code": "INVOICE_NOT_FOUND",
"message": "NF-e não encontrada."
}
}Headers
X-Api-Key
stringobrigatórioChave de API da conta (id do usuário).
X-Api-Secret
stringobrigatórioSegredo da chave de API.
Content-Type
stringobrigatórioapplication/json
Parâmetros de rota
id
string (UUID)obrigatórioIdentificador único da NF-e.
curl -X DELETE "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/nfe/018f6e3b-0000-0000-0000-000000000000" \
-H "X-Api-Key: SUA_API_KEY" \
-H "X-Api-Secret: SUA_API_SECRET" \
{
"success": true,
"data": {
"id": "018f6e3b-0000-0000-0000-000000000000",
"status": "authorized",
"apiStatus": "authorized",
"cancelEnqueued": true
}
}{
"success": false,
"error": {
"code": "INVALID_INVOICE_STATUS",
"message": "Cancelamento não permitido para nota com status \"rejected\"."
}
}Headers
X-Api-Key
stringobrigatórioChave de API da conta (id do usuário).
X-Api-Secret
stringobrigatórioSegredo da chave de API.
Content-Type
stringobrigatórioapplication/json
Parâmetros do body
series
numberobrigatórioSérie (0–999).
rangeStart
numberobrigatórioNúmero inicial (≥ 1).
rangeEnd
numberobrigatórioNúmero final (≥ rangeStart, até 999999999).
justification
stringobrigatórioJustificativa (15–255 caracteres).
year
numberopcionalAno da inutilização (2000–2100). Padrão: ano corrente.
curl -X POST "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/nfe/inutilizations" \
-H "X-Api-Key: SUA_API_KEY" \
-H "X-Api-Secret: SUA_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"series": 1,
"rangeStart": 120,
"rangeEnd": 125,
"justification": "Numeração pulada por falha no sistema de vendas"
}'{
"success": true,
"data": {
"confirmed": true,
"protocol": "135260000000001",
"message": "Inutilização de número homologado",
"id": "018f6e3b-0000-0000-0000-000000000001"
}
}{
"success": false,
"error": {
"code": "NFE_INUTILIZATION_REJECTED",
"message": "Mensagem de rejeição retornada pela SEFAZ"
}
}Headers
X-Api-Key
stringobrigatórioChave de API da conta (id do usuário).
X-Api-Secret
stringobrigatórioSegredo da chave de API.
Content-Type
stringobrigatórioapplication/json
Query params
page
numberopcionalPágina atual. Padrão: 1.
pageSize
numberopcionalItens por página (1–100). Padrão: 30.
curl -X GET "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/nfe/inutilizations?page=1&pageSize=30" \
-H "X-Api-Key: SUA_API_KEY" \
-H "X-Api-Secret: SUA_API_SECRET"{
"success": true,
"data": {
"items": [
{
"id": "018f6e3b-0000-0000-0000-000000000001",
"model": "55",
"series": 1,
"rangeStart": 120,
"rangeEnd": 125,
"year": 2026,
"justification": "Numeração pulada por falha no sistema de vendas",
"confirmed": true,
"cStat": 102,
"message": "Inutilização de número homologado",
"protocol": "135260000000001",
"environment": "production",
"createdAt": "2026-07-06T10:28:00.000Z"
}
],
"pagination": { "page": 1, "pageSize": 30 }
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Um ou mais campos contém erros de validação. Por favor, revise os dados informados.",
"details": {
"fields": [{ "field": "items.0.ncm", "error": "..." }]
}
}
}Outros endpoints da NF-e
GET /v1/companies/{companyId}/nfe/{id}/pdf— DANFEGET /v1/companies/{companyId}/nfe/{id}/xml— XML autorizadoGET /v1/companies/{companyId}/nfe/{id}/rejection-xml— XML enviado que foi rejeitado (só notarejected; responde302para URL temporária)POST /v1/companies/{companyId}/nfe/{id}/correction— carta de correção ({ "correction": "texto de 15 a 1000 caracteres" })
PDF e XML respondem com o arquivo (200, Content-Disposition: attachment) ou com 302 para o CDN — configure o cliente HTTP para seguir redirects. Só ficam disponíveis após a autorização (ou cancelamento confirmado); antes disso retornam 400 INVOICE_ASSETS_UNAVAILABLE. Query opcional: download=1 e, no PDF, regenerate=1.
Tabelas de referência NF-e
GET /v1/utils/ncm?search=...— consulta de NCMGET /v1/utils/cfop?search=...— consulta de CFOPGET /v1/utils/cest?search=...— consulta de CEST