Venda a prazo (fatura e duplicatas)

Venda a prazo B2B tem um dado que pagamentos não representa: o parcelamento em duplicatas, com data de vencimento, que o financeiro do seu cliente concilia depois. É o bloco cobranca na raiz do payload da NF-e. pagamentos continua sendo a forma de pagamento efetiva (ex.: "15" boleto) e segue fechando o total transmitido. cobranca é informativo e financeiro: não altera vNF nem o que pagamentos já faz. O motor é passthrough aqui, nada é calculado. Para declarar a condição de pagamento, use opcionalmente pagamentos[].indicador: 0 é à vista e 1 é a prazo. Na NF-e que contém fatura ou duplicatas em cobranca, a ausência recebe 1 automaticamente; se você enviar um valor, ele prevalece. Fora da venda a prazo, a ausência mantém a tag indPag omitida. Este campo é exclusivo da NF-e nesta API.

Só NF-e (modelo 55): NFC-e documenta venda com pagamento imediato ao consumidor final e recusa o bloco com 422, mas só quando ele tem conteúdo de verdade ({} vazio passa batido, útil pra quem usa o mesmo payload nos dois modelos).
Duplicata exige fatura: no leiaute (XSD), fat e dup são irmãos independentes — mas as regras nacionais do MOC 7.0 Anexo I (grupo Y, p. 124) tornam duplicatas sem fatura uma combinação inválida: Y01-20 exige nFat/vOrig/vLiq quando há cobranca (mensagem 905) e Y10-10 exige que a soma das parcelas seja igual ao líquido da fatura (mensagem 851), mesmo quando a soma bate com o total da nota. Por isso a API recusa essa combinação antes de reservar o número fiscal: nada é emitido e nenhuma numeração é consumida. Envie sempre os dois juntos.
Fatura é tudo ou nada: se você envia fatura, os 4 campos (numero, valorOriginal, valorDesconto, valorLiquido) são obrigatórios juntos, e valorLiquido precisa ser exatamente valorOriginal − valorDesconto.
Vencimento é obrigatório e auditado: precisa ser uma data real (não só o formato), maior ou igual a hoje, e as parcelas precisam vir em ordem não-decrescente de vencimento.
Coerência auditada: quando há fatura E duplicatas, a soma de duplicatas[].valor precisa bater com o líquido da fatura.

Pré-requisitos

Item	Detalhe
Documento	NF-e (modelo 55) apenas
Emissor cadastrado	Com certificado A1 instalado e `ambienteFiscal` definido
Forma de pagamento	`pagamentos[].forma` continua obrigatório e fecha o total (ex.: `"15"` boleto, `"05"` crédito em loja). `pagamentos[].indicador` é opcional: `0` à vista, `1` a prazo

Emitindo com fatura e duplicatas

curl -X POST https://api.engineapi.com.br/v1/nfe \
  -H "x-api-key: ek_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "naturezaOperacao": "Venda a prazo",
    "destinatario": {
      "cnpjCpf": "12345678000199",
      "nome": "Cliente Exemplo LTDA",
      "indicadorIE": 1,
      "ie": "123456789",
      "endereco": {
        "logradouro": "Rua A", "numero": "100", "bairro": "Centro",
        "codigoMunicipio": "5211701", "municipio": "JANDAIA",
        "uf": "GO", "cep": "75950000"
      }
    },
    "items": [
      {
        "codigo": "P1",
        "descricao": "Mercadoria vendida a prazo",
        "ncm": "61091000",
        "cfop": "5102",
        "unidade": "UN",
        "quantidade": 1,
        "valorUnitario": 3000,
        "icms": { "origem": 0, "csosn": "102" }
      }
    ],
    "pagamentos": [{ "forma": "15", "valor": 3000, "indicador": 1 }],
    "cobranca": {
      "fatura": {
        "numero": "FAT-2026-001",
        "valorOriginal": 3000,
        "valorDesconto": 0,
        "valorLiquido": 3000
      },
      "duplicatas": [
        { "numero": "001", "vencimento": "2026-09-01", "valor": 1000 },
        { "numero": "002", "vencimento": "2026-10-01", "valor": 1000 },
        { "numero": "003", "vencimento": "2026-11-01", "valor": 1000 }
      ]
    }
  }'

