Atualizar status

Atualiza o status de um alerta recebido via webhook.

Endpoint

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

Autenticação

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

Parâmetro de URL

Parâmetro	Tipo	Descrição
`id`	string (UUID)	`alert_id` recebido no payload do webhook

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`status`	string	Sim	Um dos três valores: `notfound`, `account_suspended`, `other`

Validações

status deve ser exatamente um dos três valores válidos, qualquer outro retorna 422
O alerta deve pertencer à sua empresa: caso contrário retorna 404
Status definitivos (notfound, account_suspended) não podem ser alterados depois de enviados, retorna erro se você tentar
O status expired é gerado automaticamente pelo sistema após 24h sem resposta (Ethoca) e não é enviado pelo cliente
A única transição permitida após resposta inicial é other → account_suspended, disponível por até 6 dias (Ethoca)

Ver Regras e prazos para o detalhamento completo.

Exemplo de requisição

As credenciais vêm de variáveis de ambiente (RAPID_CLIENT_ID e RAPID_CLIENT_SECRET), nunca escritas no 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 credenciais = Buffer.from(`${process.env.RAPID_CLIENT_ID}:${process.env.RAPID_CLIENT_SECRET}`).toString('base64')
const alertId = '00000000-0000-0000-0000-000000000099'

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

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

console.log('Status atualizado:', corpo.data.status)

import os

import requests

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

resposta = 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,
)

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

print("Status atualizado:", corpo["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,
]);

$bruto = curl_exec($ch);
if ($bruto === false) {
    throw new RuntimeException('Falha de rede: ' . curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$corpo = json_decode($bruto, true);

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

echo 'Status atualizado: ', $corpo['data']['status'], PHP_EOL;

Exemplos de resposta

Sucesso

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

Alerta não encontrado

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

Empresa bloqueada

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

Status fora dos valores válidos

Quando o status enviado não é um dos três valores aceitos, a validação do corpo falha antes do processamento e retorna VALIDATION_ERROR (HTTP 422):

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

Transição não permitida

Quando o status é válido mas a transição não é permitida (prazo, expiração ou status já definitivo), o código é ALERT_INVALID_STATUS (HTTP 422). A mensagem indica qual dos três cenários ocorreu:

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

Esses três ocorrem apenas em alertas Ethoca, Verifi RDR não tem regras de prazo (ver Regras e prazos).

Clientes do sistema anterior

Se você integrava com a versão anterior da plataforma, o endpoint antigo continua disponível como alias:

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

Esse alias aceita o body no formato antigo { "alert_id": "...", "status": "..." } e tanto Basic Auth quanto os headers clientid/clientkey. Como no sistema anterior, alert_id é o ID do alerta no provedor (o mesmo alert_id que você recebe no webhook em formato legacy e usa em POST /chargeback-alert/get); o UUID da Rapid também é aceito. A resposta mantém o formato antigo { "success": true, "message": "...", "status": "..." } e acrescenta data com o objeto do endpoint canônico. Erros seguem o envelope novo (422 VALIDATION_ERROR / ALERT_INVALID_STATUS, 404 ALERT_NOT_FOUND).

Recomendação: migre para PATCH /chargeback-alert/alerts/:id/status. O alias será removido no futuro quando não houver mais chamadas.