# Primera integración

> De cero a la primera alerta respondida: credenciales, webhook con firma validada, primera transacción y el callback de estado, con los comandos listos.

Página: https://doc.rapidchargeback.com/es/primeira-integracao/

El camino más corto hasta la integración funcionando. Al final de esta guía tu aplicación recibe alertas con la firma validada, envía transacciones y responde alertas por la API. Cada paso apunta a la página con el detalle completo.

> **¿Usas un asistente de IA?** Conecta el [MCP de la documentación](https://doc.rapidchargeback.com/es/referencia/ferramentas-para-devs/#mcp) antes de empezar: el asistente pasa a consultar estas páginas en lugar de deducir campos y códigos.

## 1. Obtén las credenciales

En el panel de Rapid, en **Configuración › API**, genera el `client_id` y el `client_secret`. El secreto aparece **una sola vez**: cópialo en el momento. Si lo pierdes, genéralo de nuevo en el mismo lugar (las credenciales anteriores dejan de valer en ese mismo instante).

Guarda las dos en variables de entorno, nunca en el código:

```bash
export RAPID_CLIENT_ID="tu_client_id"
export RAPID_CLIENT_SECRET="tu_client_secret"
```

Detalles en [Autenticación](https://doc.rapidchargeback.com/es/referencia/autenticacao/).

## 2. Confirma que la credencial funciona

Lista la alerta más reciente de tu empresa:

```bash
curl -u "$RAPID_CLIENT_ID:$RAPID_CLIENT_SECRET" \
  "https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts?per_page=1"
```

| Respuesta | Qué significa |
|---|---|
| `200` con `data` y `meta` | Credencial correcta. `data` puede venir vacío si todavía no llegó ninguna alerta |
| `401 UNAUTHORIZED` | `client_id` o `client_secret` incorrecto |
| `403 COMPANY_BLOCKED` | La empresa está bloqueada en Rapid: habla con soporte |

## 3. Registra el webhook

En **Configuración › Webhook**, registra la URL que va a recibir los eventos. Tiene que ser **HTTPS** y una **dirección pública de internet**: el panel rechaza `http://`, `localhost` e IPs de red local.

Al guardar, Rapid genera la **clave de firma** y la muestra una sola vez. Guárdala en `RAPID_WEBHOOK_SECRET`.

Para recibir en tu máquina durante el desarrollo, expón el servidor local con un túnel HTTPS (ver [Buenas prácticas](https://doc.rapidchargeback.com/es/canais/webhook/boas-praticas/#usa-una-dirección-pública-de-internet)).

## 4. Valida la firma

Toda entrega trae `X-Webhook-Signature` y `X-Webhook-Timestamp`. Tu endpoint verifica la firma **antes** de procesar cualquier cosa.

Copia el endpoint listo de tu lenguaje (Node.js, Python o PHP) en [Autenticación del webhook](https://doc.rapidchargeback.com/es/canais/webhook/autenticacao/#ejemplos). Los tres siguen las mismas reglas:

- la firma se calcula sobre el **cuerpo crudo**: no lo leas como JSON antes de validar
- una entrega con más de 5 minutos se rechaza (protección contra reenvío)
- toda entrega que no pase recibe `401`

Responde `2xx` rápido y procesa después, en una cola: Rapid espera hasta 30 segundos y, sin respuesta, lo intenta de nuevo. Usa el `alert_id` para no procesar la misma alerta dos veces. Ver [Buenas prácticas](https://doc.rapidchargeback.com/es/canais/webhook/boas-praticas/).

## 5. Envía la primera transacción

Si usas **Prevención** o **Disputa**, trabajan con las transacciones de venta que envías. Cada transacción indica de qué merchant (tienda, marca o vendedor) es, por el `merchant_id`. Mira los tuyos:

```bash
curl -u "$RAPID_CLIENT_ID:$RAPID_CLIENT_SECRET" \
  "https://api.rapidchargeback.com/api/v1/merchants"
```

El `id` de cada ítem de la respuesta es el `merchant_id` (ver [Listar merchants](https://doc.rapidchargeback.com/es/canais/merchants/listar-merchants/)). Con él, la transacción mínima:

```bash
curl -X POST https://api.rapidchargeback.com/api/v1/transactions \
  -u "$RAPID_CLIENT_ID:$RAPID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "00000000-0000-0000-0000-000000000001",
    "external_id": "TXN-2026-001",
    "transaction_id": "cob_8f2a91c4",
    "transaction_date": "2026-04-01T15:30:00Z",
    "amount": 150.00,
    "currency": "USD",
    "card_bin": "424242",
    "card_last4": "4242",
    "items": [
      { "product_description": "Assinatura Premium - Mensal", "unit_price": 150.00 }
    ]
  }'
```

- El `transaction_id` es el identificador del cobro en tu gateway de pago. Es por él que un contracargo futuro encuentra la transacción: sin él la defensa sale sin historial.
- La respuesta es `201` con el `id` de la transacción en Rapid: guárdalo. Si lo pierdes, puedes encontrar la transacción [por el `external_id`](https://doc.rapidchargeback.com/es/canais/transactions/consultar-transacao/#por-el-id-de-tu-sistema).
- Si viene la clave `warnings`, la transacción se creó, pero faltan campos que mejoran la protección.

Todos los campos en [Crear transacción](https://doc.rapidchargeback.com/es/canais/transactions/criar-transacao/). Para volumen, usa el [envío por lotes](https://doc.rapidchargeback.com/es/canais/transactions/envio-em-lote/).

## 6. Responde la primera alerta

Cuando llega una alerta de **Mastercard**, tienes **24 horas** para responder. Con el `alert_id` recibido en el webhook:

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

| Estado | Cuándo usarlo |
|---|---|
| `notfound` | La transacción no existe en tu sistema |
| `account_suspended` | La transacción existe y ya está resuelta (reembolso hecho, acceso cortado) |
| `other` | La transacción existe, pero todavía no está resuelta |

Una alerta de **Visa** llega con el reembolso ya hecho y no tiene plazo. Ver [Reglas y plazos](https://doc.rapidchargeback.com/es/produtos/alerta/regras-e-prazos/).

## Antes de ir a producción

- [ ] Credenciales y clave de firma en variables de entorno o en un gestor de secretos
- [ ] El webhook valida la firma y la ventana de 5 minutos, y rechaza con `401`
- [ ] El webhook responde `2xx` en menos de 30 segundos y procesa en cola
- [ ] El mismo `alert_id` procesado dos veces no genera efecto duplicado
- [ ] Alerta de Mastercard respondida en hasta 24 horas, de forma automática o por alguien de guardia
- [ ] Transacciones con `transaction_id` completo, si usas Disputa
- [ ] `429` manejado esperando el `Retry-After` (ver [Códigos de respuesta](https://doc.rapidchargeback.com/es/referencia/codigos-de-resposta/#rate-limit))

## Próximos pasos

- [Payload del webhook](https://doc.rapidchargeback.com/es/canais/webhook/payload/): todos los campos de cada evento.
- [Problemas comunes](https://doc.rapidchargeback.com/es/referencia/problemas-comuns/): qué hacer cuando algo no funciona.
- [Herramientas para devs](https://doc.rapidchargeback.com/es/referencia/ferramentas-para-devs/): la documentación en tu asistente de IA y la colección de Postman.