Como consultar os limites de uma conta via API?

Para consultar os limites configurados em uma conta bancária do merchant, utilize o endpoint GET /api/v1/limits/{accountId}.

O endpoint retorna o conjunto mais recente de limites configurados para a conta, contendo apenas os campos públicos — campos internos são filtrados antes da resposta.

A resposta tem dois blocos: limits, com os tetos configurados na conta, e usage, com quanto de cada teto já foi consumido na janela em vigor — veja Consumo em tempo real.

info

Antes de usar este endpoint, garanta que sua empresa tenha a feature ACCOUNT_LIMITS_PUBLIC_API habilitada e que sua aplicação possua o scope ACCOUNT_LIMITS_GET. Veja Primeiros passos com a API de Account Limits para detalhes.

Referência completa

Para o schema, parâmetros e exemplos interativos, veja a API Reference.

Precisa de mais limite?

Para pedir aumento pela API — subindo o comprovante e acompanhando até a decisão — veja Como solicitar aumento de limite pela API.

Parâmetros

Path

accountId (obrigatório): Identificador (ObjectId) da conta bancária da empresa para a qual os limites serão retornados.

Exemplo de resposta

Após efetuar a requisição, se tudo ocorreu bem, o status code da requisição será 200 e o body da resposta retornará o objeto limits com os campos públicos:

{
  "limits": {
    "pixDayLimit": 4000000,
    "pixNightLimit": 100000,
    "pixOutSameHolderDayLimit": 4000000,
    "pixOutDifferentHolderDayLimit": 4000000,
    "pixOutSameHolderNightLimit": 100000,
    "pixOutDifferentHolderNightLimit": 100000,
    "pixInSameHolderDayLimit": 100000000,
    "pixInDifferentHolderDayLimit": 100000000,
    "pixInSameHolderNightLimit": 100000000,
    "pixInDifferentHolderNightLimit": 100000000,
    "dayStartAt": "06:00",
    "nightStartAt": "20:00",
    "boletoEmissionLimit": 200,
    "boletoMaximumValueLimit": 1000000,
    "stableInDayLimit": 500000,
    "stableOutDayLimit": 500000,
    "tedInLimit": 500000,
    "tedOutLimit": 500000
  },
  "usage": { "...": "..." }
}

info

Todos os valores monetários são expressos em centavos. Os horários dayStartAt/nightStartAt estão no formato HH:mm. Campos sem teto configurado não aparecem na resposta.

Campos da resposta

Campo	Tipo	Descrição
`pixDayLimit`	number	Limite total diário Pix (centavos)
`pixNightLimit`	number	Limite total noturno Pix (centavos)
`pixOutSameHolderDayLimit`	number	Limite diário Pix saída mesmo titular (centavos)
`pixOutDifferentHolderDayLimit`	number	Limite diário Pix saída titulares distintos (centavos)
`pixOutSameHolderNightLimit`	number	Limite noturno Pix saída mesmo titular (centavos)
`pixOutDifferentHolderNightLimit`	number	Limite noturno Pix saída titulares distintos (centavos)
`pixInSameHolderDayLimit`	number	Limite diário Pix entrada mesmo titular (centavos)
`pixInDifferentHolderDayLimit`	number	Limite diário Pix entrada titulares distintos (centavos)
`pixInSameHolderNightLimit`	number	Limite noturno Pix entrada mesmo titular (centavos)
`pixInDifferentHolderNightLimit`	number	Limite noturno Pix entrada titulares distintos (centavos)
`dayStartAt`	string	Início da janela diurna (`HH:mm`)
`nightStartAt`	string	Início da janela noturna (`HH:mm`)
`boletoEmissionLimit`	number	Máximo de boletos emitidos por dia
`boletoMaximumValueLimit`	number	Valor máximo por boleto emitido (centavos)
`stableIn` / `stableOut`	number	Limites de compra e venda de stablecoin, diurno/noturno e por transação (centavos)
`tedIn` / `tedOut`	number	Limites de TED recebida e enviada, total do dia e por transação (centavos)
`tedRefundReceived` / `tedRefundSent`	number	Limites de devolução de TED recebida e enviada (centavos)

