# Business Accounts

> **Aviso de descontinuação:** Este endpoint (`v1`) será descontinuado em **30/06/2026**. Parceiros devem migrar para o [`v2`](/banking/api/abertura-de-contas-v2/business-accounts-v2.md) antes dessa data.

## Ciclo de Vida

### Fluxo com KYC Aprovado

```mermaid
sequenceDiagram
    participant P as Parceiro
    participant B as Banking API

    P->>B: POST /v1/accounts/business
    B-->>P: 202 Accepted (status: PENDING)
    Note over B: KYC assíncrono
    B-->>P: Webhook account_status.update (KYC_APPROVED)
    P->>B: POST /v1/accounts/business/{id}/activate
    B-->>P: 200 OK (status: ACTIVE)
```

### Fluxo com KYC Rejeitado

```mermaid
sequenceDiagram
    participant P as Parceiro
    participant B as Banking API

    P->>B: POST /v1/accounts/business
    B-->>P: 202 Accepted (status: PENDING)
    Note over B: KYC assíncrono
    B-->>P: Webhook account_status.update (KYC_REPROVED)
    P->>B: PUT /v1/accounts/business/{id} (corrige dados)
    B-->>P: 200 OK (status: PENDING)
    Note over B: Novo KYC assíncrono
    B-->>P: Webhook account_status.update (KYC_APPROVED)
    P->>B: POST /v1/accounts/business/{id}/activate
    B-->>P: 200 OK (status: ACTIVE)
```

### Status

| Status         | Descrição                                |
| -------------- | ---------------------------------------- |
| `PENDING`      | KYC em processamento                     |
| `KYC_APPROVED` | KYC aprovado, aguardando ativação        |
| `KYC_REPROVED` | KYC rejeitado, necessário corrigir dados |
| `ACTIVE`       | Conta ativa e operacional                |
| `BLOCKED`      | Conta bloqueada temporariamente          |
| `CLOSED`       | Conta encerrada permanentemente          |

### Simulação de KYC em Testes

No ambiente de testes, o resultado do KYC é determinado pelo primeiro dígito do documento (CPF do account holder ou do primeiro shareholder):

| Primeiro dígito | Resultado do KYC                                   |
| --------------- | -------------------------------------------------- |
| `0` a `4`       | Aprovado automaticamente                           |
| `5` a `6`       | Reprovado automaticamente                          |
| `7`             | Entra em análise manual, seguido de aprovação      |
| `8`             | Entra em análise manual, seguido de reprovação     |
| `9`             | Entra em análise, seguido de qualquer status final |

> **Exemplo:** Um shareholder com CPF `42345678900` (primeiro dígito `4`) terá o KYC aprovado automaticamente. Já um CPF `81234567800` (primeiro dígito `8`) entrará em análise manual e será reprovado em seguida.

***

## POST /v1/accounts/business

Cria uma nova conta bancária PJ. O processo de KYC é iniciado automaticamente.

**Headers adicionais:**

| Header        | Obrigatório | Descrição             |
| ------------- | ----------- | --------------------- |
| `X-Seller-Id` | Sim         | ID do seller na Barte |

**Request:**

```bash
curl --request POST \
  --url 'https://api-banking.barte.com/v1/accounts/business' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --header 'X-Seller-Id: 12345' \
  --data '{
    "externalId": "partner-ref-001",
    "document": "12345678000199",
    "legalName": "Empresa Exemplo LTDA",
    "tradingName": "Exemplo Store",
    "email": "contato@exemplo.com.br",
    "phoneNumber": "5511999999999",
    "foundingDate": "2020-01-15",
    "businessType": "LTDA",
    "mainActivity": "4712100",
    "address": {
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Sala 101",
      "neighborhood": "Bela Vista",
      "postalCode": "01310100",
      "city": "São Paulo",
      "state": "SP"
    },
    "shareholders": [
      {
        "document": "12345678900",
        "firstName": "João",
        "lastName": "Silva",
        "birthDate": "1990-05-20",
        "email": "joao@exemplo.com.br",
        "phoneNumber": "5511988888888",
        "type": "PARTNER",
        "address": {
          "street": "Rua Augusta",
          "number": "500",
          "neighborhood": "Consolação",
          "postalCode": "01304000",
          "city": "São Paulo",
          "state": "SP"
        }
      }
    ]
  }'
```