O que sai no XML

O grupo vira <cobr> dentro de infNFe, entre <transp> e <pag> (estrutura validada contra o XSD oficial da NF-e 4.00):

<cobr>
  <fat>
    <nFat>FAT-2026-001</nFat>
    <vOrig>3000.00</vOrig>
    <vDesc>0.00</vDesc>
    <vLiq>3000.00</vLiq>
  </fat>
  <dup>
    <nDup>001</nDup>
    <dVenc>2026-09-01</dVenc>
    <vDup>1000.00</vDup>
  </dup>
  <dup>
    <nDup>002</nDup>
    <dVenc>2026-10-01</dVenc>
    <vDup>1000.00</vDup>
  </dup>
  <dup>
    <nDup>003</nDup>
    <dVenc>2026-11-01</dVenc>
    <vDup>1000.00</vDup>
  </dup>
</cobr>

Recupere o XML autorizado com GET /v1/nfe/xml/{accessKey}: ele é o artefato real que a SEFAZ recebeu, nunca uma remontagem.

duplicatas[].numero é opcional no payload, mas nunca fica de fora do documento. Se você não numerar as parcelas, a engineAPI preenche sequencial (001, 002…): o motor de emissão usa esse número como identificador interno da parcela, então ele nunca pode faltar no XML.

Campos do bloco `cobranca`

Campo	Obrigatório	Formato	Observação
`fatura.numero`	Só se `fatura` for enviada	1 a 60 caracteres	Número da fatura (`nFat` do leiaute)
`fatura.valorOriginal`	Só se `fatura` for enviada	R$, 2 casas	Valor original da fatura (`vOrig`)
`fatura.valorDesconto`	Só se `fatura` for enviada	R$, 2 casas	Valor do desconto da fatura (`vDesc`). Não pode ser maior que `valorOriginal`
`fatura.valorLiquido`	Só se `fatura` for enviada	R$, 2 casas	Valor líquido da fatura (`vLiq`). Precisa ser igual a `valorOriginal − valorDesconto`, e igual à soma de `duplicatas[].valor` quando houver duplicatas
`duplicatas[].numero`	Não	1 a 60 caracteres	Número da duplicata (`nDup`). Ausente = sequencial automático
`duplicatas[].vencimento`	Sim	`AAAA-MM-DD`	Data de vencimento da duplicata (`dVenc`). Calendário real, `>=` hoje, e não-decrescente entre as parcelas
`duplicatas[].valor`	Sim	R$, mínimo 0.01	Valor da duplicata (`vDup`), até 120 por nota

duplicatas sem fatura não é aceito. No leiaute, dup não é filho de fat — os dois vivem direto sob cobranca e são estruturalmente independentes. Mas as regras nacionais do MOC 7.0 Anexo I (grupo Y, p. 124) tornam a combinação inválida: Y01-20 exige nFat/vOrig/vLiq sempre que há cobranca (mensagem 905), e Y10-10 exige que a soma das parcelas seja igual ao líquido da fatura (mensagem 851) — sem fat, não há vLiq pra comparar.Medimos isso emitindo de verdade em homologação (documento assinado sem <fat>, três parcelas somando exatamente o total da nota → rejeitado com 851 naquela emissão). Por isso a API passou a recusar localmente, antes de numerar, em vez de deixar a rejeição acontecer depois da transmissão, com o número fiscal já consumido.Enviar só fatura, sem detalhar as parcelas, continua válido.

A soma das duplicatas precisa bater com o líquido da fatura, quando os dois são informados. A comparação usa o valor como vai no documento (2 casas decimais) e é uma igualdade EXATA sobre esse valor, não uma tolerância. Divergência em qualquer direção (soma maior OU menor) devolve 422 COBRANCA_INVALIDA antes da numeração, citando os dois valores.

