# Consultar Cash-Out por Tag

Consulta transacciones PIX que corresponden a una tag (prefijo del `transaction_id`). Permite agrupar y buscar transacciones por fecha, tipo o cualquier prefijo del identificador.

## Endpoint

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

## Headers

| Header | Tipo | Obligatorio | Descripcion |
|--------|------|-------------|-------------|
| `Authorization` | String | Si | `ApiKey {client_id}:{client_secret}` |
| `X-Key-Case` | String | No | Envie `camelCase` para recibir la respuesta con claves en camelCase (ej: `transactionId`, `endToEndId`, `payerIspb`). Sin ese header, la respuesta mantiene `snake_case` segun el ejemplo abajo.vea [Autenticacion](/es/auth-token) |

## Path Parameters

| Parametro | Tipo | Obligatorio | Descripcion |
|-----------|------|-------------|-------------|
| `tag` | String | Si | Prefijo del `transaction_id` para busqueda |

::: tip Ejemplos de busqueda por tag
- `PIXOUT20260309` -- todas las transferencias PIX de salida del dia 09/03/2026
- `PIXOUT` -- todas las transferencias PIX de salida
- `PIXIN20260309` -- todos los recibimientos PIX del dia 09/03/2026
:::

## Ejemplo

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

## Respuesta de Exito -- 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 servico",
      "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 | Descripcion |
|-------|------|-------------|
| `data` | Array | Lista de transacciones que corresponden al prefijo. Puede venir vacia (`[]`) cuando nada coincide - aun asi HTTP 200 |

::: info Alcance de la busqueda
La busqueda por tag consulta **solo** la tabla `transactions` (transacciones liquidadas/rechazadas). PIX OUT en curso (`outbound_requests`, stage 1-2) y QR Codes no pagados (`qrcodes`) **no aparecen** en este listado. Use [GET /transactions/:id](/es/pix-cashout-status) o el webhook `pix.payout.confirmed` para acompanar transacciones en curso.
:::

Cada objeto en el array sigue el mismo shape de la respuesta "transaccion liquidada" en [GET /transactions/:id](/es/pix-cashout-status#respuesta-transaccion-liquidada-200). Valores monetarios en **unidades base** (÷ 10.000 para reales). Campos `payer_document`, `recipient_document`, `payer_ispb` y `payer_bank_name` vienen del metadata de la transaccion y pueden ser `null` en rows antiguas. Para transacciones rechazadas, la respuesta incluye `reason_code` y `reason_description` (en ingles).

::: warning Limite de resultados
La busqueda por tag retorna como maximo **50 transacciones** por solicitud, ordenadas por `started_at` desc (mas recientes primero). No hay paginacion - utilice prefijos mas especificos (ej: `PIXOUT20260309` para un dia entero, o `PIXOUT2026030915` para un periodo horario) para refinar.
:::

## Respuesta Vacia -- 200

Cuando ninguna transaccion corresponde al prefijo informado:

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