NF-e modelo 55: monte, valide e autorize com um contrato fiscal verificável.

Onde esse fluxo começa na prática

O onboarding mais rápido hoje passa pelo console: gerar a chave de homologação, cadastrar a empresa no mesmo ambiente, subir o certificado A1, configurar o webhook e depois criar o primeiro rascunho fiscal.

Criar o rascunho da NF-e

O fluxo da plataforma parte de um rascunho. Isso permite validar, versionar e emitir sem prender o ERP em uma chamada longa para a SEFAZ.

{
  "document_type": "nfe",
  "series": 1,
  "number": 214,
  "payload": {
    "nature_operation": "Venda de mercadoria para revenda",
    "operation_type": "saida",
    "consumer_final": true,
    "presence_indicator": 1,
    "recipient": {
      "name": "Cliente Fictício Atacadista Ltda",
      "document": "98765432000110",
      "state_registration_indicator": 1,
      "email": "[email protected]",
      "address": {
        "street": "Avenida Paraná",
        "number": "1000",
        "district": "Batel",
        "city_name": "Curitiba",
        "city_code": "4106902",
        "state_code": "PR",
        "postal_code": "80000000"
      }
    },
    "items": [
      {
        "code": "SKU-100",
        "name": "Produto de demonstração",
        "ncm": "85176259",
        "cfop": "5102",
        "unit": "UN",
        "quantity": 1,
        "unit_price": 1500.00,
        "discount": 50.00,
        "taxes": {
          "icms": {"code": "00", "origin": 0, "aliquot": 18},
          "pis": {"code": "01", "aliquot": 1.65},
          "cofins": {"code": "01", "aliquot": 7.6}
        }
      }
    ],
    "payments": [
      {
        "method": "01",
        "amount": 1500.00
      }
    ]
  }
}

Contrato de payload suportado

A referência OpenAPI descreve tipos, limites e obrigatoriedade. Hoje o motor NF-e suporta oficialmente os grupos abaixo.

Pedido de compra e informações complementares

Use os campos do item quando o cliente precisar relacionar cada produto a uma linha da ordem de compra. Quando um único pedido representar a nota inteira, use também ou apenas o grupo purchase.

{
  "items": [
    {
      "code": "SKU-001",
      "name": "Produto de demonstração",
      "ncm": "85369090",
      "cfop": "5102",
      "unit": "UN",
      "quantity": 15,
      "unit_price": 270,
      "purchase_order": "OC-0001",
      "purchase_order_item": "000001",
      "taxes": { "icms": { "code": "102", "origin": 2, "aliquot": 0 } }
    }
  ],
  "purchase": {
    "commitment_note": "EMP-2026-1",
    "order": "OC-0001",
    "contract": "CONT-88"
  },
  "additional_info": "Pedido OC-0001\nObservações comerciais\nOptante pelo Simples Nacional."
}

Mapeamento XML

Outras despesas acessórias (vOutro) e devolução ao fornecedor

Há dois campos, com semânticas diferentes e deliberadamente separadas. Os dois gravam em det/prod/vOutro, somam em total/ICMSTot/vOutro e entram no vNF. O que muda é o efeito na base de cálculo.

Despesas com efeito tributário declarado

Uma despesa acessória cobrada do destinatário normalmente integra a base do ICMS. Mas nem toda linha de vOutro é isso — muita gente usa o campo para fechar o total de uma devolução com o da nota de origem, onde não há o que tributar. Como não existe uma resposta única, a API não adivinha: quem informa diz o que a despesa é.

{
  "items": [
    {
      "unit_price": 1000.00,
      "quantity": 1,
      "additional_charges": [
        {
          "amount": 100.00,
          "description": "Embalagem especial cobrada do destinatario",
          "in_icms_base": true,
          "in_pis_cofins_base": true
        }
      ]
    }
  ]
}

A base do ICMS passa a 1.100,00 e o vNF também. Sem as marcações, o mesmo valor apareceria em vOutro e no vNF, mas a base continuaria 1.000,00.

Frete e seguro têm campos próprios e regra própria — sempre integram a base, porque é o que a LC 87/96 determina. Veja frete e seguro.

{
  "purpose": 4,
  "nature_operation": "Devolução de compra",
  "operation_type": "saida",
  "referenced_documents": [
    { "access_key": "32250612345678000199550010000001231000001234" }
  ],
  "items": [
    {
      "code": "SKU-001",
      "name": "Produto de demonstração",
      "ncm": "85369090",
      "cfop": "5202",
      "unit": "UN",
      "quantity": 10,
      "unit_price": 100,
      "other_expenses": 50.00,
      "taxes": { "icms": { "code": "102", "origin": 2, "aliquot": 0 } }
    }
  ]
}

No exemplo, vProd = 1000,00 e vOutro = 50,00, resultando em vNF = 1050,00. Quando houver vários itens, informe other_expenses em cada linha; havendo pagamentos, a soma de payments precisa fechar com o vNF já acrescido do vOutro.

Mapeamento XML

IBS e CBS (reforma tributária)

