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.

Limites de valor, prazo e CET​

Antes de criar a operação, a API valida (regra most-restrictive-wins entre as camadas):

  • Limites de valor (cedente / sacado / originador, configurados pelo Backoffice): fora da janela permitida → 403 com LIMIT_MAX_OPERATION_VALUE ou LIMIT_MIN_OPERATION_VALUE.
  • Limites do token M2M: max_operation_value_brl, min_term_days, max_term_days → 403 (LIMIT_*).
  • 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).