Como solicitar aumento de limite pela API

Aumentar o limite de uma conta deixou de ser um pedido manual pelo console: dá para abrir a solicitação pela API, anexar o comprovante que a justifica e acompanhar até a decisão.

São dois endpoints, e a ordem importa:

POST /api/v1/files — sobe o comprovante e devolve um file.id.
POST /api/v1/limits/request — abre o pedido mandando esse file.id.

Depois é só fazer polling no GET /api/v1/limits/request/{limitRequestId} até o status sair de IN_REVIEW.

O documento não vai no corpo do pedido

Um erro comum é tentar mandar o arquivo (ou uma URL dele) direto no POST /api/v1/limits/request. Não funciona: o pedido só aceita o fileId de um arquivo que já está na Woovi. Suba o arquivo primeiro.

Requisitos

Seu AppID precisa de três escopos (como adicionar escopos):

Escopo	Para quê
`FILE_POST`	subir o comprovante no endpoint de arquivos
`ACCOUNT_LIMITS_REQUEST_POST`	abrir o pedido de aumento
`ACCOUNT_LIMITS_GET`	consultar o limite atual e fazer o polling do pedido

1. Subir o comprovante

O arquivo vai como multipart/form-data no campo file, com purpose=ACCOUNT_LIMIT_REQUEST. Aceita application/pdf, image/png, image/jpeg e image/webp, até 10 MiB por arquivo (detalhes em Como fazer upload de um arquivo).

curl -X POST "https://api.woovi.com/api/v1/files" \
  -H "Authorization: <appID>" \
  -F "[email protected]" \
  -F "purpose=ACCOUNT_LIMIT_REQUEST"

{
  "file": {
    "id": "68c7d0a1f0b2c3d4e5f60718",
    "correlationID": "3fa17751-d522-426d-8425-80a3ef65d622",
    "purpose": "ACCOUNT_LIMIT_REQUEST",
    "fileName": "faturamento.pdf",
    "contentType": "application/pdf",
    "size": 20480,
    "url": "https://woovi-files.s3.amazonaws.com/...",
    "urlExpiresAt": "2026-09-03T18:04:45.987Z",
    "createdAt": "2026-09-03T17:49:45.968Z"
  }
}

Guarde o file.id — é ele que vai no passo 2.

tip

O purpose importa. Um arquivo subido com outro purpose (por exemplo DISPUTE_EVIDENCE) não é aceito no pedido de limite. Se isso acontecer, suba de novo com o purpose certo; não é preciso apagar o primeiro.

2. Consultar o limite atual

O pedido usa o mesmo vocabulário de campos do GET /api/v1/limits/{accountId}, então o caminho natural é ler o limite atual, subir os campos que você precisa e mandar de volta.

curl "https://api.woovi.com/api/v1/limits/6842ef6d05629d74e34d05cd" \
  -H "Authorization: <appID>"

{ "limits": { "pixDayLimit": 4000000, "pixNightLimit": 100000, "...": "..." } }

3. Abrir o pedido com o `fileId`

curl -X POST "https://api.woovi.com/api/v1/limits/request" \
  -H "Authorization: <appID>" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "companyBankAccountId": "6842ef6d05629d74e34d05cd",
    "pixDayLimit": 5000000,
    "pixNightLimit": 200000,
    "documents": [{ "fileId": "68c7d0a1f0b2c3d4e5f60718" }],
    "description": "faturamento dos ultimos 12 meses"
  }'

Campo	Obrigatório	Descrição
`companyBankAccountId`	Sim	A conta cujo limite deve subir.
`pixDayLimit` / `pixNightLimit`	Sim	Limite diurno e noturno pedidos, em centavos.
`pixOut` / `pixIn` por titularidade	Não	Os oito campos por titularidade, com os mesmos nomes do `GET` de limites.
`documents`	Sim	De 1 a 10 itens, cada um com o `fileId` do passo 1.
`description`	Não	Texto livre para o analista que vai revisar.
`limitRequestReason`	Não	Motivo do pedido.

