Actualizar estado

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

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)

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
$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

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

Alerta no encontrada

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

Empresa bloqueada

{
  "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):

{
  "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ó:

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

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

{
  "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).

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.