Valores do Recebível — Net Future Value e antecipação parcial

Três valores descrevem cada recebível na API, e eles não são sinônimos. Confundi-los é a origem mais comum de divergência de conciliação. Os campos exatos de request/response estão na Referência Técnica.

Cada valor tem dois nomes — leia o canônico

A API acabou de publicar um vocabulário canônico (*_future_value / *_present_value) ao lado dos nomes antigos. Os dois viajam juntos, com o mesmo número: nada foi renomeado, nada foi removido, nenhuma conta mudou.

Os nomes antigos continuam aceitos e devolvidos em toda a série 1.x, e serão removidos na versão 2.0 — uma mudança maior, publicada numa versão nova de URL (/v2) e anunciada no Changelog. Não há data prometida: a garantia é de versão, não de calendário. Se a sua integração já roda na 1.x, ela continua rodando — mas migre para os nomes canônicos antes de adotar a 2.0, onde os antigos não existem mais.

O de-para completo está na tabela abaixo. Esta página usa o nome canônico como primário e marca o antigo com [DEPRECATED — use ...].

De-para do vocabulário

Nome canônico (use este)	Nome deprecado	Onde aparece
gross_future_value	[DEPRECATED — use gross_future_value] gross_face_value	request + response
gross_future_value_deductions	(não existia — nasce no vocabulário novo)	request
net_future_value	[DEPRECATED — use net_future_value] net_face_value	request + response
requested_net_future_value	[DEPRECATED — use requested_net_future_value] requested_advance_value	request + response
requested_net_future_value_percent	(não existia — nasce no vocabulário novo)	request
present_value_discount	[DEPRECATED — use present_value_discount] discounted_value · discount_brl	response
net_present_liquid_value	[DEPRECATED — use net_present_liquid_value] liquid_value	response
opr_gross_future_value	[DEPRECATED — use opr_gross_future_value] opr_gross_face_value	response + webhook
opr_net_future_value	[DEPRECATED — use opr_net_future_value] opr_net_face_value	response + webhook
opr_present_value_discount	[DEPRECATED — use opr_present_value_discount] opr_discounted_value	response + webhook
opr_net_present_liquid_value	[DEPRECATED — use opr_net_present_liquid_value] opr_liquid_value	response + webhook

Cada par é equivalência exata: mesmo número, mesma semântica, mesma casa decimal. Nas respostas os dois nomes vêm sempre juntos, então você pode migrar a leitura campo a campo, sem big-bang. Nos requests você escolhe um dos dois — com uma única ressalva, a seguir.

Esta convivência é da série 1.x. Na 2.0 a coluna da direita desaparece: use esta tabela como roteiro de migração, e não como duas opções permanentes. A política completa está em Versionamento.

A única troca que não é 1:1: o bruto exige as deduções

Usar gross_future_value obriga a enviar gross_future_value_deductions no mesmo payload (envie 0 se não houver deduções). Sem ele, o pedido é recusado com 422 DEDUCTIONS_REQUIRED_WITH_GROSS.

A razão é deliberada: no nome canônico a diferença entre o bruto e o NFV passa a ser declarada por você, nunca inferida pela API. Vindo os três valores, a decomposição tem que fechar exatamente — net_future_value == gross_future_value − gross_future_value_deductions, sem tolerância de centavo — senão 422 VALUE_DECOMPOSITION_MISMATCH.

O nome deprecado gross_face_value continua aceito sozinho, exatamente como antes. Se você só quer renomear campos sem mudar payload, troque net_face_value e requested_advance_value primeiro e deixe o bruto para depois.

Migrando em fases, note uma inversão: gross_future_value_deductions é um campo novo, então usá-lo junto do bruto ainda deprecado (gross_face_value) é aceito — e, se a conta não fechar, o 422 VALUE_DECOMPOSITION_MISMATCH volta com o detail inteiro nos nomes canônicos (gross_future_value, net_future_value, expected_net_future_value), mesmo você tendo enviado o nome antigo. É o contrário da regra geral dos erros, em que o detail fala o vocabulário deprecado (veja Códigos de Erro).

Enviar os dois nomes com números diferentes é 422, nunca "o novo vence"

Se o mesmo valor chegar nos dois vocabulários com números divergentes, a API recusa o pedido inteiro com 422 VOCABULARY_CONFLICT e aponta os campos em conflito — sem efeito colateral, sem escolher um em silêncio. Enviar apenas um dos nomes, ou os dois com o mesmo número ("10000" e 10000.00 são o mesmo número), nunca gera esse erro. Os quatro códigos do vocabulário estão em Códigos de Erro.

Os três valores

