# Consultar Cash-Out por Tag

Consulta transações PIX que correspondem a uma tag (prefixo do `transaction_id`). Permite agrupar e buscar transações por data, tipo ou qualquer prefixo do identificador.

## Endpoint

```
GET /api/external/transactions/tag/:tag
```

## Headers

| Header | Tipo | Obrigatório | Descrição |
|--------|------|-------------|-----------|
| `Authorization` | String | Sim | `ApiKey {client_id}:{client_secret}` |
| `X-Key-Case` | String | Não | Envie `camelCase` para receber a resposta com chaves em camelCase (ex: `transactionId`, `endToEndId`, `payerIspb`). Sem esse header, a resposta mantém `snake_case` conforme o exemplo abaixo.veja [Autenticação](/auth-token) |

## Path Parameters

| Parâmetro | Tipo | Obrigatório | Descrição |
|-----------|------|-------------|-----------|
| `tag` | String | Sim | Prefixo do `transaction_id` para busca |

::: tip Exemplos de busca por tag
- `PIXOUT20260309` -- todas as transferências PIX de saída do dia 09/03/2026
- `PIXOUT` -- todas as transferências PIX de saída
- `PIXIN20260309` -- todos os recebimentos PIX do dia 09/03/2026
:::

## Exemplo

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

## Resposta de Sucesso -- 200

```json
{
  "worked": true,
  "data": [
    {
      "id": "c7f3a8b12d4e4f6a9c1b3e5f7a9b1d3e",
      "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
      "end_to_end_id": "E46026562202603091530abcdef01",
      "external_id": "order-9876",
      "type": "pix",
      "direction": "outbound",
      "status": "settled",
      "amount": 300000,
      "fee_amount": 350,
      "net_amount": 300350,
      "description": "Pagamento fornecedor",
      "counterparty_name": "Joao Silva",
      "recipient_key": "12345678901",
      "payer_document": "46026562000165",
      "recipient_document": "12345678901",
      "payer_ispb": "46026562",
      "payer_bank_name": "Monetarie",
      "created_at": "2026-03-09T15:30:00Z",
      "completed_at": "2026-03-09T15:30:02Z"
    },
    {
      "id": "d8e4b9c23f5a5b7c0d2e4f6a8b0c2e4f",
      "transaction_id": "PIXOUT20260309f6e5d4c3b2a1",
      "end_to_end_id": "E46026562202603091545abcdef02",
      "external_id": null,
      "type": "pix",
      "direction": "outbound",
      "status": "settled",
      "amount": 2500000,
      "fee_amount": 350,
      "net_amount": 2500350,
      "description": "Pagamento serviço",
      "counterparty_name": "Maria Santos",
      "recipient_key": "98765432100",
      "payer_document": "46026562000165",
      "recipient_document": "98765432100",
      "payer_ispb": "46026562",
      "payer_bank_name": "Monetarie",
      "created_at": "2026-03-09T15:45:00Z",
      "completed_at": "2026-03-09T15:45:01Z"
    }
  ]
}
```

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `data` | Array | Lista de transações que correspondem ao prefixo. Pode vir vazia (`[]`) quando nada casa - ainda assim HTTP 200 |

::: info Escopo da busca
A busca por tag consulta **apenas** a tabela `transactions` (transações liquidadas/rejeitadas). PIX OUT em andamento (`outbound_requests`, stage 1-2) e QR Codes não pagos (`qrcodes`) **não aparecem** nesta listagem. Use [GET /transactions/:id](/pix-cashout-status) ou o webhook `pix.payout.confirmed` para acompanhar transações em andamento.
:::

Cada objeto no array segue o mesmo shape da resposta "transação liquidada" em [GET /transactions/:id](/pix-cashout-status#resposta-transacao-liquidada-200). Valores monetários em **unidades base** (÷ 10.000 para reais). Campos `payer_document`, `recipient_document`, `payer_ispb` e `payer_bank_name` vêm do metadata da transação e podem ser `null` em rows antigas. Para transações rejeitadas, a resposta inclui `reason_code` e `reason_description` (em inglês).

::: warning Limite de resultados
A busca por tag retorna no máximo **50 transações** por requisição, ordenadas por `started_at` desc (mais recentes primeiro). Não há paginação - utilize prefixos mais específicos (ex: `PIXOUT20260309` para um dia inteiro, ou `PIXOUT2026030915` para um período horário) para refinar.
:::

## Resposta Vazia -- 200

Quando nenhuma transação corresponde ao prefixo informado:

```json
{
  "worked": true,
  "data": []
}
```