Resposta 201:

{
  "limitRequest": {
    "id": "68c7d0a1f0b2c3d4e5f6071a",
    "companyBankAccountId": "6842ef6d05629d74e34d05cd",
    "status": "IN_REVIEW",
    "requestedLimits": { "pixDayLimit": 5000000, "pixNightLimit": 200000 },
    "documents": [{ "fileName": "faturamento.pdf", "contentType": "application/pdf" }],
    "description": "faturamento dos ultimos 12 meses",
    "createdAt": "2026-09-03T17:49:59.204Z",
    "updatedAt": "2026-09-03T17:49:59.204Z"
  }
}

Guarde o limitRequest.id para acompanhar o pedido.

Regras que o pedido precisa respeitar

Nenhum campo pode vir abaixo do valor atual da conta.
Pelo menos um campo precisa vir acima do atual — um pedido que não sobe nada é recusado.
Só pode existir um pedido IN_REVIEW por conta de cada vez.

4. Acompanhar até a decisão

curl "https://api.woovi.com/api/v1/limits/request/68c7d0a1f0b2c3d4e5f6071a" \
  -H "Authorization: <appID>"

O status fica em IN_REVIEW enquanto a Woovi analisa, e depois vira:

APPROVED — o campo approvedLimits traz o que foi de fato concedido, que pode ser menor do que você pediu. Os limites efetivos da conta mudam no mesmo momento, então o GET /api/v1/limits/{accountId} já reflete os novos valores.
REJECTED — nada mudou na conta. Depois que o pedido é decidido, você pode abrir um novo.

{
  "limitRequest": {
    "id": "68c7d0a1f0b2c3d4e5f6071a",
    "status": "APPROVED",
    "requestedLimits": { "pixDayLimit": 5000000, "pixNightLimit": 200000 },
    "approvedLimits": { "pixDayLimit": 4500000, "pixNightLimit": 200000 },
    "documents": [{ "fileName": "faturamento.pdf", "contentType": "application/pdf" }],
    "createdAt": "2026-09-03T17:49:59.204Z",
    "updatedAt": "2026-09-03T19:12:03.881Z"
  }
}

info

approvedLimits não aparece enquanto o pedido está IN_REVIEW. A ausência do campo é a forma de saber que ainda não há decisão — não trate approvedLimits vazio como aprovação.

Para listar todos os pedidos da sua empresa, do mais novo para o mais antigo, use GET /api/v1/limits/request (aceita limit, máximo 100, e skip).

Erros

Status	Quando acontece	Corpo
`400`	O `fileId` não existe, é de outra empresa, ou foi subido com outro `purpose`	`{"error":"Document 68c7…: File not found"}`
`400`	Algum limite veio abaixo do valor atual	`{"error":"Requested limit cannot be less than the current value"}`
`400`	Nenhum limite é maior que o atual	`{"error":"At least one limit must be greater than the current value"}`
`400`	Nenhum documento enviado	`{"error":"documents At least one document is required"}`
`403`	O AppID não tem o escopo `ACCOUNT_LIMITS_REQUEST_POST`	`{"error":"Application does not have required scope: ACCOUNT_LIMITS_REQUEST_POST"}`
`404`	A conta não existe ou é de outra empresa	`{"error":"Account not found"}`
`409`	A conta já tem um pedido em análise	`{"error":"Limit request already in review"}`

Isolamento entre empresas

Tanto a conta quanto o arquivo são sempre filtrados pela empresa do seu AppID. Uma conta de outra empresa responde 404 (nunca um 403), e um fileId de outra empresa responde 400 File not found — o id sozinho nunca confirma que o recurso existe.

Referência completa

Schemas, parâmetros e exemplos interativos na API Reference, em Account Limits.

Requisitos​

1. Subir o comprovante​

2. Consultar o limite atual​

3. Abrir o pedido com o fileId​

Regras que o pedido precisa respeitar​

4. Acompanhar até a decisão​

Erros​