Grupo IBSCBS por item. Hoje é opcional: nota sem ele continua sendo autorizada. E é paralelo — não move ICMS, DIFAL, FCP, ICMS-ST, PIS, COFINS, IPI nem o vNF.

Referências: NT 2025.002-RTC v1.50, publicada em 03/06/2026, e IT 2025.002 v1.60 com tabelas CST/cClassTrib publicadas em 23/06/2026. A NT substitui a RT NT 2024.002 - IBS/CBS v1.10.

{
  "items": [
    {
      "unit_price": 1000.00,
      "quantity": 1,
      "taxes": {
        "ibscbs": {
          "cst": "000",
          "classification_code": "000001",
          "state_rate": 0.1,
          "municipal_rate": 0,
          "cbs_rate": 0.9
        }
      }
    }
  ]
}

Sobre 1.000,00: vIBSUF 1,00 e vCBS 9,00. O vIBS do item e todo o totalizador IBSCBSTot são somados automaticamente — não há campo de total para informar.

A API consulta a tabela instalada pela data de emissão. Quando o ano não tem as três alíquotas publicadas — como 2027 — gera aviso, não recusa: uma data sem cobertura integral não vira bloqueio rígido.

Redução de alíquota

Quando o CST informado tem o indicador de redução na tabela oficial — hoje o 200 —, a API monta o grupo gRed sozinha. O percentual não vai no payload: ele é do cClassTrib, e a SEFAZ o confere contra a tabela (regra UB27-10, Rejeição 1034). Informá-lo só criaria uma forma a mais de errar.

{
  "taxes": {
    "ibscbs": {
      "cst": "200",
      "classification_code": "200030",
      "state_rate": 0.1,
      "municipal_rate": 0,
      "cbs_rate": 0.9
    }
  }
}

O 200030 — dispositivos médicos do Anexo IV, LC 214/2025 art. 131 — reduz 60%. As alíquotas informadas continuam sendo as cheias; a API calcula gRed/pAliqEfet = 0,04 e 0,36 (regra UB28-10) e aplica sobre a base: vIBSUF 0,40 e vCBS 3,60 sobre 1.000,00. O IBSCBSTot soma o valor reduzido, e uma nota pode misturar itens reduzidos e integrais. Redução de 100% zera o imposto mas mantém o grupo: some o valor, não a declaração.

Se o cClassTrib exigir um grupo que ainda não existe, a resposta é 422 nomeando o que falta — “exige o grupo de diferimento”, “exige o grupo de crédito presumido da operação” — em vez de uma recusa genérica.

Tributação regular (operação suspensa ou condicionada)

Alguns regimes suspendem o imposto sob condição — depósito, permanência temporária, industrialização para exportação, Zona Franca. Nesses casos o cClassTrib traz o indicador de tributação regular, e a nota precisa declarar como seria tributada se a condição não fosse cumprida. Vai em taxes.ibscbs.regular_taxation.

{
  "taxes": {
    "ibscbs": {
      "cst": "550",
      "classification_code": "550003",
      "state_rate": 0.1,
      "municipal_rate": 0,
      "cbs_rate": 0.9,
      "regular_taxation": {
        "cst": "000",
        "classification_code": "000001"
      }
    }
  }
}

Informe apenas o par hipotético; alíquotas e valores são calculados. Se esse par tiver redução — por exemplo 200/200030, que reduz 60% —, a hipótese herda a redução. O par é conferido contra a mesma tabela (rejeições 1066 e 1067), e uma classificação que ela própria exija tributação regular é recusada: a declaração não fecharia.

Informar o grupo onde ele não é permitido devolve 422 citando a Rejeição 1114; omiti-lo onde é exigido, a 1065.

Imunidade e não incidência

No CST 410 — imunidade e não incidência — não existe grupo de imposto. Não é alíquota zero: a tabela oficial marca esse CST como incompatível com o grupo (ind_gIBSCBS = 0), e o item sai só com o código e a classificação.

{
  "taxes": {
    "ibscbs": {
      "cst": "410",
      "classification_code": "410008"
    }
  }
}

O 410008 do exemplo é a imunidade de livros, jornais e periódicos. A mesma família cobre doações, transferências entre estabelecimentos do mesmo titular, operações acobertadas somente pelo ICMS, exportações e outras situações sem incidência — 19 classificações em NF-e e 13 em NFC-e.

O CST 400, de isenção, existe na tabela mas nenhuma das suas classificações está habilitada para NF-e ou NFC-e. Na prática, quem cobre as situações sem incidência nestes modelos é o 410.

Rastreabilidade por lote e medicamentos

São dois grupos separados, e um não implica o outro. O rastro vale para qualquer produto sob controle sanitário — medicamento, alimento, bebida, água envasada, embalagem, produto veterinário. O med é só de medicamento e matéria-prima farmacêutica.

Lotes — items[].tracking[]

O grupo se repete por lote, até 500 por item, e não move nenhum valor da nota: é informação de rastreio, não de cálculo.