Consumo em tempo real (`usage`)

Junto de limits, a resposta traz o bloco usage: quanto de cada limite já foi consumido na janela em vigor. É o que responde "ainda dá para mandar esse Pix agora?" sem precisar tentar e tomar a rejeição.

O bloco sai do mesmo documento de limites que alimenta limits, somado aos contadores ao vivo — não há chamada extra a fazer. O teto já vem resolvido para a janela em vigor (diurna ou noturna), então você nunca precisa escolher entre *DayLimit e *NightLimit na mão.

Compatível com quem já integra

O objeto limits não mudou. usage é um campo novo ao lado dele, então integrações existentes continuam funcionando sem alteração.

{
  "limits": { "...": "..." },
  "usage": {
    "window": "DAY",
    "asOf": "2026-01-15T14:00:00-03:00",
    "aggregate": {
      "pixOut": {
        "period": "DAY_WINDOW",
        "totalLimit": 4000000,
        "usedValue": 1250000,
        "availableValue": 2750000,
        "usedPercentage": 31.25,
        "resetsAt": "2026-01-15T20:00:00-03:00"
      },
      "pixOutMonthly": {
        "period": "MONTH",
        "totalLimit": null,
        "usedValue": 500000,
        "availableValue": null,
        "usedPercentage": null,
        "resetsAt": "2026-02-01T00:00:00-03:00"
      },
      "tedOut": {
        "period": "CALENDAR_DAY",
        "totalLimit": 500000,
        "usedValue": 0,
        "availableValue": 500000,
        "usedPercentage": 0,
        "resetsAt": "2026-01-16T00:00:00-03:00"
      },
      "...": "..."
    },
    "perTransaction": {
      "pixOutSameHolder": 4000000,
      "pixOutDifferentHolder": 4000000,
      "boletoMaximumValue": 1000000,
      "...": "..."
    }
  }
}

Campo	Tipo	Descrição
`window`	string	Janela em vigor para a conta agora: `DAY` ou `NIGHT`.
`asOf`	string	Instante em que o retrato foi tirado (ISO-8601, `America/Sao_Paulo`).
`aggregate`	object	Os 12 contadores que acumulam gasto na janela.
`perTransaction`	object	Os 15 tetos cobrados por transação, que não têm contador.

`usage.aggregate` — os contadores que acumulam

São 12: pixOut, pixOutMonthly, internalTransferOut, internalTransferIn, boletoOut, pixRefundSent, stableIn, stableOut, tedIn, tedOut, tedRefundReceived e tedRefundSent.

Pix de entrada não aparece aqui

Pix recebido não tem contador acumulado — só teto por transação. Os campos pixIn* aparecem em usage.perTransaction, nunca em usage.aggregate.

Cada contador tem o mesmo formato:

Campo	Tipo	Descrição
`period`	string	Tipo do balde: `DAY_WINDOW`, `CALENDAR_DAY` ou `MONTH` (veja abaixo).
`totalLimit`	number \| null	Teto em vigor agora, em centavos, já resolvido para a janela.
`usedValue`	number	Quanto já foi consumido no balde atual, em centavos. Sempre um número — `0` quando o contador ainda não foi tocado.
`availableValue`	number \| null	`max(totalLimit - usedValue, 0)`, em centavos.
`usedPercentage`	number \| null	`usedValue / totalLimit * 100`, arredondado em 2 casas.
`resetsAt`	string	Quando esse balde vira (ISO-8601, `America/Sao_Paulo`).

null e 0 querem dizer coisas diferentes

totalLimit: null — não há teto configurado, o fluxo é ilimitado. availableValue e usedPercentage também vêm null, e usedValue continua sendo reportado.
totalLimit: 0 — o fluxo está bloqueado. availableValue é 0 (um número, não null) e usedPercentage é null, porque não existe razão a expressar.

Não trate os dois como "sem limite": um libera tudo, o outro não deixa passar nada.

