Limites da Conta

Endpoints para consultar e alterar os limites diários de transação de uma conta business (PIX e boleto).

Conceitos

Período (period)

Período	Descrição
DAY	Limite do período diurno
NIGHT	Limite do período noturno

Titularidade (isSameOwnership)

Valor	Descrição
true	Mesma titularidade — transferências entre contas do mesmo titular (mesmo CPF/CNPJ)
false	Outras titularidades — transferências para terceiros

O limite de outras titularidades (false) não pode ultrapassar o de mesma titularidade (true) para o mesmo período. Caso ultrapasse, a alteração é rejeitada (400, BNK-0038).

Valores e moeda

• O campo amount é sempre em reais (BigDecimal). Ex.: 500000 = R$ 500.000,00. Não enviar em centavos.
• Há um teto de segurança para o valor; valores acima dele retornam 400.

Efetivação

• Aumento de limite: a alteração é agendada e passa a valer em até 24 horas. Durante esse período, o limite vigente permanece em amount e o novo valor aparece em scheduledAmount.
• Redução de limite: aplicada imediatamente — o novo valor já vale em amount, sem espera de 24h.
• Uma nova alteração para o mesmo period + isSameOwnership sobrescreve o agendamento anterior (quando houver) e reinicia o SLA.

---

GET /v1/accounts/business/{businessId}/limits

Consulta os limites da conta (vigente + agendado), por período e titularidade.

Pré-requisito: Conta deve estar com status ACTIVE.

Path Parameters:

Parâmetro	Tipo	Descrição
businessId	UUID	ID da conta (UUID v4)

Request:

curl --request GET \
  --url 'https://api-banking.barte.com/v1/accounts/business/f47ac10b-58cc-4372-a567-0e02b2c3d479/limits' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}'

Response — 200 OK:

[
  {
    "period": "DAY",
    "isSameOwnership": true,
    "amount": 5000.00,
    "scheduledAmount": 500000.00
  },
  {
    "period": "DAY",
    "isSameOwnership": false,
    "amount": 5000.00,
    "scheduledAmount": 500000.00
  },
  {
    "period": "NIGHT",
    "isSameOwnership": true,
    "amount": 1000.00,
    "scheduledAmount": null
  },
  {
    "period": "NIGHT",
    "isSameOwnership": false,
    "amount": 1000.00,
    "scheduledAmount": null
  }
]

Campos — Response

Campo	Tipo	Descrição
period	String	DAY ou NIGHT
isSameOwnership	Boolean	true (mesma titularidade) ou false (outras titularidades)
amount	BigDecimal	Limite vigente, em reais. Ex.: 5000.00
scheduledAmount	BigDecimal	Aumento agendado aguardando os 24h, em reais. null quando não há agendamento (inclusive em reduções, que valem na hora)

Status Codes:

Status	Descrição
200 OK	Sucesso
401 Unauthorized	Token inválido ou expirado
403 Forbidden	Conta não pertence ao parceiro
404 Not Found	Conta não encontrada ou sem conta bancária associada

---

PATCH /v1/accounts/business/{businessId}/limits

Altera o limite diário da conta para um período e titularidade. Atualização parcial: cada chamada altera apenas a fatia informada (period + isSameOwnership) — não é necessário enviar todos os limites. Aumentos são agendados (efetivam em até 24h); reduções valem imediatamente. Idempotente na prática (reenviar o mesmo valor produz o mesmo resultado).

Pré-requisito: Conta deve estar com status ACTIVE.

Path Parameters:

Parâmetro	Tipo	Descrição
businessId	UUID	ID da conta (UUID v4)

Request:

curl --request PATCH \
  --url 'https://api-banking.barte.com/v1/accounts/business/f47ac10b-58cc-4372-a567-0e02b2c3d479/limits' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "period": "DAY",
    "amount": 500000,
    "isSameOwnership": false
  }'

Campos — Request

Campo	Tipo	Obrigatório	Validação
period	String	Sim	Enum: DAY, NIGHT
amount	BigDecimal	Sim	Valor em reais (não centavos). Maior que zero e até o teto permitido. Ex.: 500000 = R$ 500.000,00
isSameOwnership	Boolean	Sim	true = mesma titularidade; false = outras titularidades

Response — 200 OK:

{
  "period": "DAY",
  "isSameOwnership": false,
  "amount": 5000.00,
  "scheduledAmount": 500000.00
}

Em aumentos, o novo valor aparece em scheduledAmount e passa a vigorar (amount) em até 24h (exemplo acima). Em reduções, o valor já vale imediatamente em amount e scheduledAmount fica null.

Response — 400 Bad Request (valor inválido / acima do teto):

{
  "errors": [
    {
      "code": "BNK-0501",
      "title": "Invalid request params",
      "description": "Error in request amount - value exceeds the maximum allowed limit"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-06-24T15:30:00Z"
  }
}

Exemplo que dispara o erro — alterar outras titularidades (false) para um valor acima do limite vigente de mesma titularidade (no exemplo, mesma titularidade em R$ 500.000 e outras tentando R$ 600.000):

{
  "period": "DAY",
  "amount": 600000,
  "isSameOwnership": false
}

Response — 400 Bad Request (outras titularidades acima da mesma titularidade):

{
  "errors": [
    {
      "code": "BNK-0038",
      "title": "Banking flow error",
      "description": "New limit amount conflicts with scheduled intra transfers (period=DAY, amount=600000)"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-06-24T15:30:00Z"
  }
}

Response — 403 Forbidden (sem acesso a conta):

{
  "errors": [
    {
      "code": "BNK-0044",
      "title": "Banking flow error",
      "description": "Access denied to business account f47ac10b-58cc-4372-a567-0e02b2c3d479"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-06-24T15:30:00Z"
  }
}

Status Codes:

Status	Descrição
200 OK	Alteração aceita (aumento efetiva em até 24h; redução imediata)
400 Bad Request	Valor inválido/acima do teto, ou limite de outras titularidades acima do de mesma titularidade
401 Unauthorized	Token inválido ou expirado
403 Forbidden	Conta não pertence ao parceiro
404 Not Found	Conta não encontrada ou sem conta bancária associada