# Claves PIX

Lista las claves PIX registradas en la cuenta asociada a la API Key.

## Endpoint

```
GET /api/external/pix/keys
```

## Headers

| Header | Tipo | Obligatorio | Descripcion |
|--------|------|-------------|-------------|
| `Authorization` | String | Si | `ApiKey {client_id}:{client_secret}` |
| `X-Key-Case` | String | No | Defina como `camelCase` para recibir los campos de la respuesta en camelCase (default es snake_case) |

## Ejemplo

```bash
curl -X GET https://api.monetarie.com/api/external/pix/keys \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"
```

## Respuesta de Exito (200)

```json
{
  "worked": true,
  "keys": [
    {
      "key": "12345678901",
      "key_type": "cpf",
      "status": "active",
      "created_at": "2026-02-05T12:00:00Z"
    },
    {
      "key": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "key_type": "evp",
      "status": "active",
      "created_at": "2026-02-10T14:30:00Z"
    },
    {
      "key": "contato@empresa.com.br",
      "key_type": "email",
      "status": "active",
      "created_at": "2026-02-15T09:00:00Z"
    }
  ]
}
```

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| `worked` | Boolean | `true` indica exito en la operacion |
| `keys` | Array | Lista de claves PIX de la cuenta, ordenada por `inserted_at ASC` (de la mas antigua a la mas reciente). **Nota:** cuando el cobro PIX IN (`POST /pix/cash-in`) es generado sin el parametro `pix_key`, el backend usa internamente la clave `active` mas **reciente** (`DESC`) de la cuenta -- orden diferente de este endpoint. |
| `keys[].key` | String | Valor de la clave PIX |
| `keys[].key_type` | String | Tipo de la clave en minusculas (vea tabla abajo) |
| `keys[].status` | String | Status actual de la clave (vea tabla abajo) |
| `keys[].created_at` | String | Fecha de registro (ISO 8601 en UTC) |

::: info Sin paginacion
Este endpoint **retorna todas las claves de la cuenta en una unica respuesta** (cuentas PF admiten hasta 5 claves, PJ hasta 20). No hay parametros de `limit`, `offset`, `page` o `per_page` -- envio de esos parametros es silenciosamente ignorado.
:::

## Tipos de Clave

| Tipo | Formato | Ejemplo |
|------|---------|---------|
| `cpf` | 11 digitos | `12345678901` |
| `cnpj` | 14 digitos | `12345678000190` |
| `email` | E-mail valido | `contato@empresa.com.br` |
| `phone` | DDD + numero (11 digitos) | `11999998888` |
| `evp` | UUID v4 (clave aleatoria) | `a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d` |

## Status de la Clave

El schema de la base acepta **solo dos valores** para `status`:

| Status | Descripcion |
|--------|-------------|
| `active` | Clave activa y operacional -- puede recibir PIX y ser usada como `pix_key` en `POST /pix/cash-in` |
| `pending` | Registro en procesamiento en el DICT (flujo de creacion de clave iniciado pero aun no confirmado por el BACEN) |

::: info Claves exhibidas
El endpoint retorna **todas** las claves vinculadas a la cuenta (independientemente del status). Filtre por el campo `status === "active"` en el cliente si solo quiere claves operacionales.
:::

::: info Portabilidad y reivindicaciones
**Portabilidad no es un status** de la clave. Portabilidad (traer clave de otra institucion) y reivindicacion (contestar posesion) son workflows separados, disponibles solo en el **portal del merchant** o via **panel administrativo** -- no expuestos por la API externa.
:::

## Respuesta de Error (401)

```json
{
  "error": {
    "status": 401,
    "message": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}
```

::: info API externa es solo-lectura
Este endpoint **solo lista** las claves existentes. Registro, portabilidad, reivindicacion y exclusion de claves PIX son hechos exclusivamente via **portal del merchant** (merchant.monetarie.com) o **panel administrativo** -- no hay endpoints externos para esas operaciones.

Informacion sobre limites (gestionados por el backend, no expuestos por la API): cuentas PF admiten hasta 5 claves, cuentas PJ hasta 20, con 1 clave CPF/CNPJ por cuenta.
:::