# Integración

> Qué enviar para activar Prevención: datos del merchant, campos mínimos de la transacción y los que habilitan la protección contra fraude.

Página: https://doc.rapidchargeback.com/es/produtos/prevencao/integracao/

Para integrar Prevención, envías tus transacciones de venta a Rapid a través de la **API de Transacciones**. Consulta la [documentación de la API de Transacciones](https://doc.rapidchargeback.com/es/canais/transactions/visao-geral/) para los detalles completos de los endpoints.

## Datos del merchant

Antes de enviar transacciones, asegúrate de que tu merchant esté registrado con la información completa. Los siguientes campos del merchant son **obligatorios** para que Prevención funcione:

| Campo | Descripción |
|---|---|
| `name` | Nombre del merchant |
| `merchant_url` | URL del sitio del merchant |
| `contact_phone` | Teléfono de contacto |
| `store_name` | Nombre de la tienda |

## Campos mínimos de la transacción

Además de los campos obligatorios de la API de Transacciones, Prevención necesita los siguientes para funcionar:

| Campo | Por qué |
|---|---|
| `items[]` con `product_description` | Descripción de los productos comprados. Sin ella no hay qué mostrar al banco emisor |
| `order_number` | Identificación del pedido en la respuesta al banco emisor (recomendado) |

## Campos recomendados

Cuantos más datos envíes, mayor la probabilidad de desviar disputas. La tabla de abajo muestra los campos recomendados y el impacto de cada uno:

### Para el reconocimiento de la compra

| Campo | Impacto |
|---|---|
| `card_bin` | Aumenta la precisión del match con la transacción en disputa |
| `auth_code` | Mejora la identificación de la transacción |
| `customer.first_name` y `customer.last_name` | Ayuda al titular a reconocer la compra |
| `customer.email` | Ayuda al titular a reconocer la compra |

### Para la protección contra fraude

La protección contra fraude atiende disputas de **fraude**. Necesita **dos señales** de que quien compró es el dueño de la tarjeta: un identificador de la compra (el ancla) y un dato más que confirme a la persona.

Para calificar una transacción, envía una de las 3 combinaciones de abajo. El ancla (`ip_address`, `device_id` o `device_fingerprint`) es **obligatoria**; junto a ella, envía **al menos un** campo de la columna de complementos.

| Formato | Ancla obligatoria | Al menos uno de los complementos |
|---|---|---|
| **Opción 1** | `ip_address` | `customer.account_id`, `addresses` (shipping), `device_id` o `device_fingerprint` |
| **Opción 2** | `device_id` | `customer.account_id`, `addresses` (shipping) o `ip_address` |
| **Opción 3** | `device_fingerprint` | `customer.account_id`, `addresses` (shipping) o `ip_address` |

#### Campos: formato y restricciones

| Campo | Requisitos |
|---|---|
| `ip_address` | IP pública del comprador en el momento de la compra. Texto plano, no puede ser hash. IPv4 o IPv6 |
| `device_id` | Identificador único del dispositivo (ej.: IMEI). Texto plano, mín. 15 caracteres, no puede ser hash |
| `device_fingerprint` | Fingerprint derivada de atributos del dispositivo (SO, modelo, versión, etc.). Mín. 20 caracteres. Puede ser hash |
| `customer.account_id` | Identificador de inicio de sesión del comprador en tu sistema (email, username). Un único valor |
| `addresses` (type: shipping) | Dirección de envío completa: `street` (address1), `city`, `state` (region), `postal_code`, `country`. No puede ser dirección de tienda |

> **No eliges la opción.** Envía todos los campos que tengas: Rapid usa automáticamente la combinación que tu transacción cubre. Por ejemplo, si envías `ip_address + device_id + account_id`, tu transacción califica tanto para la Opción 1 como para la Opción 2, y la combinación con más campos maximiza la probabilidad de deflexión.

#### Bienes digitales: no envíes dirección de envío

Si tu empresa vende **bienes digitales** (software, SaaS, streaming, ebooks, cursos online, servicios sin entrega física), **no envíes `addresses` con type `shipping`**. Las reglas de la red de tarjetas prohíben que quien vende bienes digitales informe una dirección de envío, y enviarla puede **suspender la protección contra fraude** de tu cuenta.

Para bienes digitales, concéntrate en estos complementos:

| Opción | Ancla | Complementos prácticos |
|---|---|---|
| 1 | `ip_address` | `customer.account_id`, `device_id`, `device_fingerprint` |
| 2 | `device_id` | `customer.account_id`, `ip_address` |
| 3 | `device_fingerprint` | `customer.account_id`, `ip_address` |

`customer.account_id` e `ip_address` suelen ser los campos más naturales de capturar en e-commerce digital.

## Ejemplo de transacción completa

```json
{
  "merchant_id": "00000000-0000-0000-0000-000000000001",
  "transaction_date": "2026-04-01T15:30:00Z",
  "amount": 150.00,
  "currency": "USD",
  "card_last4": "4242",
  "card_bin": "424242",
  "order_number": "ORD-001",
  "auth_code": "AUTH999",
  "network": "visa",
  "descriptor": "LOJA EXEMPLO",
  "ip_address": "203.0.113.10",
  "device_id": "041C226BBD5A80020040105118304404",
  "external_source": "shopify",
  "external_id": "TXN-2026-001",
  "items": [
    {
      "product_description": "Assinatura Premium - Mensal",
      "product_name": "Plano Premium",
      "quantity": 1,
      "unit_price": 150.00
    }
  ],
  "customer": {
    "first_name": "João",
    "last_name": "Silva",
    "email": "joao@exemplo.com",
    "account_id": "joao@exemplo.com"
  },
  "addresses": [
    {
      "type": "shipping",
      "street": "Rua das Flores",
      "number": "123",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01001000",
      "country": "BRA"
    }
  ]
}
```

Este ejemplo incluye todos los campos recomendados para la máxima cobertura de deflexión.