{
  "items": [
    {
      "quantity": 10,
      "unit": "CX",
      "tracking": [
        { "lot": "L2026-001", "quantity": 6, "manufactured_at": "2026-01-15",
          "expires_at": "2028-01-14", "aggregation_code": "AGREG-001" },
        { "lot": "L2026-002", "quantity": 4, "manufactured_at": "2026-02-01",
          "expires_at": "2028-02-29" }
      ]
    }
  ]
}

Medicamentos — items[].medicine

Defensivos agrícolas — items[].agrochemical

Defensivo agrícola (agrotóxico) com NCM da lista da NT 2024.003 exige receituário agronômico. Em nota normal (purpose: 1) para consumidor final, a SEFAZ devolve a Rejeição 835 quando falta o grupo infNFe/agropecuario/defensivo. Você declara por item; a API junta tudo em um grupo só por nota — até 20 defensivos, qualquer que seja o número de itens — e o posiciona logo após infRespTec, como manda o XSD.

{
  "items": [
    {
      "ncm": "38085200",
      "...": "...",
      "agrochemical": {
        "prescription_number": "RC-2026/001",
        "technical_responsible_cpf": "52998224725"
      }
    }
  ]
}

Local de entrega e local de retirada

O endereço do destinatário fica em recipient.address e continua sendo o dest/enderDest. Quando a mercadoria é entregue em outro endereço, ou sai de um endereço diferente do emitente, o leiaute tem dois grupos próprios: entrega e retirada.

Os dois são opcionais, independentes e têm exatamente os mesmos campos.

{
  "recipient": { "...": "endereco do cliente, continua no dest/enderDest" },
  "delivery_address": {
    "name": "Deposito Central LTDA",
    "document": "11222333000181",
    "street": "Avenida do Deposito",
    "number": "1500",
    "complement": "Galpao 3",
    "district": "Distrito Industrial",
    "city_code": "3550308",
    "city_name": "Sao Paulo",
    "state_code": "SP",
    "postal_code": "01001000"
  }
}

Frete e seguro

O leiaute da NF-e não tem campo de frete da nota: existem det/prod/vFrete e det/prod/vSeg por item, e o total ICMSTot/vFrete é o somatório deles. Por isso há dois caminhos, e você escolhe um.

Valor por item

Valor único da nota, rateado pela API

Quem recebe um frete só da transportadora informa em shipping e a API rateia entre os itens, proporcionalmente ao valor de cada um.

{
  "shipping": {
    "modality": 0,
    "freight_amount": 150.00,
    "insurance_amount": 30.00
  },
  "items": [
    { "code": "SKU-1", "unit_price": 1000.00, "quantity": 1, "...": "..." },
    { "code": "SKU-2", "unit_price": 500.00, "quantity": 1, "...": "..." }
  ]
}

Na proporção 1.000/500, o frete vira 100,00 e 50,00; o seguro, 20,00 e 10,00.

Efeito na base de cálculo

Frete e seguro cobrados do destinatário integram a base de cálculo do ICMS, PIS, COFINS e IPI (LC 87/96, art. 13, §1º, II). Num item de 1.000,00 com 100,00 de frete e 50,00 de seguro, a base passa a 1.150,00 — e não 1.000,00. Os dois valores também entram na composição do vNF.

É a diferença em relação ao other_expenses, que compõe o vNF mas fica fora da base. Se a despesa deve entrar na base, ela é frete ou seguro, não "outras despesas".

Substituição tributária (ICMS-ST)

São duas situações diferentes, com campos diferentes: o ST que você recolhe na operação (CST 10, 30, 70 e 90; CSOSN 201, 202, 203 e 900) e o ST que o fornecedor já reteve antes (CST 60; CSOSN 500).

ST a recolher — items[].taxes.icms.st

{
  "items": [
    {
      "unit_price": 1000.00,
      "quantity": 1,
      "taxes": {
        "icms": {
          "code": "10",
          "origin": 0,
          "aliquot": 18,
          "st": {
            "base_mode": 4,
            "mva": 40,
            "aliquot": 18,
            "fcp_aliquot": 2
          }
        }
      }
    }
  ]
}

O MVA de 40% sobre 1.000,00 dá base de ST de 1.400,00. O ST a recolher é 18% disso (252,00) menos o ICMS próprio de 180,00, ou seja 72,00. O FCP-ST sai como 28,00. Ambos entram na composição do vNF, junto com os totalizadores ICMSTot/vBCST, vST e vFCPST.

ST retido anteriormente — items[].taxes.icms.st_withheld

Só no CST 60 (regime normal) e no CSOSN 500 (Simples). Não entra no vNF: o imposto já foi recolhido pelo fornecedor. Numa nota com itens de famílias diferentes, só os itens de ST a recolher somam ao total.

ST no Simples Nacional — CSOSN 201, 202, 203 e 500

Os campos são os mesmos, no mesmo st e st_withheld. O que muda é que nenhum CSOSN de ST tem ICMS próprio: não há o que descontar, e o ST vai integral. O grupo st é obrigatório nos CSOSN 201, 202 e 203 — é a razão de existirem — e o st_withheld só cabe no 500.