### Campos — Business

| Campo          | Tipo   | Obrigatório | Validação                                                                                                                            |
| -------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `externalId`   | String | Não         | Máximo 36 caracteres                                                                                                                 |
| `document`     | String | Sim         | CNPJ: exatamente 14 dígitos numéricos. Ex: `12345678000199`                                                                          |
| `legalName`    | String | Sim         | Não pode estar vazio                                                                                                                 |
| `tradingName`  | String | Não         | -                                                                                                                                    |
| `email`        | String | Sim         | Email válido (RFC 5322). Ex: `contato@empresa.com.br`                                                                                |
| `phoneNumber`  | String | Sim         | Formato: `55` + DDD (2 dígitos) + número (8-9 dígitos). Total: 12-13 dígitos. Ex: `5511999999999` (celular) ou `551133334444` (fixo) |
| `foundingDate` | String | Sim         | Data ISO 8601: `YYYY-MM-DD`. Ex: `2020-01-15`                                                                                        |
| `businessType` | String | Sim         | Enum: `MEI`, `EI`, `EIRELI`, `LTDA`, `SS`, `SA`, `NON_PROFIT`                                                                        |
| `mainActivity` | String | Não         | CNAE: 7 dígitos. Ex: `4712100`                                                                                                       |
| `address`      | Object | Sim         | Objeto de endereço (ver tabela abaixo)                                                                                               |
| `shareholders` | Array  | Sim         | Lista de sócios. Mínimo: 1                                                                                                           |

### Campos — Address

| Campo          | Tipo   | Obrigatório | Validação                                                                       |
| -------------- | ------ | ----------- | ------------------------------------------------------------------------------- |
| `street`       | String | Sim         | Apenas letras e espaços (sem números). Ex: `Avenida Paulista`, `Rua das Flores` |
| `number`       | String | Sim         | Número do endereço. Pode conter letras. Ex: `1000`, `123A`                      |
| `complement`   | String | Não         | Complemento. Ex: `Sala 101`, `Bloco B`                                          |
| `neighborhood` | String | Sim         | Bairro. Não pode estar vazio                                                    |
| `postalCode`   | String | Sim         | CEP: exatamente 8 dígitos numéricos, sem hífen. Ex: `01310100`                  |
| `city`         | String | Sim         | Cidade. Não pode estar vazio                                                    |
| `state`        | String | Sim         | UF: 2 letras maiúsculas. Ex: `SP`, `RJ`, `MG`                                   |
| `country`      | String | Não         | Código do país (ISO 3166-1 alpha-3). Default: `BRA`                             |

### Campos — Shareholder

| Campo         | Tipo   | Obrigatório | Validação                                                                                               |
| ------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------- |
| `document`    | String | Sim         | CPF (11 dígitos) ou CNPJ (14 dígitos), apenas números. Ex: `12345678900` (CPF), `12345678000199` (CNPJ) |
| `firstName`   | String | Sim         | Primeiro nome (pessoa física). Não pode estar vazio                                                     |
| `lastName`    | String | Sim         | Sobrenome (pessoa física). Não pode estar vazio                                                         |
| `birthDate`   | String | Sim         | Data ISO 8601: `YYYY-MM-DD`. Ex: `1990-05-20`                                                           |
| `legalName`   | String | Não         | Nome completo ou razão social                                                                           |
| `email`       | String | Não         | Email válido (RFC 5322), se informado                                                                   |
| `phoneNumber` | String | Não         | Formato: `55` + DDD + número. Total: 12-13 dígitos, se informado. Ex: `5511988888888`                   |
| `type`        | String | Sim         | Enum: `PARTNER`, `PROXYHOLDER`, `LEGAL_REPRESENTATIVE`, `OTHER`                                         |
| `address`     | Object | Sim         | Objeto de endereço (mesma estrutura acima)                                                              |

