# Chaves PIX

Lista as chaves PIX registradas na conta associada à API Key.

## Endpoint

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

## Headers

| Header | Tipo | Obrigatório | Descrição |
|--------|------|-------------|-----------|
| `Authorization` | String | Sim | `ApiKey {client_id}:{client_secret}` |
| `X-Key-Case` | String | Não | Defina como `camelCase` para receber os campos da resposta em camelCase (padrão é snake_case) |

## Exemplo

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

## Resposta de Sucesso (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 | Descrição |
|-------|------|-----------|
| `worked` | Boolean | `true` indica sucesso na operação |
| `keys` | Array | Lista de chaves PIX da conta, ordenada por `inserted_at ASC` (da mais antiga para a mais recente). **Nota:** quando a cobrança PIX IN (`POST /pix/cash-in`) é gerada sem o parâmetro `pix_key`, o backend usa internamente a chave `active` mais **recente** (`DESC`) da conta -- ordem diferente deste endpoint. |
| `keys[].key` | String | Valor da chave PIX |
| `keys[].key_type` | String | Tipo da chave em minúsculas (veja tabela abaixo) |
| `keys[].status` | String | Status atual da chave (veja tabela abaixo) |
| `keys[].created_at` | String | Data de registro (ISO 8601 em UTC) |

::: info Sem paginação
Este endpoint **retorna todas as chaves da conta em uma única resposta** (contas PF admitem até 5 chaves, PJ até 20). Não há parâmetros de `limit`, `offset`, `page` ou `per_page` -- envio desses parâmetros é silenciosamente ignorado.
:::

## Tipos de Chave

| Tipo | Formato | Exemplo |
|------|---------|---------|
| `cpf` | 11 dígitos | `12345678901` |
| `cnpj` | 14 dígitos | `12345678000190` |
| `email` | E-mail válido | `contato@empresa.com.br` |
| `phone` | DDD + número (11 dígitos) | `11999998888` |
| `evp` | UUID v4 (chave aleatória) | `a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d` |

## Status da Chave

O schema da base aceita **apenas dois valores** para `status`:

| Status | Descrição |
|--------|-----------|
| `active` | Chave ativa e operacional -- pode receber PIX e ser usada como `pix_key` em `POST /pix/cash-in` |
| `pending` | Registro em processamento no DICT (fluxo de criação de chave iniciado mas ainda não confirmado pelo BACEN) |

::: info Chaves exibidas
O endpoint retorna **todas** as chaves vinculadas à conta (independente do status). Filtre pelo campo `status === "active"` no cliente se só quiser chaves operacionais.
:::

::: info Portabilidade e reivindicações
**Portabilidade não é um status** da chave. Portabilidade (trazer chave de outra instituição) e reivindicação (contestar posse) são workflows separados, disponíveis apenas no **portal do merchant** ou via **painel administrativo** -- não expostos pela API externa.
:::

## Resposta de Erro (401)

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

::: info API externa é somente-leitura
Este endpoint **apenas lista** as chaves existentes. Registro, portabilidade, reivindicação e exclusão de chaves PIX são feitos exclusivamente via **portal do merchant** (merchant.monetarie.com) ou **painel administrativo** -- não há endpoints externos para essas operações.

Informação sobre limites (gerenciados pelo backend, não expostos pela API): contas PF admitem até 5 chaves, contas PJ até 20, com 1 chave CPF/CNPJ por conta.
:::