availableValue nunca é negativo — se o teto for reduzido no meio da janela e o consumo já estiver acima dele, o disponível é 0, não um número negativo. Já usedPercentage não é travado em 100: nesse mesmo caso ele passa de 100, de propósito, para a anomalia continuar visível.

`period` — quando o contador zera

`period`	Vira quando	Quem usa
`DAY_WINDOW`	Na troca entre as janelas diurna e noturna da conta (`dayStartAt` / `nightStartAt`)	Pix, transferência interna, boleto, devolução de Pix, stablecoin
`CALENDAR_DAY`	À meia-noite de Brasília, independente da janela	os quatro contadores de TED
`MONTH`	No dia 1º do mês seguinte	`pixOutMonthly`

resetsAt vem do relógio e das janelas configuradas na própria conta — não do TTL de nenhuma chave interna.

`usage.perTransaction` — os tetos por transação

São os 15 tetos cobrados sobre uma transação, em centavos, já resolvidos para a janela em vigor (null quando não há teto configurado): pixOutSameHolder, pixOutDifferentHolder, pixInSameHolder, pixInDifferentHolder, internalTransferOut, internalTransferIn, boletoOut, boletoMaximumValue, pixRefundSent, stableIn, stableOut, tedIn, tedOut, tedRefundReceived e tedRefundSent.

Eles não têm contador: passar do teto por transação reprova aquele pagamento, sem consumir nada.

Exemplo: dá para mandar esse Pix agora?

const { usage } = await response.json();

const amount = 150000; // centavos
const { availableValue } = usage.aggregate.pixOut;
const perTransaction = usage.perTransaction.pixOutDifferentHolder;

const fitsInTheDayTotal = availableValue === null || amount <= availableValue;
const fitsInOneTransaction = perTransaction === null || amount <= perTransaction;

if (fitsInTheDayTotal && fitsInOneTransaction) {
  // manda
} else {
  // espera o `usage.aggregate.pixOut.resetsAt` ou peça aumento de limite
}

Códigos de resposta

Status	Descrição
`200`	Limites retornados com sucesso
`400`	`accountId` não é um `ObjectId` válido
`401`	Credenciais ausentes, malformadas ou inválidas
`403`	Aplicação sem o scope `ACCOUNT_LIMITS_GET` ou empresa sem a feature `ACCOUNT_LIMITS_PUBLIC_API`
`404`	Conta não pertence à empresa autenticada, ou nenhum limite configurado para a conta

Exemplos de erro

{
  "error": "Account ID is invalid"
}

{
  "data": null,
  "errors": [{ "message": "Invalid appID" }]
}

{
  "error": "Application does not have required scope: ACCOUNT_LIMITS_GET"
}

{
  "error": "API not allowed"
}

{
  "error": "Account not found"
}

{
  "error": "No limits configured for this account"
}

Exemplos em código

Shell + cURL
JavaScript + Fetch

curl 'https://api.woovi.com/api/v1/limits/SEU_ACCOUNT_ID' -X GET \
    -H "Accept: application/json" \
    -u "SEU_CLIENT_ID:SEU_CLIENT_SECRET"

const clientId = 'SEU_CLIENT_ID';
const clientSecret = 'SEU_CLIENT_SECRET';
const accountId = 'SEU_ACCOUNT_ID';

const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');

const response = await fetch(`https://api.woovi.com/api/v1/limits/${accountId}`, {
  method: 'GET',
  headers: {
    'Authorization': `Basic ${credentials}`,
  },
});

const data = await response.json();

console.log(data.limits.pixDayLimit);
// 4000000

console.log(data.usage.aggregate.pixOut.availableValue);
// 2750000

Parâmetros​

Path​

Exemplo de resposta​

Campos da resposta​

Consumo em tempo real (usage)​

usage.aggregate — os contadores que acumulam​

period — quando o contador zera​

usage.perTransaction — os tetos por transação​

Exemplo: dá para mandar esse Pix agora?​

Códigos de resposta​

Exemplos de erro​

Exemplos em código​