# Consultar alertas

> Lista las alertas de contracargo de tu empresa, con filtros opcionales y paginación.

Página: https://doc.rapidchargeback.com/es/callback/consultar-alertas/

Lista las alertas de contracargo de tu empresa, con filtros opcionales y paginación.

## Endpoint

```
GET https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts
```

## Autenticación

```
Authorization: Basic base64(client_id:client_secret)
```

---

## Query params

Todos opcionales. Combina los que necesites.

| Param | Tipo | Default | Descripción |
|---|---|---|---|
| `page` | int (≥ 1) | `1` | Página de la paginación |
| `per_page` | int (1–100) | `20` | Elementos por página |
| `status` | enum | - | `pending`, `notfound`, `account_suspended`, `other`, `expired` |
| `provider_alert_id` | string | - | ID de la alerta en el sistema del proveedor (Ethoca/Verifi). Único dentro de cada proveedor; normalmente devuelve 0 o 1 elemento |
| `date_from` | YYYY-MM-DD | - | Filtra por `received_at >= date_from` (00:00:00 UTC) |
| `date_to` | YYYY-MM-DD | - | Filtra por `received_at <= date_to` (23:59:59 UTC) |
| `card_bin` | string (6-8 dígitos) | - | BIN de la tarjeta |
| `card_last4` | string (4 dígitos) | - | Últimos dígitos de la tarjeta |

---

## Buscar por tu propio ID (el del proveedor)

Las alertas tienen dos IDs:

- **`id`**: UUID que Rapid genera cuando recibe la alerta. Es lo que necesitas para actualizar el estado (`PATCH /chargeback-alert/alerts/:id/status`).
- **`provider_alert_id`**: ID que generó Ethoca o Verifi. Es lo que probablemente ya tienes guardado en tus sistemas, del payload original del proveedor.

Si solo tienes el `provider_alert_id` y necesitas encontrar nuestro `id` (o los datos de la alerta), usa este endpoint con el filtro:

```bash
curl -G "https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts" \
  --data-urlencode "provider_alert_id=ALERT-ETHOCA-12345" \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="
```

El `provider_alert_id` es único dentro de cada proveedor, así que la respuesta normalmente tendrá 1 elemento en `data`. Para una clave estable y globalmente única, usa el `id` (UUID) de la respuesta.

---

## Ejemplos

### Listar las últimas alertas pendientes

```bash
curl -G "https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts" \
  --data-urlencode "status=pending" \
  --data-urlencode "per_page=50" \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="
```

### Alertas de los últimos 7 días

```bash
curl -G "https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts" \
  --data-urlencode "date_from=2026-04-16" \
  --data-urlencode "date_to=2026-04-23" \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="
```

### Buscar por tarjeta (BIN + últimos dígitos)

```bash
curl -G "https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts" \
  --data-urlencode "card_bin=424242" \
  --data-urlencode "card_last4=4242" \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="
```

---

## Respuesta

### Éxito

```json
{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000099",
      "company_id": "00000000-0000-0000-0000-0000000000c1",
      "merchant_id": "00000000-0000-0000-0000-000000000001",
      "merchant_enrollment_id": "00000000-0000-0000-0000-0000000000aa",
      "provider": "ethoca_alerts",
      "provider_alert_id": "ALERT-ETHOCA-12345",
      "amount": "150.00",
      "currency": "USD",
      "card_last4": "4242",
      "card_bin": "424242",
      "transaction_date": "2026-04-01T00:00:00.000Z",
      "descriptor": "LOJA EXEMPLO",
      "arn": null,
      "caid": null,
      "auth_code": "AUTH999",
      "alert_type": "fraud",
      "reason_code": "10.4",
      "issuer": "BANK XYZ",
      "status": "pending",
      "received_at": "2026-04-23T10:15:00.000Z",
      "expires_at": "2026-04-24T10:15:00.000Z",
      "created_at": "2026-04-23T10:15:00.000Z",
      "updated_at": "2026-04-23T10:15:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 42,
    "total_pages": 3
  }
}
```

### Sin resultados

```json
{
  "data": [],
  "meta": { "page": 1, "per_page": 20, "total": 0, "total_pages": 0 }
}
```

### Validación inválida (ej.: `card_bin` no numérico)

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "card_bin must be 6-8 digits"
  }
}
```

---

## Clientes del sistema anterior

Quien ya integraba con el sistema anterior puede seguir consultando una alerta por el endpoint antiguo, mantenido como alias:

```
POST https://api.rapidchargeback.com/chargeback-alert/get
```

Ten en cuenta que este alias **no** tiene el prefijo `/api/v1`. Acepta Basic Auth o los headers `clientid`/`clientkey`.

### Cuerpo de la solicitud

Envía **uno** de los dos:

| Campo | Tipo | Descripción |
|---|---|---|
| `alert_id` | string | **ID de la alerta en el proveedor**, el mismo que recibes en el formato `legacy` del webhook. El UUID de Rapid también se acepta |
| `authorization_code` | string | Código de autorización de la transacción |

Si vienen los dos, `alert_id` tiene prioridad. Cuando más de una alerta coincide (por ejemplo, dos alertas con el mismo código de autorización), se devuelve la más reciente.

### Ejemplo

```bash
curl -X POST https://api.rapidchargeback.com/chargeback-alert/get \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{ "alert_id": "ETH-99887766" }'
```

### Respuesta

`200` con `success` y `data`, donde `data` es el **mismo cuerpo del webhook en formato `legacy`** (ver [Formato legacy](https://doc.rapidchargeback.com/es/canais/webhook/payload/#formato-legacy)):

```json
{
  "success": true,
  "data": {
    "alert_id": "ETH-99887766",
    "merchant": "Minha Loja",
    "provider": "ethoca",
    "descriptor": "LOJA EXEMPLO",
    "transaction_date": "2026-04-01T00:00:00.000Z",
    "currency": "USD",
    "amount": 150,
    "card_number": "424242******4242",
    "created_at": "2026-04-14T12:00:00.000Z"
  }
}
```

La respuesta viene con `Cache-Control: no-store`, como en el sistema anterior.

### Errores de este alias

Para mantener la paridad con el sistema anterior, los errores de este endpoint usan el envelope **antiguo** (`{"error": "texto"}`), y no el envelope nuevo con `code`:

| Situación | Respuesta |
|---|---|
| Ni `alert_id` ni `authorization_code` | `400` `{"error": "Informe alert_id ou authorization_code."}` |
| Ninguna alerta tuya coincide | `404` `{"error": "Alerta não encontrado."}` |

Los mensajes están en portugués, tal como los devolvía el sistema anterior. En integraciones nuevas, prefiere [`GET /api/v1/chargeback-alert/alerts/:id`](#endpoint), que usa el envelope de error estándar de la API.

---

## Notas

- **`provider`** viene como string slug (`"ethoca_alerts"` o `"verifi_rdr"`), igual que en el payload del webhook saliente (formato `v2`).
- Los campos de la respuesta son exactamente los del ejemplo de arriba, más `installment_number` e `installment_count` (cuotas, los mismos del webhook) y `provider_id`, un identificador interno mantenido por compatibilidad: usa `provider`.
- Las fechas de "solo fecha" (`transaction_date`) llegan como `"2026-04-01T00:00:00.000Z"`.
- **Orden:** siempre por `received_at` descendente (la más reciente primero). No hay parámetro de orden personalizado.
- **Auth, rate limit, códigos de error:** ver [Autenticación](https://doc.rapidchargeback.com/es/referencia/autenticacao/) y [Códigos de respuesta](https://doc.rapidchargeback.com/es/referencia/codigos-de-resposta/).