### Tipos de Shareholder

| Tipo                   | Descrição           |
| ---------------------- | ------------------- |
| `PARTNER`              | Sócio               |
| `PROXYHOLDER`          | Procurador          |
| `LEGAL_REPRESENTATIVE` | Representante legal |
| `OTHER`                | Outro               |

**Response — 202 Accepted:**

```json
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "externalId": "partner-ref-001",
  "document": "12345678000199",
  "legalName": "Empresa Exemplo LTDA",
  "tradingName": "Exemplo Store",
  "email": "contato@exemplo.com.br",
  "phoneNumber": "5511999999999",
  "foundingDate": "2020-01-15",
  "businessType": "LTDA",
  "mainActivity": "4712100",
  "status": "PENDING",
  "kycDetails": null,
  "address": {
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Sala 101",
    "neighborhood": "Bela Vista",
    "postalCode": "01310100",
    "city": "São Paulo",
    "state": "SP",
    "country": "BRA"
  },
  "shareholders": [
    {
      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "document": "12345678900",
      "firstName": "João",
      "lastName": "Silva",
      "legalName": null,
      "birthDate": "1990-05-20",
      "email": "joao@exemplo.com.br",
      "phoneNumber": "5511988888888",
      "type": "PARTNER",
      "address": {
        "street": "Rua Augusta",
        "number": "500",
        "neighborhood": "Consolação",
        "postalCode": "01304000",
        "city": "São Paulo",
        "state": "SP",
        "country": "BRA"
      }
    }
  ],
  "createdAt": "2026-01-30T15:30:00Z",
  "updatedAt": "2026-01-30T15:30:00Z",
  "activatedAt": null
}
```

**Response — 400 Bad Request (validação):**