Vencimento fora de ordem entre as parcelas recusa. As duplicatas precisam vir em ordem não-decrescente de vencimento (a 2ª parcela não pode vencer antes da 1ª). Um vencimento anterior à data de emissão também recusa: a engineAPI não emite nota com parcela “vencida antes de nascer”.

Erros comuns

O que aconteceu	Resposta	Como corrigir
Soma de `duplicatas[].valor` diverge do líquido da fatura	`422 COBRANCA_INVALIDA`	Ajuste os valores, remova `duplicatas` se não há parcelamento formal, ou remova o bloco `cobranca` inteiro se a operação não for venda a prazo — nunca omita só `fatura` (duplicatas sem fatura também recusa)
`duplicatas` enviada sem `fatura`	`422 COBRANCA_INVALIDA`	Envie o bloco `fatura` (`numero`, `valorOriginal`, `valorDesconto`, `valorLiquido`, com `valorLiquido` igual à soma das parcelas) ou remova `duplicatas`
`fatura.valorLiquido` != `valorOriginal − valorDesconto`	`422 COBRANCA_INVALIDA`	Corrija o valor líquido
`fatura.valorDesconto` maior que `valorOriginal`	`422 COBRANCA_INVALIDA`	O desconto não pode ser maior que o valor original
`duplicatas[].vencimento` anterior a hoje, ou fora de ordem entre as parcelas	`422 COBRANCA_INVALIDA`	Ajuste as datas: `>=` hoje e não-decrescente entre parcelas
`cobranca` com conteúdo (fatura ou duplicatas) numa NFC-e	`422 COBRANCA_NAO_SUPORTADA_NFCE`	Emita uma NF-e (modelo 55). NFC-e não tem o conceito de fatura a prazo
`duplicatas[]` sem `valor` ou sem `vencimento`	`400` nomeando o campo	Os dois são obrigatórios por duplicata
`vencimento` fora do formato `AAAA-MM-DD`, ou uma data que não existe (ex.: `"2026-02-30"`)	`400` nomeando o campo	Use o formato ISO com uma data de calendário real
`fatura` enviada com só alguns dos 4 campos	`400` nomeando o campo	Os 4 campos (`numero`, `valorOriginal`, `valorDesconto`, `valorLiquido`) são obrigatórios juntos
Mais de 120 duplicatas	`400` nomeando o campo	O leiaute limita `dup` a 120 ocorrências por nota

Todos os 422 acima são locais: acontecem antes de qualquer chamada à SEFAZ e antes da numeração, então nada é emitido e nenhum número fiscal é consumido. Em lote (POST /v1/nfe/batch) o item falha no pré-voo e sai FAILED com o mesmo code, sem retry.

Referências

MOC (Manual de Orientação do Contribuinte) Anexo I, grupo Y (cobr/ fat/dup): regras de negócio da fatura (Y04/Y05/Y06), do número da duplicata (Y07/Y08), do vencimento (Y09) e da soma das duplicatas contra a fatura (Y10).
Leiaute NF-e 4.00, elemento cobr dentro de infNFe (irmão de transp e pag).
Catálogo de erros: todos os code de negócio da API.
Emitir NF-e: o payload completo, campo a campo.
Campos de NFe: referência de todo campo aceito.

Comece aqui

Emissão

Tributação

Erros e operação

IA e automação

Conceitos

Migração

Perguntas frequentes

Venda a prazo (fatura e duplicatas)

Pré-requisitos

Emitindo com fatura e duplicatas

O que sai no XML

Campos do bloco `cobranca`

Erros comuns

Referências

​Pré-requisitos

​Emitindo com fatura e duplicatas

​O que sai no XML

​Campos do bloco cobranca

​Erros comuns

​Referências

Pré-requisitos

Emitindo com fatura e duplicatas

O que sai no XML

Campos do bloco `cobranca`

Erros comuns

Referências