Skip to navigation

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:

Janela no pedidoCampo em GET /limits/availableO que éHorário no ledger
single_transfersingleTransferUma operação—
daytimedaytimeJanela diurna06:00–20:00
nighttimenighttimeJanela noturna20:00–06:00
monthlymonthlyMês calendário—

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:

  1. Conta — teto próprio gravado no ledger.
  2. Padrão do tenant — vale para a conta que ainda não tem a célula.
  3. Padrão global — o mesmo, quando o tenant também não definiu.
  4. Cadastro anterior (source: legacy) — o MySQL de antes do ledger, só enquanto a operação não tem nenhum teto próprio.
  5. Operador — só na credencial do internet banking. A credencial BaaS não chama essa rota. Na saída, min(conta, operador).
  6. 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 é:

teto próprio da conta
│ (não há)
▼
cadastro anterior da operação, se ela ainda não tem teto próprio
│ (não há, ou a operação já tem teto próprio)
▼
padrão do tenant
│ (não há)
▼
padrão global
│ (não há)
▼
fail-open: a janela não barra

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.

curl -X POST "https://tenant.api.corpx.com/v1/accounts/$ACCOUNT_ID/limit-requests" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3f1c0b6e-9a2d-4c71-8e55-1b7a0d4c9e21" \
-H "X-Acting-Document: 39053344705" \
-H "X-Acting-Ip: 200.10.20.30" \
-d '{
"operations": ["pix_out", "boleto", "ted_out"],
"window": "daytime",
"requestedLimitBrl": 50000,
"justification": "Folha de pagamento do mês.",
"identifier": "3f1c0b6e-9a2d-4c71-8e55-1b7a0d4c9e21",
"risk": {
"provider": "castle",
"action": "allow",
"score": 0.12,
"policyName": "ib-limit-increase",
"evaluatedAt": "2026-10-02T18:00:00Z"
}
}'

201:

{
"id": "lr_01J9XQ8K2M3N4P5Q6R7S8T9U0V",
"status": "awaiting_documents",
"operation": "pix_out",
"window": "daytime",
"currentLimitBrl": 20000,
"requestedLimitBrl": 50000,
"approvedLimitBrl": null,
"justification": "Folha de pagamento do mês.",
"identifier": "3f1c0b6e-9a2d-4c71-8e55-1b7a0d4c9e21",
"decisionMessage": null,
"effectiveAt": null,
"createdAt": "2026-10-02T18:00:01Z"
}

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

StatusSignificado
awaiting_documentsAberto, fora da fila, até o submit. Expira em 7 dias.
pending_reviewNa fila. O teto ainda é o antigo.
info_requestedO analista pediu mais informações. Fora da fila. Expira em 7 dias.
approvedAprovado e aplicado. approvedLimitBrl é o teto que passou a valer e pode ser menor que o pedido.
refusedRecusado. O teto não mudou. decisionMessage explica.
cancelledCancelado por quem pediu, ou porque o submit não veio no prazo.

Não existe estado “aprovado mas ainda não aplicado”.

Eventos

EventoOuça para
limit_request.createdSaber que um pedido foi aberto, ainda em awaiting_documents. Não sai de novo no replay da mesma Idempotency-Key.
limit_request.updatedSaber que o pedido mudou. reason é submitted (entrou na fila), decided (aprovado, recusado ou cancelado por quem pediu), info_requested ou expired.
account.limits.updatedSaber que um teto mudou de verdade (aprovação, staff ou titular). Não sai para padrão de tenant/global nem quando um afrouxamento de operador já agendado passa a valer.

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.

Erros

CódigoHTTPQuando
missing_idempotency_key400Sem Idempotency-Key, ou chave acima de 128 caracteres
invalid_identifier400identifier diferente da chave
invalid_justification400Vazia ou acima de 500 caracteres
invalid_risk400action ou score fora do contrato
acting_document_required400Sem X-Acting-Document
invalid_acting_document400Documento que não é CPF nem CNPJ
limit_request_operation_unavailable422operation ou window fora da tabela acima
limit_request_not_above_current422Valor pedido (ou aprovado) não supera o teto efetivo
limit_request_above_requested422Valor aprovado maior que o pedido
limit_request_pending409Já existe pedido aberto para a mesma operação e janela
limit_request_closed409Anexo, envio ou cancelamento num pedido que não aceita mais essa ação
limit_request_documents_missing422submit quando um tipo marcado como obrigatório não tem arquivo APPROVED. O catálogo atual não marca nenhum. details.missing lista os tipos
limit_request_info_missing422submit em info_requested sem o que foi pedido
limit_request_document_type_invalid422documentType fora do catálogo desta conta
limit_request_not_found404id inexistente nesta conta