Pular para o conteúdo principal

Taxas, PMP e Limites

Como a API resolve a taxa aplicada e quais limites são validados. Os campos exatos de request/response estão na Referência Técnica.

Hierarquia de taxas​

Se você não informar taxas (fees) na chamada, a API aplica a hierarquia, do nível mais específico ao mais genérico:

recebível > operação > cedente > sacado > policy do originador

A taxa de cada nível vem das policies pré-cadastradas pelo Backoffice. O campo fee_source na resposta indica qual nível forneceu a taxa de cada recebível (receivable, operation, assignor, payer, policy, liquid_value ou total_liquid_value).

Campos opcionais para direcionar a policy:

  • product_id — filtra as policies de taxa e os limites de valor por produto financeiro. Descubra os válidos em GET /v1/products.
  • policy_id — override: substitui a policy principal na resolução.

PMP — Prazo Médio Ponderado​

Quando a policy aplicável tem rate_schedule (taxa escalonada por faixa de dias), a API calcula o PMP da operação — a média dos dias até o vencimento ponderada pelo valor de cada recebível — e interpola a taxa mensal correspondente.

Na resposta de POST /v1/simulate:

  • weighted_avg_days — o PMP usado (em dias).
  • policy_used.rate_from_schedule — true se a taxa veio do rate_schedule.
  • policy_used.schedule_day_used — qual faixa de dias foi aplicada.

Na operação criada, o snapshot applied_fees_snapshot registra a taxa efetiva (effective_rate_pct) e a policy_version usada.

Simule antes de criar

Use POST /v1/simulate para ver o PMP e a taxa resultante antes de criar a operação.

Cálculo do desconto mensal​

O componente pro-rata de monthly_rate_pct usa juros simples com base de 30 dias:

desconto = valor-base × (taxa mensal / 100) × (dias até o vencimento + floating_days) / 30

O valor-base depende do fluxo: net_future_value — o Net Future Value (NFV), sempre integral — nas operacoes via estoque, e requested_net_future_value na simulacao/operacao direta. Em nenhum dos dois a base é o gross_future_value: a diferenca entre o bruto e o NFV (o que voce declara em gross_future_value_deductions) e informacao gerencial — descontos ja aplicados ao lastro. A distinção entre os três valores está em Valores do Recebível (NFV). floating_days soma ao prazo cobrado. Por exemplo, 25 dias até o vencimento com floating_days: 2 resultam em 27 dias na fórmula. Deságios percentuais (discount_pct) e descontos fixos (fixed_discount_brl) são cumulativos quando também informados.

Limites de valor e CET​

Antes de criar a operação, a API valida em camadas independentes — todas precisam passar:

  • Teto por operação da policy (per_operation_limit_brl, configurado no Backoffice): o valor desta operação, sozinho, não pode passar o teto → 403 com LIMIT_MAX_OPERATION_VALUE (detail.source: policy_per_operation). Desde a v1.6.0 esta é a única fonte de teto de valor por operação: a credencial de API não tem mais teto próprio, e nenhuma camada recusa por prazo do recebível — veja o changelog.

  • Exposição agregada em aberto por recorte (tese da policy / cedente / sacado): a soma das operações não liquidadas do recorte, mais esta operação, não pode passar o limite dele → 403 com LIMIT_AGGREGATE_EXPOSURE (scope diz qual recorte, detail.limit_origin diz de onde veio o teto).

  • Ente TRAVADO pela ancoragem de risco: quando a policy ancora o risco num dos lados (cedente ou sacado), a ausência de teto naquele lado significa bloqueio, e não "sem limite". O ente entra na conta com limite 0 e a operação é recusada → 403 com LIMIT_AGGREGATE_EXPOSURE, limit_brl: "0" e detail.limit_origin dizendo qual das duas situações ocorreu:

    • anchored_side_closed — ninguém definiu o default daquele lado;
    • side_default_zero — o default do lado foi configurado como 0 (bloqueio deliberado).

    No lado não ancorado vale o oposto: ausência de teto é "sem limite por aqui" — mas o que estiver configurado lá continua valendo normalmente.

    É assim que se escreve uma allowlist: default do lado ancorado em 0 (ou ausente) + limite próprio apenas nos entes que devem operar.

  • Limite POR ENTE configurado: só a tese não basta — é preciso existir teto por ente valendo para a operação → 403 com LIMIT_ENTITY_CONFIG_MISSING (e LIMIT_CONFIG_MISSING quando não há limite agregado nenhum). Basta o teto do cedente ou de um sacado.

    É recusa de configuração: resolve-se no Backoffice, não mudando o valor.

  • CET dentro da policy: se a taxa efetiva resultante sair do intervalo [min, max] da policy → 422 com CET_OUT_OF_BOUNDS.

Veja o formato completo do detail em Códigos de Erro.

Compatibilidade

O campo taxes é aceito como alias de fees (compatibilidade com a V1).

Na mesma linha, os valores monetarios tem um nome canonico e um deprecado, com o mesmo numero: net_future_value / net_face_value, requested_net_future_value / requested_advance_value, gross_future_value / gross_face_value, present_value_discount / discounted_value. Os deprecados seguem aceitos em toda a serie 1.x e sao removidos na 2.0; o de-para completo esta em Valores do Recebivel.