# Actualizar estado

> Actualiza el estado de una alerta recibida por webhook.

Página: https://doc.rapidchargeback.com/es/callback/atualizar-status/

Actualiza el estado de una alerta recibida por webhook.

## Endpoint

```
PATCH https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts/:id/status
```

## Autenticación

```
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json
```

---

## Parámetro de URL

| Parámetro | Tipo | Descripción |
|---|---|---|
| `id` | string (UUID) | `alert_id` recibido en el payload del webhook |

---

## Cuerpo de la solicitud

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `status` | string | Sí | Uno de tres valores: `notfound`, `account_suspended`, `other` |

---

## Validaciones

- `status` debe ser exactamente uno de los tres valores válidos; cualquier otro devuelve `422`
- La alerta debe pertenecer a tu empresa; si no, devuelve `404`
- Los estados definitivos (`notfound`, `account_suspended`) no se pueden cambiar una vez enviados; si lo intentas, devuelve error
- El estado `expired` lo genera el sistema automáticamente después de 24 h sin respuesta (Ethoca) y no lo envía el cliente
- La única transición permitida después de la respuesta inicial es `other → account_suspended`, disponible hasta 6 días (Ethoca)

Ver [Reglas y plazos](https://doc.rapidchargeback.com/es/produtos/alerta/regras-e-prazos/) para el detalle completo.

---

## Ejemplo de solicitud

Las credenciales vienen de variables de entorno (`RAPID_CLIENT_ID` y `RAPID_CLIENT_SECRET`), nunca escritas en el código.

**cURL**

```bash
curl -X PATCH https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts/00000000-0000-0000-0000-000000000099/status \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "account_suspended"
  }'
```

**Node.js**

```javascript
const credenciales = Buffer.from(`${process.env.RAPID_CLIENT_ID}:${process.env.RAPID_CLIENT_SECRET}`).toString('base64')
const alertId = '00000000-0000-0000-0000-000000000099'

const respuesta = await fetch(`https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts/${alertId}/status`, {
  method: 'PATCH',
  headers: { Authorization: `Basic ${credenciales}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ status: 'account_suspended' }),
})

const cuerpo = await respuesta.json()
if (!respuesta.ok) throw new Error(`${respuesta.status} ${cuerpo.error.code}: ${cuerpo.error.message}`)

console.log('Estado actualizado:', cuerpo.data.status)
```

**Python**

```python
import os

import requests

alert_id = "00000000-0000-0000-0000-000000000099"

respuesta = requests.patch(
    f"https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts/{alert_id}/status",
    auth=(os.environ["RAPID_CLIENT_ID"], os.environ["RAPID_CLIENT_SECRET"]),
    json={"status": "account_suspended"},
    timeout=30,
)

cuerpo = respuesta.json()
if not respuesta.ok:
    raise RuntimeError(f"{respuesta.status_code} {cuerpo['error']['code']}: {cuerpo['error']['message']}")

print("Estado actualizado:", cuerpo["data"]["status"])
```

**PHP**

```php
<?php
$alertId = '00000000-0000-0000-0000-000000000099';

$ch = curl_init("https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts/$alertId/status");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_USERPWD => getenv('RAPID_CLIENT_ID') . ':' . getenv('RAPID_CLIENT_SECRET'),
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['status' => 'account_suspended']),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);

$crudo = curl_exec($ch);
if ($crudo === false) {
    throw new RuntimeException('Error de red: ' . curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$cuerpo = json_decode($crudo, true);

if ($status >= 400) {
    throw new RuntimeException("$status {$cuerpo['error']['code']}: {$cuerpo['error']['message']}");
}

echo 'Estado actualizado: ', $cuerpo['data']['status'], PHP_EOL;
```

---

## Ejemplos de respuesta

### Éxito

```json
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000099",
    "status": "account_suspended",
    "updated_at": "2026-04-14T14:30:00.000Z"
  }
}
```

### Alerta no encontrada

```json
{
  "error": {
    "code": "ALERT_NOT_FOUND",
    "message": "Alert not found"
  }
}
```

### Empresa bloqueada

```json
{
  "error": {
    "code": "COMPANY_BLOCKED",
    "message": "Company is blocked"
  }
}
```

### Estado fuera de los valores válidos

Cuando el `status` enviado no es uno de los tres valores aceptados, la validación del cuerpo falla antes del procesamiento y devuelve `VALIDATION_ERROR` (HTTP 422):

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid enum value. Expected 'notfound' | 'account_suspended' | 'other', received 'foo'"
  }
}
```

### Transición no permitida

Cuando el `status` es válido pero la transición no está permitida (plazo, vencimiento o estado ya definitivo), el código es `ALERT_INVALID_STATUS` (HTTP 422). El mensaje indica cuál de los tres casos ocurrió:

```json
{
  "error": {
    "code": "ALERT_INVALID_STATUS",
    "message": "Alert has expired"
  }
}
```

```json
{
  "error": {
    "code": "ALERT_INVALID_STATUS",
    "message": "Response deadline has passed"
  }
}
```

```json
{
  "error": {
    "code": "ALERT_INVALID_STATUS",
    "message": "Alert already has a definitive status"
  }
}
```

Estos tres solo ocurren en alertas de Ethoca; Verifi RDR no tiene reglas de plazo (ver [Reglas y plazos](https://doc.rapidchargeback.com/es/produtos/alerta/regras-e-prazos/)).

---

## Clientes del sistema anterior

Si integrabas con la versión anterior de la plataforma, el endpoint antiguo sigue disponible como alias:

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

Este alias acepta el body en el formato antiguo `{ "alert_id": "...", "status": "..." }` y tanto Basic Auth como los headers `clientid`/`clientkey`. Como en el sistema anterior, **`alert_id` es el ID de la alerta en el proveedor** (el mismo `alert_id` que recibes en el formato `legacy` del webhook y usas en `POST /chargeback-alert/get`); el UUID de Rapid también se acepta. La respuesta mantiene el formato antiguo `{ "success": true, "message": "...", "status": "..." }` y agrega `data` con el objeto del endpoint canónico. Los errores siguen el envelope nuevo (`422 VALIDATION_ERROR` / `ALERT_INVALID_STATUS`, `404 ALERT_NOT_FOUND`).

**Recomendación:** migra a `PATCH /chargeback-alert/alerts/:id/status`. El alias se eliminará en el futuro, cuando ya no haya llamadas.