Campo canônico	Nome deprecado	O que é
gross_future_value	gross_face_value	Valor de face bruto — o valor nominal do lastro (a NF-e/duplicata), antes de qualquer desconto aplicado a ele.
net_future_value	net_face_value	Net Future Value (NFV) — o valor de face futuro, líquido de quaisquer descontos já aplicados ao lastro (impostos na fonte ou outros). É o teto do que se pode antecipar daquele recebível, nas duas portas.
requested_net_future_value	requested_advance_value	Quanto do NFV você está antecipando.

A sigla NFV não mudou de significado

net_face_value era o Net Face Value; net_future_value é o Net Future Value. É o mesmo número e a mesma sigla de sempre — só o nome longo ficou mais preciso, porque o valor é o face futuro (no vencimento), em contraste com o valor presente que o cedente recebe hoje. Essa é a lógica de todo o vocabulário novo: *_future_value é o que vale no vencimento, *_present_value / net_present_* é o que vale hoje.

O NFV é o teto nas duas portas — por mecanismos diferentes

No fluxo direto, POST /v1/operations/direct recusa requested_net_future_value > net_future_value com 422. No fluxo de estoque não há como pedir acima do NFV, porque o deságio incide sobre o NFV e a antecipação é sempre de 100% dos itens: um item com gross_future_value de 12.000,00 e NFV de 10.000,00 é antecipado sobre 10.000,00, e a diferença de 2.000,00 é informação gerencial (os descontos já aplicados ao lastro), não base de cálculo.

O NFV é informado, não calculado

net_future_value é um input: quem cadastra o recebível informa o valor de face já líquido dos descontos. A API não deriva o NFV a partir do bruto. Em POST /v1/simulate e POST /v1/operations/direct, o bruto é opcional e, se omitido por completo, a API faz o contrário e assume gross_future_value = net_future_value. Em POST /v1/stock os dois são obrigatórios e os dois precisam ser maiores que zero — NFV 0 é recusado com 422 tanto no POST /v1/stock quanto no PATCH /v1/stock/{item_id} (um NFV zerado significa "nada antecipável").

Antecipação total e parcial

O percentual antecipado é, no fluxo direto, requested_net_future_value / net_future_value — um percentual do Net Future Value.

• requested_net_future_value == net_future_value → antecipação de 100%.
• requested_net_future_value < net_future_value → antecipação parcial.

Você pode declarar o percentual direto

requested_net_future_value_percent aceita o percentual do NFV (0 < p <= 100) em vez do valor absoluto em BRL. É mutuamente exclusivo com o valor absoluto: mandar os dois é 422 REQUESTED_VALUE_AMBIGUOUS.

A resolução é percent / 100 × net_future_value, arredondada a centavos sempre para baixo; o percentual 100 devolve o NFV exato, sem arredondamento. Exemplo: 60 sobre um NFV de 10.000,00 resolve 6.000,00.