{
  "items": [
    {
      "unit_price": 1000.00,
      "quantity": 1,
      "taxes": {
        "icms": {
          "code": "201",
          "origin": 0,
          "credit_rate": 2.5,
          "st": {
            "base_mode": 4,
            "mva": 40,
            "aliquot": 18,
            "fcp_aliquot": 2
          }
        }
      }
    }
  ]
}

Base de ST de 1.400,00, ST de 252,00 (integral, sem desconto de ICMS próprio) e FCP-ST de 28,00, fechando vNF em 1.280,00. O credit_rate gera o crédito do art. 23 da LC 123 e vale nos CSOSN 101, 201 e 900. No 201 o par pCredSN/vCredICMSSN é obrigatório pelo leiaute: sem credit_rate ele sai zerado.

O único CSOSN com destaque próprio é o 900: nele o aliquot gera o ICMS do item e esse valor é descontado do ST, como no regime normal. Nenhum CSOSN tem FCP próprio — informar taxes.icms.fcp_aliquot com emitente do Simples é recusado, com a indicação de usar st.fcp_aliquot ou st_withheld.fcp_aliquot.

Fundo de Combate à Pobreza (FCP)

Vários estados cobram um adicional de ICMS destinado ao FCP. Informe a alíquota em items[].taxes.icms.fcp_aliquot e a API calcula o valor e soma o totalizador ICMSTot/vFCP.

{
  "items": [
    {
      "unit_price": 1000.00,
      "quantity": 1,
      "tax_benefit_code": "SP800001",
      "taxes": {
        "icms": {
          "code": "20",
          "origin": 0,
          "aliquot": 18,
          "base_reduction": 30,
          "fcp_aliquot": 2
        }
      }
    }
  ]
}

Com redução de 30% sobre 1.000,00, a base passa a 700,00, e é sobre ela que incidem tanto o ICMS (126,00) quanto o FCP (14,00). A base do FCP acompanha a base reduzida do ICMS, não o valor bruto do item.

Exportação

Três coisas caracterizam uma nota de exportação, e a SEFAZ confere as três juntas: o destinatário no exterior, o CFOP da série 7000 em todos os itens e o grupo export, que diz por onde a mercadoria deixa o país. Faltar qualquer uma devolve 422 antes do envio.

{
  "recipient": {
    "name": "IMPORTADORA INTERNACIONAL LLC",
    "foreign_document": "US987654321",
    "address": {
      "street": "100 Biscayne Boulevard",
      "number": "2500",
      "district": "Downtown",
      "country_code": 2496,
      "country_name": "Estados Unidos"
    }
  },
  "export": {
    "exit_state": "SP",
    "exit_location": "Porto de Santos"
  },
  "items": [
    { "cfop": "7102", "quantity": 10, "unit_price": 100 }
  ]
}

Drawback e exportação indireta

O grupo items[].export_details[] cobre dois casos que o leiaute reuniu: o ato concessório de drawback e a exportação indireta, em que a mercadoria sai por uma comercial exportadora e o item aponta a NF-e recebida.

{
  "referenced_documents": [
    { "access_key": "35260767882130000176550990010002271021181451" }
  ],
  "items": [
    {
      "cfop": "7102",
      "quantity": 10,
      "export_details": [
        { "drawback_number": "20260000001" },
        {
          "indirect": {
            "export_registry": "123456789012",
            "access_key": "35260767882130000176550990010002271021181451",
            "quantity": 10
          }
        }
      ]
    }
  ]
}

No IBS/CBS, a exportação tem classificações próprias: 550001 (suspensão para exportação de bens materiais) e 410004 (imunidade nas exportações de bens e serviços). Ambas só fazem sentido numa nota que realmente sai do país, e as duas foram autorizadas nesse formato nos cenários testados na homologação da SEFAZ-SP. Veja IBS e CBS.

Nota complementar e nota de ajuste

A finalidade da nota vai em purpose (ide/finNFe). As quatro existem e todas emitem; o que muda entre elas é a exigência de referenciar a nota de origem.

{
  "purpose": 2,
  "nature_operation": "Complemento de imposto",
  "referenced_documents": [
    { "access_key": "35260767882130000176550990010002271021181451" }
  ],
  "items": [
    {
      "unit_price": 0,
      "quantity": 1,
      "taxes": {
        "icms": { "code": "00", "origin": 0, "aliquot": 18 }
      }
    }
  ]
}

O que dá para complementar

referenced_documents não indica a finalidade: uma nota normal com referência também é autorizada. Se você quer complementar, é o purpose que diz isso, não a presença da chave.

Os cenários acima — complemento de imposto, de valor e de quantidade, com e sem quantidade zero, com pagamento declarado e com item misto — foram autorizados nos cenários testados na homologação da SEFAZ-SP. Nenhum foi testado em produção nem em outra UF.

ISSQN — serviço na NF-e

A NF-e pode levar serviço sujeito ao imposto municipal, sozinho ou junto com mercadoria. Duas regras governam isso, e as duas foram medidas contra a SEFAZ.