```json
{
  "errors": [
    {
      "code": "BNK-0501",
      "title": "Invalid request params",
      "description": "Error in request phoneNumber - Phone must be in format 5511999999999"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 409 Conflict (CNPJ duplicado):**

```json
{
  "errors": [
    {
      "code": "BNK-0048",
      "title": "Não foi possível processar a operação",
      "description": "Business account with document 12345678000199 already exists"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 409 Conflict (externalId duplicado):**

```json
{
  "errors": [
    {
      "code": "BNK-0046",
      "title": "Banking flow error",
      "description": "Business account with externalId partner-ref-001 already exists"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Status Codes:**

| Status             | Descrição                                       |
| ------------------ | ----------------------------------------------- |
| `202 Accepted`     | Conta criada, KYC em processamento              |
| `400 Bad Request`  | Dados inválidos ou campos obrigatórios ausentes |
| `401 Unauthorized` | Token inválido ou expirado                      |
| `403 Forbidden`    | Certificado mTLS inválido                       |
| `409 Conflict`     | CNPJ ou externalId já cadastrado                |

***

## GET /v1/accounts/business

Busca contas por filtros. Pelo menos um filtro é obrigatório.

**Query Parameters:**

| Parâmetro    | Tipo   | Obrigatório | Descrição                    |
| ------------ | ------ | ----------- | ---------------------------- |
| `externalId` | String | Não\*       | ID de referência do parceiro |
| `document`   | String | Não\*       | CNPJ da empresa (14 dígitos) |

> \*Pelo menos um dos filtros é obrigatório.

**Request:**

```bash
curl --request GET \
  --url 'https://api-banking.barte.com/v1/accounts/business?externalId=partner-ref-001' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}'
```

**Response — 200 OK:**

Retorna o objeto `BusinessAccountResponse` (mesmo formato do POST).

**Response — 400 Bad Request (filtro ausente):**

```json
{
  "errors": [
    {
      "code": "BNK-0049",
      "title": "Filter required",
      "description": "At least one filter (externalId or document) is required"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15: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-01-30T15:30:00Z"
  }
}
```

**Response — 404 Not Found:**

```json
{
  "errors": [
    {
      "code": "BNK-0040",
      "title": "Banking flow error",
      "description": "Business account with externalId partner-ref-001 not found"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Status Codes:**

| Status             | Descrição                  |
| ------------------ | -------------------------- |
| `200 OK`           | Sucesso                    |
| `400 Bad Request`  | Nenhum filtro informado    |
| `401 Unauthorized` | Token inválido ou expirado |
| `403 Forbidden`    | Sem acesso a conta         |
| `404 Not Found`    | Conta não encontrada       |

***

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

Consulta os dados de uma conta por ID.

**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' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}'
```

**Response — 200 OK:**

```json
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "externalId": "partner-ref-001",
  "document": "12345678000199",
  "legalName": "Empresa Exemplo LTDA",
  "tradingName": "Exemplo Store",
  "email": "contato@exemplo.com.br",
  "phoneNumber": "5511999999999",
  "foundingDate": "2020-01-15",
  "businessType": "LTDA",
  "mainActivity": "4712100",
  "status": "ACTIVE",
  "kycDetails": {
    "status": "KYC_APPROVED",
    "reviewedAt": "2026-01-30T16:00:00Z",
    "reasons": []
  },
  "address": {
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Sala 101",
    "neighborhood": "Bela Vista",
    "postalCode": "01310100",
    "city": "São Paulo",
    "state": "SP",
    "country": "BRA"
  },
  "shareholders": [
    {
      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "document": "12345678900",
      "firstName": "João",
      "lastName": "Silva",
      "legalName": null,
      "birthDate": "1990-05-20",
      "email": "joao@exemplo.com.br",
      "phoneNumber": "5511988888888",
      "type": "PARTNER",
      "address": {
        "street": "Rua Augusta",
        "number": "500",
        "neighborhood": "Consolação",
        "postalCode": "01304000",
        "city": "São Paulo",
        "state": "SP",
        "country": "BRA"
      }
    }
  ],
  "createdAt": "2026-01-30T15:30:00Z",
  "updatedAt": "2026-01-30T16:05:00Z",
  "activatedAt": "2026-01-30T16:05:00Z"
}
```

### Campos — kycDetails

| Campo        | Tipo   | Descrição                                   |
| ------------ | ------ | ------------------------------------------- |
| `status`     | String | `PENDING`, `KYC_APPROVED` ou `KYC_REPROVED` |
| `reviewedAt` | String | Data/hora da análise (ISO 8601)             |
| `reasons`    | Array  | Motivos da rejeição (se aplicável)          |

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

***

## PUT /v1/accounts/business/{businessId}

Atualiza os dados de uma conta. **Dispara novo ciclo de KYC**.

> Não permitido quando status é `PENDING`. Aguarde o resultado do KYC atual.

**Path Parameters:**

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

**Request:**

```bash
curl --request PUT \
  --url 'https://api-banking.barte.com/v1/accounts/business/f47ac10b-58cc-4372-a567-0e02b2c3d479' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "legalName": "Empresa Exemplo LTDA",
    "tradingName": "Exemplo Store Atualizada",
    "email": "novo-contato@exemplo.com.br",
    "phoneNumber": "5511977777777",
    "foundingDate": "2020-01-15",
    "businessType": "LTDA",
    "mainActivity": "4712100",
    "address": { ... },
    "shareholders": [ ... ]
  }'
```

> **Nota:** O `document` (CNPJ) é imutável. A conta é identificada pelo `businessId` na URL.

**Response — 200 OK:**

Retorna o objeto completo da conta com `status: "PENDING"`.

**Response — 409 Conflict (KYC em andamento):**

```json
{
  "errors": [
    {
      "code": "BNK-0052",
      "title": "Banking flow error",
      "description": "Cannot update business account f47ac10b-58cc-4372-a567-0e02b2c3d479 while KYC is in progress. Wait for KYC result."
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Status Codes:**

| Status             | Descrição                            |
| ------------------ | ------------------------------------ |
| `200 OK`           | Dados atualizados, novo KYC iniciado |
| `400 Bad Request`  | Dados inválidos                      |
| `401 Unauthorized` | Token inválido                       |
| `403 Forbidden`    | Conta não pertence ao parceiro       |
| `404 Not Found`    | Conta não encontrada                 |
| `409 Conflict`     | KYC em andamento, aguarde resultado  |

***

## POST /v1/accounts/business/{businessId}/activate

Ativa uma conta após aprovação do KYC.

**Pré-requisito:** Status deve ser `KYC_APPROVED`.

**Path Parameters:**

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

**Request:**

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

**Response — 200 OK:**

```json
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "externalId": "partner-ref-001",
  "document": "12345678000199",
  "legalName": "Empresa Exemplo LTDA",
  "tradingName": "Exemplo Store",
  "email": "contato@exemplo.com.br",
  "phoneNumber": "5511999999999",
  "foundingDate": "2020-01-15",
  "businessType": "LTDA",
  "mainActivity": "4712100",
  "status": "ACTIVE",
  "kycDetails": {
    "status": "KYC_APPROVED",
    "reviewedAt": "2026-01-30T16:00:00Z",
    "reasons": []
  },
  "address": { ... },
  "shareholders": [ ... ],
  "createdAt": "2026-01-30T15:30:00Z",
  "updatedAt": "2026-01-30T16:05:00Z",
  "activatedAt": "2026-01-30T16:05:00Z"
}
```

**Response — 409 Conflict (KYC não aprovado):**

```json
{
  "errors": [
    {
      "code": "BNK-0041",
      "title": "Banking flow error",
      "description": "Business account f47ac10b-58cc-4372-a567-0e02b2c3d479 has invalid status PENDING. Expected: KYC_APPROVED"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Response — 409 Conflict (conta já ativa):**

```json
{
  "errors": [
    {
      "code": "BNK-0053",
      "title": "Banking flow error",
      "description": "Business account f47ac10b-58cc-4372-a567-0e02b2c3d479 is already active"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Status Codes:**

| Status             | Descrição                          |
| ------------------ | ---------------------------------- |
| `200 OK`           | Conta ativada com sucesso          |
| `401 Unauthorized` | Token inválido                     |
| `403 Forbidden`    | Conta não pertence ao parceiro     |
| `404 Not Found`    | Conta não encontrada               |
| `409 Conflict`     | KYC não aprovado ou conta já ativa |

***

## GET /v1/accounts/business/{businessId}/balance

Consulta o saldo da conta business. Retorna o saldo da bag de débito.

**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/balance' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}'
```

**Response — 200 OK:**

```json
{
  "amount": 1500.00
}
```

### Campos — Response

| Campo    | Tipo       | Descrição                                        |
| -------- | ---------- | ------------------------------------------------ |
| `amount` | BigDecimal | Saldo da bag de débito (em reais). Ex: `1500.00` |

**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-01-30T15:30:00Z"
  }
}
```

**Response — 404 Not Found:**

```json
{
  "errors": [
    {
      "code": "BNK-0040",
      "title": "Banking flow error",
      "description": "Business account f47ac10b-58cc-4372-a567-0e02b2c3d479 not found"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Status Codes:**

| Status             | Descrição                                            |
| ------------------ | ---------------------------------------------------- |
| `200 OK`           | Saldo retornado com 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 |


---

# Agent Instructions: 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:

```
GET https://docs.barte.com/banking/api/business-accounts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.