> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Contas de uma entidade

> Cadastre e gerencie contas financeiras pertencentes a uma entidade pessoa ou empresa.

## Visão geral

As contas são recursos filhos de entidades pessoa e empresa. Elas permitem cadastrar várias contas por cliente, inclusive em moedas diferentes.

Cada conta possui um `externalId` definido pelo cliente, uma `currency` ISO 4217 e pelo menos um identificador de pagamento. Os dados ficam isolados na organização atual.

## Endpoints

O mesmo CRUD existe para três buscas de entidade, no mesmo padrão de [atualizar por external ID](/pt/api-reference/entities/update-by-external-id) e `PATCH /entities/by-tax-id/{taxId}`:

| Método           | Rota                                                         | Busca da entidade              |
| ---------------- | ------------------------------------------------------------ | ------------------------------ |
| `GET` `POST`     | `/entities/{id}/accounts`                                    | UUID da Gu1                    |
| `PATCH` `DELETE` | `/entities/{id}/accounts/{accountId}`                        | UUID da Gu1                    |
| `GET` `POST`     | `/entities/by-external-id/{externalId}/accounts`             | Seu `externalId` (match exato) |
| `PATCH` `DELETE` | `/entities/by-external-id/{externalId}/accounts/{accountId}` | Seu `externalId`               |
| `GET` `POST`     | `/entities/by-tax-id/{taxId}/accounts`                       | Tax ID, desnormalizado         |
| `PATCH` `DELETE` | `/entities/by-tax-id/{taxId}/accounts/{accountId}`           | Tax ID, desnormalizado         |

`{accountId}` é sempre o UUID Gu1 da conta (o de create/list).

**Busca por tax ID** ignora pontuação e maiúsculas (CUIT `20-12345678-9` casa com `20123456789`). Usa a mesma chave alfanumérica da unicidade de tax ID no nível da organização (`idx_entities_org_norm_tax_id`). Codifique o segmento de path se o valor tiver caracteres reservados.

A leitura requer `entities:read`. As alterações requerem `entities:edit`, com fallback legacy `entities:write`.

## Campos da conta

| Campo           | Tipo    | Obrigatório | Descrição                                                   |
| --------------- | ------- | ----------: | ----------------------------------------------------------- |
| `externalId`    | string  |         Sim | ID da conta no seu sistema; único na organização            |
| `currency`      | string  |         Sim | Código ISO 4217, como `USD`, `ARS` ou `BRL`                 |
| `accountType`   | enum    |         Não | Tipo canônico de conta; consulte os valores aceitos abaixo  |
| `status`        | string  |         Não | `active`, `inactive`, `frozen` ou `closed`; padrão `active` |
| `countryCode`   | string  |         Não | País ISO 3166-1 alpha-2                                     |
| `accountNumber` | string  | Condicional | Número genérico da conta                                    |
| `cbu`           | string  | Condicional | CBU com 22 dígitos                                          |
| `cvu`           | string  | Condicional | CVU com 22 dígitos                                          |
| `iban`          | string  | Condicional | IBAN com até 34 caracteres                                  |
| `alias`         | string  | Condicional | Alias da conta                                              |
| `bankName`      | string  |         Não | Banco ou instituição financeira                             |
| `bankCode`      | string  |         Não | Código do banco definido pelo cliente                       |
| `isPrimary`     | boolean |         Não | Conta principal da entidade para essa moeda                 |
| `metadata`      | object  |         Não | Dados adicionais específicos do cliente                     |
| `openedAt`      | string  |         Não | Data de abertura ISO 8601                                   |
| `closedAt`      | string  |         Não | Data de encerramento ISO 8601                               |

### Tipos de conta aceitos

`accountType` aceita exclusivamente um destes valores:

* **Genéricos:** `bank_account`, `personal`, `business`, `other`
* **Depósitos bancários:** `checking`, `savings`, `business_checking`, `business_savings`, `payroll`, `pension`, `money_market`, `fixed_deposit`
* **Investimento e custódia:** `investment`, `brokerage`, `custody`, `escrow`
* **Pagamentos e fundos digitais:** `payment`, `wallet`, `virtual_account`, `prepaid`, `merchant`
* **Crédito:** `credit`, `loan`
* **Operação institucional:** `correspondent`, `settlement`, `clearing`, `cash_management`

Use `bank_account` quando souber que é uma conta bancária, mas não conhecer o produto, e `other` somente quando nenhuma categoria representar a conta. `checking` corresponde a conta corrente e `savings` a conta poupança. Um valor fora do enum retorna `400 VALIDATION_ERROR`.

Ao criar uma conta, pelo menos um destes campos é obrigatório: `accountNumber`, `cbu`, `cvu`, `iban` ou `alias`.

## Exemplo de criação

```bash theme={null}
curl -X POST "https://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "account-usd-001",
    "currency": "USD",
    "accountType": "savings",
    "accountNumber": "ACC-001",
    "countryCode": "AR",
    "isPrimary": true
  }'
```

```json theme={null}
{
  "success": true,
  "account": {
    "id": "77c2ca62-4528-4d2e-a424-ff7c0ee7ab18",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "account-usd-001",
    "currency": "USD",
    "accountType": "savings",
    "status": "active",
    "accountNumber": "ACC-001",
    "isPrimary": true
  }
}
```

Criar com o seu `externalId` em vez do UUID da Gu1:

```bash theme={null}
curl -X POST "https://api.gu1.ai/entities/by-external-id/merchant-99/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "account-usd-001",
    "currency": "USD",
    "accountType": "savings",
    "accountNumber": "ACC-001",
    "isPrimary": true
  }'
```

Criar por tax ID (a pontuação é opcional):

```bash theme={null}
curl -X POST "https://api.gu1.ai/entities/by-tax-id/20-12345678-9/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "account-ars-001",
    "currency": "ARS",
    "cbu": "0000003100000000000001"
  }'
```

Ao enviar `isPrimary: true`, a API remove a marca principal das outras contas da mesma entidade e moeda.

## Erros

| HTTP  | Código             | Quando                                                                                             |
| ----- | ------------------ | -------------------------------------------------------------------------------------------------- |
| `400` | `VALIDATION_ERROR` | O input é inválido, `accountType` está fora do enum ou nenhum identificador de pagamento permanece |
| `404` | `NOT_FOUND`        | A entidade ou conta não existe na organização atual                                                |
| `409` | `CONFLICT`         | O `externalId` já existe na organização atual                                                      |