{
  "services": { "competence_date": "2026-07-01" },
  "items": [
    {
      "code": "SRV-1",
      "name": "Suporte tecnico",
      "ncm": "00",
      "cfop": "5933",
      "unit": "UN",
      "quantity": 1,
      "unit_price": 1000.00,
      "taxes": {
        "issqn": {
          "base": 1000.00,
          "aliquot": 5,
          "city_code": "3550308",
          "service_list_item": "01.07",
          "exigibility": 1
        }
      }
    }
  ]
}

PIS e COFINS por substituição tributária

Tem dois lados, e só um está disponível.

{
  "taxes": {
    "pis":    { "code": "05" },
    "cofins": { "code": "05" }
  }
}

O CST 05 é "Operação Tributável por Substituição Tributária". O item sai com PISNT/COFINSNT, sem valor destacado, e não move o vNF — o tributo foi recolhido antes, por quem substituiu. É o caso mais comum na ponta: o varejista que revende mercadoria com PIS/COFINS já retidos.

Diferimento

Diferir é adiar o recolhimento: o imposto incide, mas o pagamento passa para outro momento da cadeia. Os dois sistemas tributários fazem isso de formas diferentes, e os grupos não se misturam — uma nota pode ter os dois ao mesmo tempo.

ICMS diferido (CST 51)

{
  "items": [
    {
      "unit_price": 1000.00,
      "quantity": 1,
      "tax_benefit_code": "SP052600",
      "taxes": {
        "icms": {
          "code": "51",
          "origin": 0,
          "aliquot": 18,
          "deferral": { "percentage": 100 }
        }
      }
    }
  ]
}

Sobre 1.000,00 a 18%: vICMSOp 180,00, vICMSDif 180,00 e vICMS 0,00. Com percentage: 50, metade de cada. O ICMSTot/vICMS recebe o devido, e o vNF não se move — o ICMS é imposto por dentro.

IBS/CBS diferido (CST 510 e 515)

{
  "taxes": {
    "ibscbs": {
      "cst": "510",
      "classification_code": "510001",
      "state_rate": 0.1,
      "municipal_rate": 0,
      "cbs_rate": 0.9,
      "deferral": { "percentage": 100 }
    }
  }
}

A alíquota informada continua sendo a padrão da transição — quem retira o imposto é o diferimento. Sobre 1.000,00: vDif 1,00 no IBS da UF e 9,00 na CBS, com vIBSUF e vCBS zerados. Informe só o percentual; os valores dos três componentes são calculados (regras UB23-10, UB42-10 e UB61-10).

No 515 — diferimento com redução de alíquota — as duas coisas se compõem na ordem certa: a redução do cClassTrib primeiro, o diferimento sobre a alíquota já reduzida. O grupo é exigido pelo indicador do CST (Rejeições 1030, 1044 e 1061) e recusado sem ele (1029, 1083 e 1090).

ICMS desonerado (vICMSDeson)

Quando o ICMS deixa de ser cobrado por isenção, redução, suspensão ou decisão judicial, o valor que deixou de ser cobrado é declarado no item, junto com o motivo. Vai em items[].taxes.icms.exemption.

{
  "items": [
    {
      "unit_price": 1000.00,
      "quantity": 1,
      "tax_benefit_code": "SP010030",
      "taxes": {
        "icms": {
          "code": "40",
          "origin": 0,
          "exemption": {
            "value": 180.00,
            "reason": 9,
            "deducts_from_total": false
          }
        }
      }
    }
  ]
}

Um motivo fora da lista do CST é recusado no build, com a lista do que vale — o XSD tem enumerações diferentes por grupo, e um valor errado só apareceria como erro de schema no envio. A desoneração é dos CST do regime normal: nenhum grupo ICMSSN do Simples Nacional tem vICMSDeson, e enviá-la com emitente do Simples é recusado.

Partilha do ICMS na venda interestadual (ICMSUFDest / DIFAL)

Na venda interestadual para consumidor final não contribuinte, a diferença entre a alíquota interna da UF de destino e a interestadual pertence ao estado do comprador (EC 87/2015). Isso vai no grupo ICMSUFDest por item, e a API soma o totalizador ICMSTot/vICMSUFDest automaticamente.

Informe por item, em items[].taxes.icms_destination:

{
  "consumer_final": true,
  "recipient": {
    "state_registration_indicator": 9,
    "address": { "state_code": "SP" }
  },
  "items": [
    {
      "cfop": "6108",
      "unit_price": 1000.00,
      "quantity": 1,
      "taxes": {
        "icms": { "code": "00", "origin": 0, "aliquot": 12 },
        "icms_destination": {
          "aliquot": 18,
          "interstate_aliquot": 12,
          "fcp_aliquot": 2
        }
      }
    }
  ]
}

O exemplo gera vICMSUFDest = 60,00 — (18 − 12)% sobre 1.000,00 — e vFCPUFDest = 20,00. Desde 2019 a partilha é integral para o destino, então pICMSInterPart é sempre 100 e vICMSUFRemet é sempre zero; a API preenche os dois, você não precisa informá-los.