O campo existe apenas em POST /v1/simulate e POST /v1/operations/direct. As portas de /v1/stock/* não o aceitam, justamente porque lá a antecipação é sempre de 100%.

O restante permanece no estoque

Numa antecipação parcial por POST /v1/operations/direct, o restante do NFV (net_future_value − requested_net_future_value) volta ao estoque como um item novo em IN_STOCK. Esse item:

• recebe o external_id <external_id_original>_REMAINDER_<8 primeiros caracteres do id da operação> — um identificador próprio, justamente para não conflitar com a NF de origem, cuja unicidade por (originador, external_id) continua intacta;
• herda da origem backing_type e os dados de NF-e (nfe_number, nfe_serie, nfe_key, nfe_issue_date, nfe_total_value) — é a mesma nota fiscal;
• nasce sempre pre_authorized: false (bloqueado), qualquer que seja o estado do item de origem — o resto não herda a liberação (veja o aviso abaixo);
• pode ser localizado em GET /v1/stock.

Exemplo: NFV de 10.000,00 com requested_net_future_value de 6.000,00 (60% do NFV) gera um item de estoque de 4.000,00 com external_id terminado em _REMAINDER_....

O resto normalmente nasce bloqueado e precisa ser liberado

pre_authorized é uma trava de antecipação: item com pre_authorized: false é recusado com 409 (stock_item_<id>_not_pre_authorized) tanto em request-anticipation quanto em simulate-anticipation.

O item-resto é sempre-restrito: ele nasce pre_authorized: false mesmo quando o item de origem estava liberado. A liberação vale para o lastro que foi antecipado, não para o pedaço que sobrou — decidir antecipar o resto é uma decisão nova, e ela é humana (fail-closed deliberado). Antes de antecipar o resto, libere-o com PATCH /v1/stock/{item_id} enviando {"pre_authorized": true}.

Se você integrou antes desta mudança contando com a herança, o sintoma é um 409 (stock_item_<id>_not_pre_authorized) ao antecipar um resto cuja origem estava liberada.

Antecipação parcial só existe no fluxo direto — o estoque recusa

POST /v1/stock/request-anticipation e POST /v1/stock/simulate-anticipation antecipam sempre 100% dos itens listados em stock_item_ids. Por isso o requested_net_future_value do corpo dessas duas rotas precisa ser exatamente igual à soma dos net_future_value dos itens selecionados; qualquer outro valor — para mais ou para menos — é recusado com 422 STOCK_REQUESTED_VALUE_MISMATCH.

Pedir uma fração do NFV pelo estoque não produz antecipação parcial nem item-resto: produz erro. Para antecipar parcialmente, use POST /v1/operations/direct. Para fixar o líquido a receber pelo estoque, use fees.total_liquid_value_brl.

O valor-base do deságio

O deságio (Taxas) incide sobre um valor-base que depende do fluxo:

Fluxo	Valor-base do deságio
POST /v1/simulate e POST /v1/operations/direct	requested_net_future_value (uma fração do NFV, ou o NFV inteiro em antecipação de 100%)
POST /v1/stock/simulate-anticipation e POST /v1/stock/request-anticipation	net_future_value do item — o NFV, sempre integral

Em nenhuma das portas o gross_future_value é base de cálculo: a diferença gross_future_value − net_future_value (o que você declara em gross_future_value_deductions) é informação gerencial — impostos na fonte e outros descontos já aplicados ao lastro. Consequência prática: um mesmo recebível antecipado integralmente produz o mesmo deságio pelas duas portas.

Os agregados da operação (opr_*)

O prefixo opr_ continua marcando o nível operação (agregado); o nome nu é o nível recebível/título.

Campo canônico	Nome deprecado	O que agrega
opr_gross_future_value	opr_gross_face_value	Soma dos gross_future_value. Não é base de cálculo em nenhuma porta. É a grandeza dos limites agregados de exposição nos recortes policy_total, policy_entity_default e assignor (403 LIMIT_AGGREGATE_EXPOSURE, sob LIMITS_RESOLUTION=aggregate_max); o recorte do sacado mede requested_net_future_value nas duas portas — ou seja, o valor ANTECIPADO em moeda de Net Future Value, e nao o bruto (regua unica: "o solicitado, em moeda NFV").
opr_net_future_value	opr_net_face_value	Soma dos net_future_value — o NFV agregado, igual nas quatro portas. Veja os dois avisos abaixo sobre antecipação parcial.
opr_present_value_discount	opr_discounted_value	Deságio total cobrado.
opr_net_present_liquid_value	opr_liquid_value	Valor efetivamente pago por PIX ao cedente. É este que o funding concilia.
opr_net_liquid_value	(não tem par — leia o aviso abaixo)	Projeção informativa de opr_net_present_liquid_value − other_debt_discounts.
other_debt_discounts	(não tem par)	Saldo devedor dos títulos vencidos e em aberto do mesmo cedente. Informativo — não é abatido do pagamento.

opr_net_liquid_value e opr_net_present_liquid_value são campos DIFERENTES

Os nomes são parecidos e o significado não é:

Campo	O que é	Concilia pagamento?
opr_net_present_liquid_value	O PIX ao cedente. Nome canônico de opr_liquid_value.	Sim
opr_net_liquid_value	Projeção informativa opr_net_present_liquid_value − other_debt_discounts. Não faz parte do vocabulário novo — não é o par de nada, e continua com esse nome.	Não

O net de opr_net_liquid_value não tem relação com o net do Net Future Value: lá significa "face líquido de descontos do lastro", aqui significa "líquido projetado de débitos vencidos do cedente". opr_net_liquid_value e other_debt_discounts não são persistidos e não afetam o pagamento. Se você está escrevendo a conciliação, o campo é opr_net_present_liquid_value.

opr_net_future_value é LASTRO, não valor antecipado — e não se soma entre operações

Os dois erros abaixo vêm da mesma causa e produzem conciliação errada em silêncio: nenhum dos dois dá erro, os dois só entregam um número maior do que o real.

1. Em antecipação parcial, ele não é o valor antecipado. opr_net_future_value agrega o lastro (soma dos net_future_value) nas quatro portas. Numa antecipação de 100% ele coincide com o valor antecipado; numa antecipação parcial pelo fluxo direto os dois divergem — NFV de 10.000,00 com requested_net_future_value de 6.000,00 devolve opr_net_future_value: "10000.00", e não 6000.00. Para a base do deságio de uma operação parcial, some o requested_net_future_value item a item em receivables[] — não há agregado pronto para isso.

2. Somá-lo entre operações conta o resto duas vezes. Como o campo reporta o lastro inteiro do recebível, a cadeia parcial → item-resto → antecipação do resto duplica:

Operação	opr_net_future_value (= opr_net_face_value)
1ª — parcial de 6.000,00 sobre um NFV de 10.000,00	10000.00
2ª — antecipação do item-resto _REMAINDER_ de 4.000,00	4000.00
Soma	14000.00 para um recebível cuja face é 10.000,00

Para lastro consolidado, some net_future_value por título (GET /v1/titles/{id}), que é único por operação e não se repete entre elas. (GET /v1/operations/{id}/titles devolve a forma resumida, sem o campo.)

Migrar o nome não conserta nada disso. opr_net_future_value traz exatamente o número que opr_net_face_value sempre trouxe: o campo novo herdou a semântica do antigo, não a corrigiu. Se você já tratava essas duas diferenças, nada muda; se não tratava, o problema é o mesmo nos dois nomes.

Cadeia de valor

A cadeia não é a mesma nas duas portas — o ponto em que o deságio entra muda.

Fluxo direto (POST /v1/operations/direct e POST /v1/simulate)

gross_future_value                     valor de face bruto do lastro
  − gross_future_value_deductions      descontos aplicados ao lastro (você declara)
= net_future_value                     Net Future Value (NFV) — teto enforçado (422)
  × percentual solicitado              requested_net_future_value_percent, se você usar
= requested_net_future_value           o que se antecipa; é a BASE do deságio
                                       (restante volta ao estoque como item _REMAINDER_)
  − opr_present_value_discount         deságio
= opr_net_present_liquid_value         o que o cedente recebe por PIX

Fluxo de estoque (/v1/stock/simulate-anticipation e /v1/stock/request-anticipation)

gross_future_value                     valor de face bruto do lastro
  − gross_future_value_deductions      informação GERENCIAL — não entra no cálculo
= net_future_value                     Net Future Value (NFV); é a BASE do deságio
                                       (sempre integral: 100% do item)
  − opr_present_value_discount         deságio
= opr_net_present_liquid_value         o que o cedente recebe por PIX

Sempre 100% dos itens de stock_item_ids: não há antecipação parcial nem item-resto por esta porta, e requested_net_future_value tem que confirmar exatamente a soma dos NFV (senão 422 STOCK_REQUESTED_VALUE_MISMATCH). Como a base é o próprio NFV, opr_net_present_liquid_value nunca supera o lastro.

Os valores no contrato de cessão

O contrato de cessão enviado para assinatura eletrônica declara, por recebível, dois números — e são os mesmos dois conceitos desta página:

Número no documento	O que é
o valor antecipado	quanto do NFV está sendo antecipado daquele recebível. Numa antecipação de 100% é o próprio NFV; numa antecipação parcial pelo fluxo direto é a fração solicitada.
o lastro (NFV)	o Net Future Value inteiro do recebível — o lastro cedido, independente da fração antecipada.

Os totais do documento somam exatamente esses dois números. O valor efetivamente pago por PIX é o opr_net_present_liquid_value (antecipado menos o deságio) e aparece em campo próprio.

Consequências que valem conferir na conciliação:

• numa antecipação de 100%, antecipado e lastro coincidem — os dois números são o mesmo por natureza, não por erro;
• numa antecipação parcial (só pelo fluxo direto), o antecipado é menor que o lastro;
• o gross_future_value não aparece no contrato: a diferença gross_future_value − net_future_value é informação gerencial, e não é cedida nem antecipada.

Data de corte da semântica do documento

A partir de 30/07/2026, 19:05 (horário de Brasília), o valor do recebível declarado no documento é o valor antecipado.

Documentos emitidos antes de 30/07/2026, 19:05 (horário de Brasília) preservam a semântica anterior e não são regerados — um contrato já assinado continua valendo exatamente como foi assinado. Ao conciliar documentos antigos, use a data de emissão para saber qual leitura se aplica.

Conciliando por título

Cada operação gera títulos (GET /v1/titles/{id}), e é neles que a conciliação por recebível acontece. Um detalhe do fluxo de estoque economiza horas de investigação:

No fluxo de estoque, requested_net_future_value do título é o BRUTO

No título criado por /v1/stock/request-anticipation, o campo requested_net_future_value (requested_advance_value) grava o gross_future_value do item — uma convenção pré-existente desse fluxo, mantida. O líquido do título é calculado sobre o NFV:

net_present_liquid_value = net_future_value − present_value_discount

Ou seja: quando o item tem deduções de lastro (bruto ≠ NFV), a subtração requested_net_future_value − present_value_discount não fecha. Use net_future_value, que volta em GET /v1/titles/{id}.

No fluxo direto não há essa diferença: lá o requested_net_future_value do título é o valor antecipado e a subtração fecha.

O net_present_liquid_value do título é também gravado como principal_value_brl, a base do saldo devedor — veja Saldos.