Limites de transação

Como a BlendFi limita o volume de transações em duas camadas, um teto por operação na plataforma e um teto diário e mensal por usuário em tiers, e como solicitar alteração.

A BlendFi controla o volume de transações em duas camadas: um teto por operação que vale para qualquer operação na plataforma, e um teto diário e mensal por cliente final, resolvido a partir de um tier gerenciado pela BlendFi. Toda conversão (onramp e offramp) passa pelas duas checagens no aceite da cotação. Se alguma camada estoura, a chamada falha com transaction_limit_exceeded (HTTP 422), nenhuma reserva é feita e a conversão não é criada. Todos os limites são em BRL.

As duas camadas

Camada	Quem define	Vale para	Como varia
Teto por operação da plataforma	BlendFi	Toda conversão da plataforma	Valor único, hoje uniforme
Tier por cliente final	BlendFi, por usuário	Cada cliente final do parceiro	Tetos diário e mensal; um tier por usuário

A ordem da checagem é teto da plataforma primeiro, depois o tier do usuário. A primeira camada que estoura é a que aparece na resposta.

Teto por operação da plataforma

Um único valor em BRL define o máximo que uma operação pode carregar, do início ao fim. Vale para todo aceite de cotação na plataforma. A BlendFi não publica o valor exato; ele é dimensionado para absorver o tráfego dos parceiros e raramente afeta um parceiro individual.

O teto é por operação, não por dia. Ele só avalia o tamanho desta operação, não quanto já foi movimentado no dia ou no mês. Esse outro lado é o tier do usuário.

Tier por cliente final

Todo cliente final tem um tier de limite (por exemplo tier_0, tier_1, e por aí vai). O tier carrega:

Um teto diário em BRL: a soma das conversões do usuário no dia corrente (horário de Brasília).
Um teto mensal em BRL: a soma das conversões do usuário no mês corrente.

Um usuário recém-criado começa no tier padrão. O tier pode ser revisado depois, em uma análise feita pelo time da BlendFi (veja Como solicitar alteração).

Você não enxerga o id do tier na resposta do usuário. As informações observáveis hoje são:

O risk_profile do usuário, retornado em GET /v1/users/:id e GET /v1/users. O perfil é preenchido server-side a partir do questionário do KYC de plataforma e reflete o segmento em que o usuário se encaixa; é informativo e não é um campo que você grava.
O erro transaction_limit_exceeded quando uma operação ultrapassaria o teto do usuário (veja Como sai a resposta de erro).

`risk_profile` é leitura apenas

risk_profile não é mais aceito como entrada em POST /v1/users nem em PATCH /v1/users/:id. Ele é preenchido pela BlendFi a partir da submissão do KYC de plataforma e pode mudar entre submissões se as respostas do cliente mudarem. Se você está migrando de uma integração que escrevia risk_profile, remova o campo dos seus payloads. Os valores existentes são preservados.

Fluxo de uma operação

Quando você aceita uma cotação, a BlendFi roda as duas checagens antes de reservar volume:

O valor que conta para o teto é o valor em BRL da operação no aceite da cotação. Para onramp, é o expected_source_amount. Para offramp, é o valor alvo em BRL carregado pela cotação.

Reset diário e mensal

O contador diário zera na virada do dia em horário de Brasília. O contador mensal zera no primeiro dia do mês, em horário de Brasília.

Cancelamento, expiração e falha

Quando uma conversão é cancelada (POST /v1/conversions/:id/cancel) ou termina em expired ou failed, o volume reservado é devolvido aos contadores do usuário. Uma conversão que não liquidou não come do teto.

A devolução é best-effort: no caso raro de a devolução falhar, os contadores se autocorrigem no próximo reset. Não há nada para você reprocessar do seu lado.

Como sai a resposta de erro

{
  "code": "transaction_limit_exceeded",
  "message": "Transaction amount exceeds the platform per-transaction cap.",
  "request_id": "01KPR9F6MM8G147177J7ZQPJHG"
}

O code é estável: faça match em transaction_limit_exceeded. A message identifica a camada:

Mensagem	Camada	O que fazer
`Transaction amount exceeds the platform per-transaction cap.`	Teto por operação da plataforma	O valor desta operação é grande demais. Tente um valor menor, ou peça revisão à BlendFi se um teto maior fizer sentido.
`Transaction would exceed your daily transfer limit.`	Teto diário do usuário	O usuário gastou a maior parte do teto diário. Aguarde a virada do dia em Brasília, ou peça revisão do tier.
`Transaction would exceed your monthly transfer limit.`	Teto mensal do usuário	O usuário gastou a maior parte do teto mensal. Aguarde o primeiro dia do mês, ou peça revisão do tier.

Como solicitar alteração

O tier por usuário pode ser revisado em uma análise do time da BlendFi. Há dois canais:

API do parceiro (preview)

POST /v1/users/{user_id}/limit-upgrade-requests é o canal pelo parceiro. É o endpoint que a sua integração vai chamar quando o fluxo de revisão for habilitado. Hoje o endpoint responde 501 limit_upgrade_not_available, para você instrumentar o caminho com antecedência; ele vai começar a aceitar pedidos em uma versão futura. Até lá, use o canal manual abaixo.

Quando estiver habilitado, o endpoint recebe o id do usuário no path e um header Idempotency-Key. Não há body para iniciar o pedido; o time da BlendFi analisa o histórico do usuário e retorna o resultado.

Canal manual

Para revisar o tier de um usuário hoje, fale com o time da BlendFi informando:

O user_id cujo tier deve ser revisado.
O volume diário e mensal alvo para esse usuário, em BRL.
O contexto que justifica o pedido (volume em regime, picos esperados, mudança de modelo de negócio).

Os tetos da plataforma são revisados pelo mesmo canal e em outra frequência.

FAQ

Os limites valem no sandbox? Sim. O sandbox usa os mesmos limites da plataforma e do usuário. Use isso para verificar o tratamento de transaction_limit_exceeded no seu código antes de chegar em produção.

O que conta para o limite, o valor da cotação ou o valor liquidado? O valor em BRL no aceite da cotação. Para onramp, expected_source_amount. Para offramp, o valor alvo em BRL da cotação. Diferenças entre o esperado e o recebido (offramp sub ou sobrefinanciado) não alteram o que já foi contado; a devolução na falha terminal ou no cancelamento traz o contador de volta.

Dois aceites simultâneos do mesmo usuário que somados estouram o teto, qual passa? O primeiro a reservar passa. O segundo recebe 422 transaction_limit_exceeded. A checagem e a reserva são atômicas.

Como sei quanto do teto de um usuário já foi consumido? Hoje não há endpoint público para consultar o consumo. Se você precisa desse dado para um painel interno ou alerta, fale com o time da BlendFi.

Posso trocar o tier de um usuário? Não diretamente. O tier é gerenciado pela BlendFi; o parceiro pede a revisão (veja Como solicitar alteração) e a BlendFi aplica.

Por que risk_profile aparece na resposta do usuário se eu não posso setar? É uma classificação server-side trazida do KYC de plataforma. É informativa, útil para a sua própria segmentação, e pode oscilar entre submissões. Ela não determina o tier; o tier é uma atribuição separada.