IPI devolvido na devolução (impostoDevol / vIPIDevol)

Quando um emitente que não é contribuinte do IPI (Simples Nacional, MEI) devolve mercadoria a um fornecedor do regime normal, o IPI que veio destacado na nota de compra precisa voltar no grupo impostoDevol. É ele que dá ao destinatário o direito ao crédito do IPI: o vOutro faz o total fechar, mas não produz esse efeito. O grupo existe no leiaute desde a versão 3.10; o totalizador no grupo de totais (ICMSTot/vIPIDevol) entrou com o leiaute 4.00, pela NT 2016.002.

Informe por item, em items[].returned_ipi:

{
  "purpose": 4,
  "nature_operation": "Devolução de compra",
  "operation_type": "saida",
  "referenced_documents": [
    { "access_key": "32250612345678000199550010000001231000001234" }
  ],
  "items": [
    {
      "code": "SKU-001",
      "name": "Produto devolvido integralmente",
      "ncm": "85369090",
      "cfop": "5202",
      "unit": "UN",
      "quantity": 10,
      "unit_price": 100,
      "returned_ipi": { "value": 209.40 },
      "taxes": { "icms": { "code": "102", "origin": 2, "aliquot": 0 } }
    },
    {
      "code": "SKU-002",
      "name": "Produto devolvido pela metade",
      "ncm": "85369090",
      "cfop": "5202",
      "unit": "UN",
      "quantity": 4,
      "unit_price": 50,
      "returned_ipi": { "value": 15.60, "percentage": 50 },
      "taxes": { "icms": { "code": "102", "origin": 2, "aliquot": 0 } }
    }
  ]
}

No exemplo, vProd = 1200,00 e o total do IPI devolvido é 209,40 + 15,60 = 225,00, resultando em vNF = 1425,00. O totalizador e o vNF são calculados pela API: não existe campo de total independente.

Mapeamento XML

Quando a ordem dos itens não coincide com a da nota original, ou quando a devolução consolida mais de uma nota, informe a referência explicitamente em cada linha:

{
  "items": [
    {
      "code": "SKU-001",
      "referenced_document": {
        "access_key": "32250612345678000199550010000001231000001234",
        "item": 7
      },
      "returned_ipi": { "value": 209.40 }
    }
  ]
}

Crédito de ICMS do Simples Nacional na devolução (CSOSN 101/900)

Empresas do Simples Nacional que devolvem mercadoria a um fornecedor do regime normal podem informar o crédito de ICMS a que o destinatário tem direito (art. 23 da LC 123/2006). Use taxes.icms.credit_rate com a alíquota do crédito — a API calcula o valor automaticamente sobre a base do item (unit_price × quantity − discount) e grava no grupo pCredSN/vCredICMSSN. O campo vale tanto para CSOSN 101 quanto 900.

{
  "purpose": 4,
  "nature_operation": "Devolução de compra",
  "operation_type": "saida",
  "referenced_documents": [
    { "access_key": "32250612345678000199550010000001231000001234" }
  ],
  "items": [
    {
      "code": "SKU-001",
      "name": "Produto de demonstração",
      "ncm": "85369090",
      "cfop": "5202",
      "unit": "UN",
      "quantity": 1,
      "unit_price": 1000.00,
      "other_expenses": 50.00,
      "taxes": { "icms": { "code": "900", "origin": 2, "aliquot": 0, "credit_rate": 4.00 } }
    }
  ]
}

No exemplo, a base do item é 1000,00 e o crédito de 4% resulta em vCredICMSSN = 40,00.

Mapeamento XML

Venda a prazo com fatura e duplicatas

Para fazer o grupo fiscal cobr/fat/dup aparecer no XML e na DANFE da NF-e modelo 55, use payload.billing. O pagamento financiado deve usar method=14 (Duplicata Mercantil); indicator=1 informa pagamento a prazo e também é assumido automaticamente quando omitido nesse método.

Mapeamento para o XML/MOC

Exemplo completo para copiar

Substitua {token}, os dados fiscais e as datas de vencimento antes de executar.

curl -X POST 'https://fiscal.contora.com.br/api/v1/nfe/drafts' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pedido-214-nfe' \
  --data-raw '{
  "document_type": "nfe",
  "series": 1,
  "number": 214,
  "payload": {
    "nature_operation": "Venda de mercadoria a prazo",
    "operation_type": "saida",
    "consumer_final": false,
    "presence_indicator": 0,
    "recipient": {
      "name": "Cliente de Exemplo LTDA",
      "document": "98765432000110",
      "state_registration_indicator": 9,
      "address": {
        "street": "Avenida Parana",
        "number": "1000",
        "district": "Batel",
        "city_name": "Curitiba",
        "city_code": "4106902",
        "state_code": "PR",
        "postal_code": "80000000"
      }
    },
    "items": [{
      "code": "SKU-100",
      "name": "Produto de demonstracao",
      "ncm": "85176259",
      "cfop": "5102",
      "unit": "UN",
      "quantity": 1,
      "unit_price": 1500.00,
      "taxes": {
        "icms": {"code": "00", "origin": 0, "aliquot": 18},
        "pis": {"code": "01", "aliquot": 1.65},
        "cofins": {"code": "01", "aliquot": 7.6}
      }
    }],
    "payments": [
  {
    "method": "14",
    "indicator": 1,
    "amount": 1500.00
  }
],
"billing": {
  "invoice": {
    "number": "FAT-000214",
    "original_amount": 1500.00,
    "discount_amount": 0.00,
    "net_amount": 1500.00
  },
  "installments": [
    {
      "number": "001",
      "due_date": "2030-08-20",
      "amount": 500.00
    },
    {
      "number": "002",
      "due_date": "2030-09-20",
      "amount": 500.00
    },
    {
      "number": "003",
      "due_date": "2030-10-20",
      "amount": 500.00
    }
  ]
    }
  }
}'

