> 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/abertura-de-contas-v2/business-accounts-v2.md).

# Conta PJ

## Por que o V2?

A **Circular nº 3.978/2020 do Banco Central** passou a exigir verificação biométrica facial obrigatória no onboarding de contas PJ. Com isso, cada entidade vinculada à conta (sócio, representante legal) precisa realizar uma verificação de identidade com biometria facial (liveness + facematch + OCR de documento) além do KYC cadastral já existente.

O endpoint `v2` foi criado para incorporar esse fluxo sem impactar os parceiros que ainda utilizam o `v1`. Os dois endpoints coexistem durante o período de migração — parceiros migram de `v1` para `v2` individualmente.

> **Aviso de descontinuação:** O endpoint `v1` será descontinuado em **30/06/2026**. Parceiros devem migrar para o `v2` antes dessa data. Consulte também o aviso na documentação de [Business Accounts](/banking/api/business-accounts.md).

### O que muda em relação ao v1?

|                                | v1                      | v2                                   |
| ------------------------------ | ----------------------- | ------------------------------------ |
| **Biometria facial**           | Não                     | Sim — obrigatória para cada entidade |
| `tradingName`                  | Presente                | Removido                             |
| `foundingDate`                 | Presente                | Removido                             |
| `businessType`                 | Presente                | Removido                             |
| `mainActivity`                 | Presente                | Removido                             |
| `motherName` (sócios)          | Presente                | Removido                             |
| `annualRevenueRange`           | Ausente                 | Obrigatório                          |
| `monthlyRevenueRange` (sócios) | Ausente                 | Opcional                             |
| `occupation` (sócios)          | Ausente                 | Opcional                             |
| `address.country`              | Ausente                 | Opcional (default: `BRA`)            |
| `legalRelationships`           | Ausente                 | Opcional                             |
| **Resposta**                   | Sem sessões biométricas | Inclui `biometricSessions[]`         |

***

## Ciclo de Vida

O fluxo de abertura de conta no v2 envolve duas etapas independentes que precisam ser aprovadas para cada entidade:

* **KYC cadastral** — validação dos dados da empresa e dos indivíduos vinculados.
* **Biometria facial** — verificação de identidade com liveness, facematch e OCR de documento.

Ambas as etapas são processadas de forma assíncrona. O account holder só é aprovado quando KYC **e** biometria estiverem aprovados para **todas** as entidades da conta.

A biometria precisa ser refeita (via retry) somente nos casos de: reprovação, atualização de dados de uma entidade ou inclusão de novo sócio.

### Fluxo com KYC e Biometria Aprovados

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

    P->>B: POST /v2/accounts/business
    B-->>P: 202 Accepted (status: PENDING)
    P->>B: GET /v2/accounts/{id}/biometric-sessions
    B-->>P: 200 OK (biometricUrl por entidade)
    P->>E: Envia biometricUrl à entidade
    E->>B: Completa biometria via link
    loop Aguarda confirmação de KYC e biometria
        Note over B: Processamento assíncrono em andamento
    end
    B-->>P: Notificação de status ao parceiro (em desenvolvimento)
    P->>B: POST /v1/accounts/business/{id}/activate
    B-->>P: 200 OK (status: ACTIVE)
```

### Fluxo com KYC e Biometria Rejeitados (Retry)

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

    B-->>P: Notificação de KYC ou biometria rejeitados (em desenvolvimento)
    P->>B: POST /v2/accounts/{id}/biometric-sessions/retry
    B-->>P: 202 Accepted (novo biometricUrl)
    P->>E: Envia novo biometricUrl à entidade
    E->>B: Refaz biometria via link
    loop Aguarda nova confirmação
        Note over B: Novo processamento assíncrono em andamento
    end
    B-->>P: Notificação de status ao parceiro (em desenvolvimento)
    P->>B: POST /v1/accounts/business/{id}/activate
    B-->>P: 200 OK (status: ACTIVE)
```

### Fluxo com Token Expirado (Refresh)

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

    Note over P: Token expirado (TTL: 72h)
    P->>B: POST /v2/accounts/{id}/biometric-sessions/refresh
    B-->>P: 202 Accepted (novo biometricUrl)
    P->>E: Reenvia novo link à entidade
    E->>B: Completa biometria via link
    loop Aguarda confirmação
        Note over B: Processamento assíncrono em andamento
    end
    B-->>P: Notificação de KYC aprovado ou rejeitado (em desenvolvimento)
