# Consultar alertas

> Lista os alertas de chargeback da sua empresa, com filtros opcionais e paginação.

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

Lista os alertas de chargeback da sua empresa, com filtros opcionais e paginação.

## Endpoint

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

## Autenticação

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

---

## Query params

Todos opcionais. Combine os que precisar.

| Param | Tipo | Default | Descrição |
|---|---|---|---|
| `page` | int (≥ 1) | `1` | Página da paginação |
| `per_page` | int (1–100) | `20` | Itens por página |
| `status` | enum | - | `pending`, `notfound`, `account_suspended`, `other`, `expired` |
| `provider_alert_id` | string | - | ID do alerta no sistema do provedor (Ethoca/Verifi). Único dentro de cada provedor; normalmente devolve 0 ou 1 item |
| `date_from` | YYYY-MM-DD | - | Filtra por `received_at >= date_from` (00:00:00) |
| `date_to` | YYYY-MM-DD | - | Filtra por `received_at <= date_to` (23:59:59) |
| `card_bin` | string (6-8 dígitos) | - | BIN do cartão |
| `card_last4` | string (4 dígitos) | - | Final do cartão |

---

## Buscar pelo seu próprio ID (do provedor)

Os alertas têm dois IDs:

- **`id`**: UUID que a Rapid gera quando recebe o alerta. É o que você precisa para atualizar status (`PATCH /chargeback-alert/alerts/:id/status`).
- **`provider_alert_id`**: ID que o Ethoca ou Verifi gerou. É o que você provavelmente já tem armazenado nos seus sistemas, vindo do payload original do provedor.

Se você só tem o `provider_alert_id` e precisa achar o nosso `id` (ou os dados do alerta), use este endpoint com o filter:

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

O `provider_alert_id` é único dentro de cada provedor, então a resposta normalmente terá 1 item em `data`. Para uma chave estável e globalmente única, use o `id` (UUID) que vem na resposta.

---

## Exemplos

### Listar últimos alertas pendentes

```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 dos últimos 7 dias

```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 cartão (BIN + final)

```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="
```

---

## Resposta

### Sucesso

```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
  }
}
```

### Sem resultados

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

### Validação inválida (ex: `card_bin` não-numérico)

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

---

## Clientes do sistema anterior

Quem já integrava com o sistema anterior continua podendo consultar um alerta pelo endpoint antigo, mantido como alias:

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

Note que este alias **não** tem o prefixo `/api/v1`. Ele aceita Basic Auth ou os headers `clientid`/`clientkey`.

### Corpo da requisição

Informe **um** dos dois:

| Campo | Tipo | Descrição |
|---|---|---|
| `alert_id` | string | **ID do alerta no provedor**, o mesmo que você recebe no webhook em formato `legacy`. O UUID da Rapid também é aceito |
| `authorization_code` | string | Código de autorização da transação |

Se os dois vierem, `alert_id` tem prioridade. Quando mais de um alerta casa (por exemplo, dois alertas com o mesmo código de autorização), volta o mais recente.

### Exemplo

```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" }'
```

### Resposta

`200` com `success` e `data`, onde `data` é o **mesmo corpo do webhook em formato `legacy`** (ver [Formato legacy](https://doc.rapidchargeback.com/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"
  }
}
```

A resposta vem com `Cache-Control: no-store`, como no sistema anterior.

### Erros deste alias

Para manter a paridade com o sistema anterior, os erros deste endpoint usam o envelope **antigo** (`{"error": "texto"}`), e não o envelope novo com `code`:

| Situação | Resposta |
|---|---|
| Nem `alert_id` nem `authorization_code` | `400` `{"error": "Informe alert_id ou authorization_code."}` |
| Nenhum alerta seu corresponde | `404` `{"error": "Alerta não encontrado."}` |

Em integrações novas, prefira [`GET /api/v1/chargeback-alert/alerts/:id`](#endpoint), que usa o envelope de erro padrão da API.

---

## Notas

- **`provider`** vem como string slug (`"ethoca_alerts"` ou `"verifi_rdr"`), igual ao payload do webhook outbound (formato `v2`).
- Os campos da resposta são exatamente os do exemplo acima, mais `installment_number` e `installment_count` (parcelamento, os mesmos do webhook) e `provider_id`, um identificador interno mantido por compatibilidade: use `provider`.
- Datas do tipo "só data" (`transaction_date`) chegam como `"2026-04-01T00:00:00.000Z"`.
- **Ordenação:** sempre por `received_at` decrescente (mais recente primeiro). Não há parâmetro de ordenação custom.
- **Auth, rate limit, códigos de erro:** ver [Autenticação](https://doc.rapidchargeback.com/referencia/autenticacao/) e [Códigos de resposta](https://doc.rapidchargeback.com/referencia/codigos-de-resposta/).