Pagamento parcialmente à vista e parcialmente a prazo

Em uma NF-e de 1500.00, os 300.00 pagos em dinheiro ficam separados dos 1200.00 financiados. Somente a parte com method=14 entra na fatura e nas duplicatas.

"payments": [
  {"method": "01", "indicator": 0, "amount": 300.00},
  {"method": "14", "indicator": 1, "amount": 1200.00}
],
"billing": {
  "invoice": {
    "number": "FAT-000215",
    "original_amount": 1200.00,
    "discount_amount": 0.00,
    "net_amount": 1200.00
  },
  "installments": [
    {"number": "001", "due_date": "2030-08-20", "amount": 600.00},
    {"number": "002", "due_date": "2030-09-20", "amount": 600.00}
  ]
}

Erros de validação

Quando as duplicatas não fecham com a fatura, a API responde HTTP 422 e aponta o campo exato:

{
  "ok": false,
  "message": "Falha de validacao no request.",
  "error": {
    "type": "validation_error",
    "details": {
      "fields": {
        "payload.billing.installments": [
          "A soma das duplicatas precisa ser exatamente igual ao net_amount da fatura."
        ]
      }
    }
  }
}

Se method=14 for enviado sem fatura e duplicatas, o retorno mantém o mesmo envelope:

{
  "ok": false,
  "message": "Falha de validacao no request.",
  "error": {
    "type": "validation_error",
    "details": {
      "fields": {
        "payload.payments": [
          "O meio de pagamento 14 (Duplicata Mercantil) exige payload.billing com fatura e duplicatas."
        ]
      }
    }
  }
}

Frete, transportadora e volumes (shipping)

Use payload.shipping quando a operação realmente envolver transporte. Sem esse campo, a nota continua sendo emitida com modalidade 9 (sem ocorrência de transporte), como antes — nada muda para quem não usa o recurso. carrier, vehicle e volumes são opcionais dentro de shipping e podem ser combinados livremente.

{
  "shipping": {
    "modality": 0,
    "carrier": {
      "name": "Transportadora Rápida LTDA",
      "document": "11222333000181",
      "state_registration": "1234567890",
      "address": "Rodovia BR-101, KM 50",
      "city_name": "Curitiba",
      "state_code": "PR"
    },
    "vehicle": {
      "plate": "ABC1D23",
      "state_code": "PR",
      "rntc": "99887766"
    },
    "volumes": [
      {
        "quantity": 2,
        "species": "CAIXA",
        "brand": "MARCA-X",
        "numbering": "001/002",
        "net_weight": 10.5,
        "gross_weight": 12.0
      }
    ]
  }
}

Mapeamento XML

Cartão e PIX: o grupo card

Para a SEFAZ, PIX é pagamento eletrônico e entra na mesma regra do cartão. Sempre que payments[].method for 03 (crédito), 04 (débito) ou 17 (PIX), envie o grupo payments[].card. Sem ele pode vir a Rejeição 391 — "Não informados os dados do cartão de crédito / débito nas Formas de Pagamento da Nota Fiscal".

O PIX é o caso que costuma surpreender: o nome do grupo fala em cartão, o pagamento não passa por maquininha nenhuma, e é natural enviar só o meio e o valor. A regra da autorizadora, porém, é a mesma.

Enviar o grupo é sempre o mais seguro: vale nos dois modelos e não muda o resultado onde a SEFAZ não cobra.

O mínimo que faz uma venda em PIX passar é um campo:

"payments": [
  {
    "method": "17",
    "indicator": 0,
    "amount": 4400.00,
    "card": { "integration": 2 }
  }
]

Uma venda em cartão de crédito integrado ao PDV fica assim:

"payments": [
  {
    "method": "03",
    "indicator": 0,
    "amount": 1250.00,
    "card": {
      "integration": 1,
      "authorization": "884523",
      "institution_document": "01027058000191",
      "brand": "02"
    }
  }
]

Quando o grupo falta numa NFC-e, o build responde:

{
  "ok": false,
  "message": "O meio de pagamento 17 (PIX, pagamento instantâneo) exige o grupo payments[].card na NFC-e — sem ele a SEFAZ devolve a Rejeição 391. (...)",
  "error": {
    "type": "document_build_error",
    "details": {}
  }
}