```

### Status da Conta

| Status         | Descrição                                        |
| -------------- | ------------------------------------------------ |
| `PENDING`      | KYC e biometria em processamento                 |
| `KYC_APPROVED` | KYC e biometria aprovados, aguardando ativação   |
| `KYC_REPROVED` | KYC ou biometria rejeitados, necessário retentar |
| `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 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 /v2/accounts/business

Cria uma nova conta bancária PJ com suporte a KYC e biometria facial. O processo de biometria é iniciado automaticamente — cada entidade recebe uma sessão com link de biometria facial.

**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/v2/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",
    "email": "contato@exemplo.com.br",
    "phoneNumber": "5511999999999",
    "annualRevenueRange": "from_50k_to_500k",
    "address": {
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Sala 101",
      "neighborhood": "Bela Vista",
      "postalCode": "01310100",
      "city": "São Paulo",
      "state": "SP"
    },
    "shareholders": [
      {
        "document": "12345678900",
        "type": "PARTNER",
        "firstName": "João",
        "lastName": "Silva",
        "birthDate": "1990-05-20",
        "email": "joao@exemplo.com.br",
        "phoneNumber": "5511988888888",
        "monthlyRevenueRange": "3_to_5_sm",
        "address": {
          "street": "Rua Augusta",
          "number": "500",
          "neighborhood": "Consolação",
          "postalCode": "01304000",
          "city": "São Paulo",
          "state": "SP"
        }
      }
    ],
    "legalRelationships": [
      {
        "relationshipType": "LEGAL_REPRESENTATIVE",
        "person": {
          "document": "98765432100",
          "fullName": "Maria Souza",
          "email": "maria@exemplo.com.br",
          "phoneNumber": "5511977777777",
          "monthlyRevenueRange": "5_to_7_sm",
          "occupation": "Advogado",
          "address": {
            "street": "Rua Consolação",
            "number": "200",
            "neighborhood": "Consolação",
            "postalCode": "01302000",
            "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                                                                              |
| `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` |
| `annualRevenueRange` | String | Sim         | Enum (ver tabela abaixo)                                                                          |
| `address`            | Object | Sim         | Objeto de endereço (ver tabela abaixo)                                                            |
| `shareholders`       | Array  | Sim         | Lista de sócios. Mínimo: 1                                                                        |
| `legalRelationships` | Array  | Não         | Lista de representantes legais                                                                    |

### Valores — annualRevenueRange

| Valor              | Descrição (em R$)         |
| ------------------ | ------------------------- |
| `up_to_50k`        | Até 50 mil                |
| `from_50k_to_500k` | De 50 mil a 500 mil       |
| `from_500k_to_5m`  | De 500 mil a 5 milhões    |
| `from_5m_to_50m`   | De 5 milhões a 50 milhões |
| `above_50m`        | Acima de 50 milhões       |

### Campos — Address

| Campo          | Tipo   | Obrigatório | Validação                                                      |
| -------------- | ------ | ----------- | -------------------------------------------------------------- |
| `street`       | String | Sim         | Apenas letras e espaços (sem números). Ex: `Avenida Paulista`  |
| `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            |
| `type`                | String | Sim         | Enum: `PARTNER`, `PROXYHOLDER`, `LEGAL_REPRESENTATIVE`, `OTHER`  |
| `firstName`           | String | Não         | Primeiro nome (pessoa física)                                    |
| `lastName`            | String | Não         | Sobrenome (pessoa física)                                        |
| `birthDate`           | String | Não         | Data ISO 8601: `YYYY-MM-DD`. Ex: `1990-05-20`                    |
| `legalName`           | String | Não         | Razão social (pessoa jurídica)                                   |
| `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 |
| `monthlyRevenueRange` | String | Não         | Enum (ver tabela abaixo)                                         |
| `annualRevenueRange`  | String | Não         | Enum: mesmos valores do campo business                           |
| `address`             | Object | Sim         | Objeto de endereço (mesma estrutura acima)                       |

### Valores — monthlyRevenueRange

| Valor         | Descrição                    |
| ------------- | ---------------------------- |
| `0_to_1_sm`   | Até 1 salário mínimo         |
| `1_to_2_sm`   | De 1 a 2 salários mínimos    |
| `2_to_3_sm`   | De 2 a 3 salários mínimos    |
| `3_to_5_sm`   | De 3 a 5 salários mínimos    |
| `5_to_7_sm`   | De 5 a 7 salários mínimos    |
| `7_to_10_sm`  | De 7 a 10 salários mínimos   |
| `10_to_15_sm` | De 10 a 15 salários mínimos  |
| `15_to_20_sm` | De 15 a 20 salários mínimos  |
| `over_20_sm`  | Acima de 20 salários mínimos |

### Campos — LegalRelationship

| Campo              | Tipo   | Obrigatório | Validação                                                                                                |
| ------------------ | ------ | ----------- | -------------------------------------------------------------------------------------------------------- |
| `relationshipType` | String | Sim         | Enum: `LEGAL_REPRESENTATIVE`, `ATTORNEY_IN_FACT`, `REPRESENTATIVE_FOREIGN`, `TUTOR`, `EMANCIPATED_MINOR` |
| `person`           | Object | Sim         | Dados da pessoa (ver tabela abaixo)                                                                      |

### Campos — LegalRelationship Person

| Campo                 | Tipo   | Obrigatório | Validação                                             |
| --------------------- | ------ | ----------- | ----------------------------------------------------- |
| `document`            | String | Sim         | CPF (11 dígitos) ou CNPJ (14 dígitos), apenas números |
| `fullName`            | String | Sim         | Nome completo ou razão social                         |
| `email`               | String | Sim         | Email válido (RFC 5322)                               |
| `phoneNumber`         | String | Sim         | Formato: `55` + DDD + número. Total: 12-13 dígitos    |
| `monthlyRevenueRange` | String | Sim         | Enum: mesmos valores do campo shareholder             |
| `occupation`          | String | Não         | Ocupação da pessoa (ver tabela abaixo)                |
| `address`             | Object | Sim         | Objeto de endereço (mesma estrutura acima)            |

> **Nota:** `monthlyRevenueRange` é obrigatório para `LegalRelationship Person` e opcional para `Shareholder`. Representantes legais têm contrato mais restrito por exigência regulatória de identificação de renda.

### Valores — occupation

| Valor                                 |
| ------------------------------------- |
| `Administrador de Redes`              |
| `Advogado`                            |
| `Agricultor`                          |
| `Analista Administrativo`             |
| `Analista de Dados`                   |
| `Analista de Marketing`               |
| `Analista de Sistemas / TI`           |
| `Analista Financeiro`                 |
| `Aprendiz`                            |
| `Aposentado`                          |
| `Arquiteto`                           |
| `Artista`                             |
| `Assistente Administrativo`           |
| `Atendente`                           |
| `Atleta Profissional`                 |
| `Auditor`                             |
| `Autônomo`                            |
| `Auxiliar Administrativo`             |
| `Auxiliar de Cozinha`                 |
| `Auxiliar de Logística`               |
| `Auxiliar de Serviços Gerais`         |
| `Bancário`                            |
| `Barbeiro`                            |
| `Bombeiro`                            |
| `Cabeleireiro`                        |
| `Camareiro(a)`                        |
| `Cientista de Dados`                  |
| `Coletor de Resíduos`                 |
| `Confeiteiro`                         |
| `Consultor`                           |
| `Consultor Financeiro`                |
| `Contador`                            |
| `Coordenador Pedagógico`              |
| `Corretor de Imóveis`                 |
| `Corretor de Seguros`                 |
| `Cozinheiro`                          |
| `Cuidador de Pessoas`                 |
| `Dentista`                            |
| `Desempregado`                        |
| `Designer Gráfico`                    |
| `Desenvolvedor de Software`           |
| `Digitador`                           |
| `Diretor de Área`                     |
| `Diretor Executivo (CEO / CFO / COO)` |
| `Do lar`                              |
| `Economista`                          |
| `Eletricista`                         |
| `Empreendedor / Empresário`           |
| `Empresário (genérico)`               |
| `Encanador`                           |
| `Enfermeiro`                          |
| `Engenheiro`                          |
| `Engenheiro de Software`              |
| `Escriturário`                        |
| `Estagiário`                          |
| `Esteticista`                         |
| `Estoquista`                          |
| `Estudante`                           |
| `Faxineiro / Limpeza`                 |
| `Farmacêutico`                        |
| `Fisioterapeuta`                      |
| `Garçom`                              |
| `Gerente Administrativo`              |
| `Gerente Comercial`                   |
| `Gerente de Loja`                     |
| `Gerente de Operações`                |
| `Gerente Financeiro`                  |
| `Gerente Geral`                       |
| `Influencer / Criador de Conteúdo`    |
| `Instrutor / Tutor`                   |
| `Investidor Profissional`             |
| `Jornalista`                          |
| `Manicure / Pedicure`                 |
| `Mecânico`                            |
| `Médico`                              |
| `Microempreendedor Individual (MEI)`  |
| `Motoboy / Entregador`                |
| `Motorista (carro / aplicativo)`      |
| `Motorista de Caminhão`               |
| `Músico`                              |
| `Nutricionista`                       |
| `Operador de Criptoativos`            |
| `Operador de Empilhadeira`            |
| `Operador de Máquinas`                |
| `Outro / Não informado`               |
| `Padeiro`                             |
| `Pecuarista`                          |
| `Pedreiro`                            |
| `Pensionista`                         |
| `Pescador`                            |
| `Policial`                            |
| `Porteiro / Vigia`                    |
| `Prestador de Serviços`               |
| `Produtor Cultural`                   |
| `Professor (Educação Básica)`         |
| `Professor do Ensino Médio`           |
| `Professor Universitário`             |
| `Psicólogo`                           |
| `Publicitário`                        |
| `Recepcionista`                       |
| `Recepcionista de Hotel`              |
| `Representante Autônomo`              |
| `Representante Comercial`             |
| `Secretário(a)`                       |
| `Servente de Obras`                   |
| `Servidor Público`                    |
| `Soldador`                            |
| `Suporte Técnico de TI`               |
| `Técnico em Edificações`              |
| `Técnico em Eletrônica`               |
| `Técnico em Enfermagem`               |
| `Técnico em Mecânica`                 |
| `Técnico em Segurança do Trabalho`    |
| `Trader / Day Trader`                 |
| `Trabalhador Doméstico`               |
| `Trabalhador Rural`                   |
| `Vendedor`                            |
| `Vigia / Segurança Privado`           |
| `Vigilante`                           |
| `Zelador`                             |

**Response — 202 Accepted:**

```json
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "externalId": "partner-ref-001",
  "document": "12345678000199",
  "legalName": "Empresa Exemplo LTDA",
  "email": "contato@exemplo.com.br",
  "phoneNumber": "5511999999999",
  "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",
      "type": "PARTNER",
      "firstName": "João",
      "lastName": "Silva",
      "legalName": null,
      "birthDate": "1990-05-20",
      "email": "joao@exemplo.com.br",
      "phoneNumber": "5511988888888",
      "motherName": null,
      "address": {
        "street": "Rua Augusta",
        "number": "500",
        "neighborhood": "Consolação",
        "postalCode": "01304000",
        "city": "São Paulo",
        "state": "SP",
        "country": "BRA"
      }
    }
  ],
  "legalRelationships": [
    {
      "id": "b2c3d4e5-6789-01bc-def0-234567890123",
      "relationshipType": "LEGAL_REPRESENTATIVE",
      "person": {
        "document": "98765432100",
        "fullName": "Maria Souza",
        "email": "maria@exemplo.com.br",
        "phoneNumber": "5511977777777",
        "monthlyRevenueRange": "5_to_7_sm",
        "occupation": "Advogado",
        "address": {
          "street": "Rua Consolação",
          "number": "200",
          "neighborhood": "Consolação",
          "postalCode": "01302002",
          "city": "São Paulo",
          "state": "SP",
          "country": "BRA"
        }
      }
    }
  ],
  "status": "PENDING",
  "kycDetails": null,
  "createdAt": "2026-01-30T15:30:00Z",
  "updatedAt": "2026-01-30T15:30:00Z",
  "activatedAt": null
}
```

### Campos — Response

| Campo         | Tipo         | Descrição                                                                  |
| ------------- | ------------ | -------------------------------------------------------------------------- |
| `id`          | UUID         | Identificador único da conta na Barte                                      |
| `status`      | String       | Status atual da conta (ver tabela Status da Conta)                         |
| `kycDetails`  | Object\|null | Detalhes do resultado do KYC. `null` enquanto o processo está em andamento |
| `activatedAt` | String\|null | Timestamp UTC de ativação da conta. `null` até a conta ser ativada         |
| `createdAt`   | String       | Timestamp UTC de criação da conta (ISO 8601)                               |
| `updatedAt`   | String       | Timestamp UTC da última atualização (ISO 8601)                             |

**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"
  }
}
```

**Status Codes:**

| Status             | Descrição                                       |
| ------------------ | ----------------------------------------------- |
| `202 Accepted`     | Conta criada, KYC e biometria iniciados         |
| `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                |

> Para consultar e gerenciar as sessões biométricas geradas, consulte [Sessões Biométricas](/banking/api/abertura-de-contas-v2/biometric-sessions.md).

***

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

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

> 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/v2/accounts/business/f47ac10b-58cc-4372-a567-0e02b2c3d479' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --header 'X-Seller-Id: 12345' \
  --data '{
    "legalName": "Empresa Exemplo LTDA",
    "email": "novo-contato@exemplo.com.br",
    "phoneNumber": "5511977777777",
    "annualRevenueRange": "from_500k_to_5m",
    "address": {
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Sala 101",
      "neighborhood": "Bela Vista",
      "postalCode": "01310100",
      "city": "São Paulo",
      "state": "SP",
      "country": "BRA"
    },
    "shareholders": [
      {
        "document": "12345678900",
        "type": "PARTNER",
        "firstName": "João",
        "lastName": "Silva",
        "birthDate": "1990-05-20",
        "email": "joao@exemplo.com.br",
        "phoneNumber": "5511988888888",
        "monthlyRevenueRange": "3_to_5_sm",
        "address": {
          "street": "Rua Augusta",
          "number": "500",
          "neighborhood": "Consolação",
          "postalCode": "01304000",
          "city": "São Paulo",
          "state": "SP",
          "country": "BRA"
        }
      }
    ],
    "legalRelationships": [
      {
        "relationshipType": "LEGAL_REPRESENTATIVE",
        "person": {
          "document": "98765432100",
          "fullName": "Maria Souza",
          "email": "maria@exemplo.com.br",
          "phoneNumber": "5511977777777",
          "monthlyRevenueRange": "5_to_7_sm",
          "occupation": "Advogado",
          "address": {
            "street": "Rua Consolação",
            "number": "200",
            "neighborhood": "Consolação",
            "postalCode": "01302000",
            "city": "São Paulo",
            "state": "SP",
            "country": "BRA"
          }
        }
      }
    ]
  }'
```

> **Nota:** O `document` (CNPJ) é imutável e não deve ser enviado no body. O contrato de campos segue o mesmo do POST.

**Response — 200 OK:**

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

**Status Codes:**

| Status             | Descrição                                         |
| ------------------ | ------------------------------------------------- |
| `200 OK`           | Dados atualizados, novo KYC e biometria iniciados |
| `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               |

> Para consultar e gerenciar as sessões biométricas geradas após a atualização, consulte [Sessões Biométricas](/banking/api/abertura-de-contas-v2/biometric-sessions.md).

***

## Webhooks

O banking service envia notificações de status de conta via webhook. Esta funcionalidade está em desenvolvimento.

***

## Códigos de Erro

| Código     | Endpoint                   | Descrição                                                        |
| ---------- | -------------------------- | ---------------------------------------------------------------- |
| `BNK-0048` | POST /v2/accounts/business | CNPJ ou `externalId` já cadastrado                               |
| `BNK-0501` | POST /v2/accounts/business | Parâmetros de request inválidos (ex: formato de campo incorreto) |


---

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

```
GET https://docs.barte.com/banking/api/abertura-de-contas-v2/business-accounts-v2.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.