> For the complete documentation index, see [llms.txt](https://docs.barte.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.barte.com/banking/api/account-limits.md).

# 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:**

```bash
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:**

```json
[
  {
    "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:**

```bash
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:**

```json
{
  "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):**

```json
{
  "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):

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

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

```json
{
  "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):**

```json
{
  "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                                           |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.barte.com/banking/api/account-limits.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.