Na NF-e, o mesmo payload constrói e o alerta vem junto:

{
  "ok": true,
  "data": {
    "build_warnings": [
      "O meio de pagamento 17 (PIX, pagamento instantâneo) foi informado sem o grupo payments[].card. A NF-e é transmitida assim, e as UFs que medimos autorizam, mas a UF que cobrar o grupo devolve a Rejeição 391. (...)"
    ]
  }
}

Pagamento em dinheiro com troco

Fora do fluxo de fatura/duplicata (payload.billing), a soma de payments[].amount precisa ser maior ou igual ao valor total do documento. Quando for maior, o excedente é gravado automaticamente como troco (pag/vTroco) — mas só quando houver pagamento(s) em dinheiro (method: "01") suficiente(s) para cobrir a diferença; caso contrário a API rejeita antes do envio, já que não faz sentido dar troco de um pagamento em cartão ou PIX.

{
  "payments": [
    { "method": "01", "amount": 200.00 }
  ]
}

Se o total do documento for 150,00, esse pagamento gera vTroco = 50,00. Quando a soma dos pagamentos é exatamente igual ao total (o caso mais comum), o comportamento é o de sempre: nenhuma mudança para quem já integra hoje.

Venda por marketplace ou plataforma de intermediação

Use payload.marketplace quando a venda passar por um intermediador (marketplace, plataforma de delivery e similares). Esse campo grava ide/indIntermed = 1 e o grupo infIntermed.

{
  "marketplace": {
    "intermediary_document": "44455566000183",
    "intermediary_id": "VENDEDOR-XPTO-001"
  }
}

Operação sem intermediador (indIntermed = 0)

Não é preciso enviar nada além de presence_indicator. Quando a operação é direta — venda em site ou plataforma própria, atendimento B2G, televendas — basta omitir payload.marketplace: a API grava ide/indIntermed = 0 automaticamente sempre que presence_indicator for 2, 3, 4 ou 9, que são os indicadores de presença para os quais a NT 2020.006 exige a tag.

{
  "presence_indicator": 9
}
// resultado no XML: ide/indIntermed = 0, sem grupo infIntermed

Para presence_indicator igual a 0, 1 ou 5 a tag não se aplica e não é gravada, conforme a mesma nota técnica.

Mapeamento XML

Exemplo pratico de resposta

Depois de criar o rascunho, a API devolve um identificador estavel do documento, o status inicial do ciclo de vida e os primeiros metadados para acompanhamento.

{
  "ok": true,
  "data": {
    "id": "18f017f7-a69c-4fa6-89c7-05f52fcc8be4",
    "document_type": "nfe",
    "environment": "homologacao",
    "series": 1,
    "number": 214,
    "status": "draft",
    "processing_status": "draft",
    "requested_action": "build_unsigned",
    "created_at": "2026-07-02T14:35:18-03:00"
  }
}

Build e emissão

Depois do rascunho salvo, o ERP pode pedir o build fiscal e em seguida disparar a emissão assíncrona.

Build opcional

{"sign": false}

{
  "action": "authorize"
}

A resposta de dispatch confirma o enfileiramento. A autorização final deve ser acompanhada por consulta de status ou webhook.

HTTP/1.1 202 Accepted

{
  "ok": true,
  "message": "Documento enfileirado para processamento.",
  "data": {
    "id": "18f017f7-a69c-4fa6-89c7-05f52fcc8be4",
    "document_type": "nfe",
    "status": "draft",
    "processing_status": "queued",
    "requested_action": "authorize"
  }
}

Cancelamento e Carta de Correção

Só é possível cancelar ou corrigir uma NF-e já authorized. Os dois endpoints são assíncronos como o dispatch: enfileiram o evento e a confirmação vem por /status ou webhook.

{
  "reason": "Cancelamento por erro operacional na emissao."
}

{
  "text": "Corrigir informacao complementar sem alterar valores fiscais."
}

Sequência recomendada para a primeira emissão

1. Criar o rascunho com o payload completo.
2. Executar o build assinado se quiser revisar XML antes do envio.
3. Disparar action=authorize.
4. Acompanhar por /status ou webhook.
5. Quando autorizado, baixar XML e DANFE.
6. Se houver rejeição, revisar o retorno traduzido antes de reenviar.

Máquina de estados resumida

draft
  ├─ build(sign=false) ─→ built_unsigned
  ├─ build(sign=true)  ─→ built_signed
  └─ dispatch(authorize) → queued → processing
                                  ├─ authorized ─┬─ cancel      → cancelled
                                  │              └─ corrections → correction registrada
                                  ├─ authorize_pending → authorized | error
                                  └─ error / failed

Disponibilidade atual da v1

NF-e recebidas — DFe do destinatário

Além de emitir, a API captura as NF-e emitidas contra o CNPJ da empresa no DFe do destinatário (Ambiente Nacional). A sincronização avança por NSU e importa o resumo primeiro; o XML completo só fica disponível depois que a empresa registra a ciência da operação, como manda a SEFAZ.