Guia de limites
O teto de saída é por conta, por operação e por janela. Não é uma regra de
política: pixOut.maxAmount não é mais
avaliado. Quem estoura o teto recebe 422 limit_exceeded_transaction.
Tipos de limite
Quatro operações: pix_out, ted_out, boleto, internal_out.
Quatro janelas, em America/Sao_Paulo:
Não misture os nomes. No pedido a janela é snake_case. Na leitura, a por
transação é camelCase. daytime, nighttime e monthly coincidem.
Camadas de teto, da mais específica para a mais geral:
- Conta — teto próprio gravado no ledger.
- Padrão do tenant — vale para a conta que ainda não tem a célula.
- Padrão global — o mesmo, quando o tenant também não definiu.
- Cadastro anterior (
source: legacy) — o MySQL de antes do ledger, só enquanto a operação não tem nenhum teto próprio. - Operador — só na credencial do internet banking. A credencial BaaS
não chama essa rota. Na saída,
min(conta, operador). - Teto do liquidante no PIX — independente. Um teto local de PIX não o substitui; o liquidante continua barrando.
Como é calculado
Para cada célula (operação × janela) a precedência é:
Sem teto efetivo a janela é fail-open: o pagamento não é barrado por
limite local. limitBrl vem null. Nas janelas que acumulam, usedBrl
e availableBrl também vêm null, e a tela mostra a janela como aberta.
O cadastro anterior não tem mensal e usa horário 07:00–22:00 / 22:00–07:00. O ledger usa 06:00–20:00 / 20:00–06:00. O primeiro teto próprio de uma operação desliga o legado da operação inteira. Na aprovação de um pedido (e em qualquer escrita de teto da conta), as outras janelas que ainda vinham do cadastro anterior passam a ser tetos próprios, com os mesmos valores. O mensal aberto não é gravado. A partir daí o horário é o do ledger.
singleTransfer é o teto de cada envio. Não acumula: a resposta traz
limitBrl (e scope / source, quando o ledger tem) e omite usedBrl,
availableBrl e resetsAt.
usedBrl é o que já saiu na janela que está aberta. availableBrl é o
que ainda cabe. A janela que não está aberta mostra a próxima ocorrência,
com usado zero e sem resetsAt: o período que já fechou não conta mais.
O mês é o mês calendário, não trinta dias corridos. Com teto de operador,
o disponível da saída é o menor entre a conta e o operador.
Ler o disponível
GET /v1/accounts/{accountId}/limits/available devolve as quatro
operações, cada uma com as quatro janelas. As que acumulam trazem usado
e restante. singleTransfer traz só o teto.
source na janela diz de onde veio o teto: account, tenant_default,
global_default ou legacy. No item da operação, source: legacy
significa que a operação inteira ainda está no cadastro anterior.
GET /v1/accounts/{accountId}/pix/limits está deprecated. Devolve só
os tetos de PIX do liquidante, sem usado, e aponta Link para
/limits/available.
Pedir um aumento
Pela API ou pela página Limites do backoffice da API. As duas abrem o
mesmo pedido. O pedido nasce em awaiting_documents e não entra na fila
até POST .../submit. Os documentos do catálogo são opcionais: dá para
enviar sem arquivo. Se houver arquivo, o antivírus precisa aprová-lo
antes do submit. Aí o status vira pending_review e a CorpX analisa.
Não muda o teto. Ao aprovar, aplica o valor na hora. O valor aprovado pode ser menor que o pedido, nunca
maior. effectiveAt fica null: não há carência no teto da conta.
No backoffice, quem pede informa o CPF de quem opera (11 dígitos, dígitos verificadores válidos) e confirma com TOTP. O IP enviado é o do servidor do painel, não o do browser. Viewer só lê. Tenant admin e tenant manager criam e cancelam.
201:
Use operation para manter o formato de uma operação ou operations para
abrir de 1 a 4 operações distintas no mesmo lote. Não envie os dois campos.
O lote compartilha janela, valor pedido, documentos, mensagens e decisão.
Cada operação continua aparecendo em bundle.items, com seu teto atual e o
valor aprovado. Em single_transfer, TED é limitada a R$ 14.999,99; se a
conta já estiver nesse teto, ela aparece em skipped com
reason: ted_single_cap e as demais operações seguem normalmente.
requestedLimitBrl tem de ser maior que o teto efetivo daquela janela.
currentLimitBrl é esse teto no momento do pedido, inclusive quando ele
ainda vem do cadastro anterior. Só é 0 quando a janela está aberta.
Valor igual ou menor é 422 limit_request_not_above_current.
Em conta ainda no cadastro anterior, a aprovação grava a janela pedida e também as outras janelas legadas da mesma operação, com os valores de então. O horário passa a ser o do ledger.
Idempotência
Idempotency-Key é obrigatório (até 128 caracteres) e identifier tem de
ser idêntico ao header. A mesma chave devolve o pedido original com
201, mesmo que o corpo mude, e não abre outro pedido. Outra chave, com
um pedido ainda aberto (awaiting_documents, pending_review ou
info_requested) para a mesma operação e janela, é
409 limit_request_pending.
Quem pediu e o risco
X-Acting-Document é obrigatório: CPF (11 dígitos) ou CNPJ (14). É o
documento que volta no webhook para você avisar a pessoa certa.
X-Acting-Ip é o IP do operador, não o do seu servidor. No backoffice da
API o painel preenche os dois: o CPF que o operador digitou e o IP de
origem do BFF.
risk é opcional. action é allow, challenge ou deny; score, se
vier, fica entre 0 e 1. O bloco só é armazenado e mostrado ao analista.
deny não recusa o pedido.
justification é obrigatória, até 500 caracteres.
Documentos
GET /v1/limit-requests/document-types?holderType=PF|PJ devolve o catálogo:
required e additional, cada um com type, label e description.
PF e PJ saem do documento da conta (11 ou 14 dígitos). O rótulo já vem
pronto. Nenhum tipo do catálogo é obrigatório: required sai vazio e
tudo vem em additional.
Cada tipo aceita vários arquivos (frente e verso, três extratos). O upload
é o mesmo da evidência de MED: POST .../evidence/upload-url devolve um
PUT assinado de 15 minutos, o browser envia o arquivo direto ao
armazenamento, e POST .../evidence/add registra. O arquivo passa por
verificação de tipo, antivírus e sanitização. scanStatus fica PENDING
até o resultado. downloadUrl só existe com APPROVED. REJECTED não
conta e pode ser substituído por outro arquivo.
Limites: 5 MB por arquivo, 30 arquivos e 60 MB por pedido. Tipos:
application/pdf, image/jpeg, image/png, image/webp.
POST .../submit avança awaiting_documents para pending_review mesmo
sem arquivo. O catálogo não marca tipo obrigatório.
Sem submit em 7 dias (documentsDueAt), o pedido é cancelado. O webhook
limit_request.updated sai com reason: expired.
Anexo só em awaiting_documents ou info_requested. Nos outros status a
resposta é 409 limit_request_closed.
Se a análise pedir mais coisa, o status volta para info_requested com uma
mensagem em messages e, se houver, os tipos em documentTypes. O cliente
responde com arquivo e um texto opcional (POST .../messages) e chama
submit de novo. O prazo de 7 dias recomeça. Arquivo enviado antes do
pedido do analista não atende o tipo pedido.
Acompanhar e cancelar
GET /v1/accounts/{accountId}/limit-requests?status= devolve
{ "items": [...] }. status filtra awaiting_documents, pending_review,
info_requested, approved, refused ou cancelled. Sem filtro, devolve todos.
GET .../limit-requests/{id} acrescenta decisionMessage, effectiveAt e
events: [{ "at", "status", "message" }]. Só entram eventos públicos. A
nota interna do analista não sai nesta API.
POST .../limit-requests/{id}/cancel cancela awaiting_documents,
pending_review ou info_requested. Qualquer outro status é
409 limit_request_closed. O cancelamento também dispara o
webhook de atualização. Cancelar não pede TOTP no backoffice.
Status
Não existe estado “aprovado mas ainda não aplicado”.
Eventos
A aprovação emite limit_request.updated e account.limits.updated, sem
ordem garantida entre os dois. Deduplique pelo id do envelope. Quando o
valor importar, releia GET /limits/available.
Assinatura com lista de eventos vazia recebe tudo. Assinatura com lista explícita só recebe o evento se ele estiver na lista.
O exemplo completo de cada envelope está em Webhooks.