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

# Cuentas de una entidad

> Registrá y administrá cuentas financieras pertenecientes a una entidad persona o empresa.

## Descripción general

Las cuentas son recursos hijos de entidades persona y empresa. Permiten registrar varias cuentas por cliente, incluso en distintas monedas.

Cada cuenta tiene un `externalId` definido por el cliente, una `currency` ISO 4217 y al menos un identificador de pago. Los datos quedan aislados dentro de la organización actual.

## Endpoints

El mismo CRUD existe para tres búsquedas de entidad, igual que [actualizar por external ID](/es/api-reference/entities/update-by-external-id) y `PATCH /entities/by-tax-id/{taxId}`:

| Método           | Ruta                                                         | Búsqueda de entidad            |
| ---------------- | ------------------------------------------------------------ | ------------------------------ |
| `GET` `POST`     | `/entities/{id}/accounts`                                    | UUID de Gu1                    |
| `PATCH` `DELETE` | `/entities/{id}/accounts/{accountId}`                        | UUID de Gu1                    |
| `GET` `POST`     | `/entities/by-external-id/{externalId}/accounts`             | Tu `externalId` (match exacto) |
| `PATCH` `DELETE` | `/entities/by-external-id/{externalId}/accounts/{accountId}` | Tu `externalId`                |
| `GET` `POST`     | `/entities/by-tax-id/{taxId}/accounts`                       | Tax ID, denormalizado          |
| `PATCH` `DELETE` | `/entities/by-tax-id/{taxId}/accounts/{accountId}`           | Tax ID, denormalizado          |

`{accountId}` es siempre el UUID de Gu1 de la cuenta (el de create/list).

**Búsqueda por tax ID** ignora puntuación y mayúsculas (CUIT `20-12345678-9` matchea `20123456789`). Usa la misma clave alfanumérica que la unicidad de tax ID a nivel organización (`idx_entities_org_norm_tax_id`). Codificá el segmento de path si el valor tiene caracteres reservados.

La lectura requiere `entities:read`. Las mutaciones requieren `entities:edit`, con fallback legacy `entities:write`.

## Campos de la cuenta

| Campo           | Tipo    |   Requerido | Descripción                                                    |
| --------------- | ------- | ----------: | -------------------------------------------------------------- |
| `externalId`    | string  |          Sí | ID de cuenta en tu sistema; único dentro de la organización    |
| `currency`      | string  |          Sí | Código ISO 4217, como `USD`, `ARS` o `BRL`                     |
| `accountType`   | enum    |          No | Tipo canónico de cuenta; consultá los valores admitidos debajo |
| `status`        | string  |          No | `active`, `inactive`, `frozen` o `closed`; default `active`    |
| `countryCode`   | string  |          No | País ISO 3166-1 alpha-2                                        |
| `accountNumber` | string  | Condicional | Número de cuenta genérico                                      |
| `cbu`           | string  | Condicional | CBU de 22 dígitos                                              |
| `cvu`           | string  | Condicional | CVU de 22 dígitos                                              |
| `iban`          | string  | Condicional | IBAN de hasta 34 caracteres                                    |
| `alias`         | string  | Condicional | Alias de la cuenta                                             |
| `bankName`      | string  |          No | Banco o institución financiera                                 |
| `bankCode`      | string  |          No | Código de banco definido por el cliente                        |
| `isPrimary`     | boolean |          No | Cuenta principal de la entidad para esa moneda                 |
| `metadata`      | object  |          No | Datos adicionales propios del cliente                          |
| `openedAt`      | string  |          No | Fecha de apertura ISO 8601                                     |
| `closedAt`      | string  |          No | Fecha de cierre ISO 8601                                       |

### Tipos de cuenta admitidos

`accountType` acepta exclusivamente uno de estos valores:

* **Genéricos:** `bank_account`, `personal`, `business`, `other`
* **Depósitos bancarios:** `checking`, `savings`, `business_checking`, `business_savings`, `payroll`, `pension`, `money_market`, `fixed_deposit`
* **Inversión y custodia:** `investment`, `brokerage`, `custody`, `escrow`
* **Pagos y fondos digitales:** `payment`, `wallet`, `virtual_account`, `prepaid`, `merchant`
* **Crédito:** `credit`, `loan`
* **Operación institucional:** `correspondent`, `settlement`, `clearing`, `cash_management`

Usá `bank_account` cuando sabés que es una cuenta bancaria pero no conocés el producto, y `other` solo cuando ninguna categoría represente la cuenta. `checking` corresponde a cuenta corriente y `savings` a caja de ahorro. Un valor fuera del enum devuelve `400 VALIDATION_ERROR`.

Al crear una cuenta se requiere al menos uno de estos campos: `accountNumber`, `cbu`, `cvu`, `iban` o `alias`.

## Ejemplo de creación

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

Crear con tu `externalId` en vez del UUID de 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
  }'
```

Crear por tax ID (la puntuación es 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"
  }'
```

Al enviar `isPrimary: true`, la API quita la marca principal de las otras cuentas de la misma entidad y moneda.

## Errores

| HTTP  | Código             | Cuándo                                                                                           |
| ----- | ------------------ | ------------------------------------------------------------------------------------------------ |
| `400` | `VALIDATION_ERROR` | El input es inválido, `accountType` no pertenece al enum o no queda ningún identificador de pago |
| `404` | `NOT_FOUND`        | La entidad o cuenta no existe en la organización actual                                          |
| `409` | `CONFLICT`         | El `externalId` ya existe en la organización actual                                              |