# Integração

> O que enviar para ativar a Prevenção: dados do merchant, campos mínimos da transação e os que habilitam a proteção contra fraude.

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

Para integrar a Prevenção, você precisa enviar suas transações de venda para a Rapid via **API de Transações**. Consulte a [documentação da API de Transações](https://doc.rapidchargeback.com/canais/transactions/visao-geral/) para detalhes completos dos endpoints.

## Dados do merchant

Antes de enviar transações, certifique-se de que seu merchant está cadastrado com as informações completas. Os seguintes campos do merchant são **obrigatórios** para a Prevenção funcionar:

| Campo | Descrição |
|---|---|
| `name` | Nome do merchant |
| `merchant_url` | URL do site do merchant |
| `contact_phone` | Telefone de contato |
| `store_name` | Nome da loja |

## Campos mínimos da transação

Além dos campos obrigatórios da API de Transações, a Prevenção precisa dos seguintes para funcionar:

| Campo | Por quê |
|---|---|
| `items[]` com `product_description` | Descrição dos produtos comprados. Sem ela não há o que mostrar ao banco emissor |
| `order_number` | Identificação do pedido na resposta ao banco emissor (recomendado) |

## Campos recomendados

Quanto mais dados você enviar, maior a chance de deflectir disputas. A tabela abaixo mostra os campos recomendados e o impacto de cada um:

### Para o reconhecimento da compra

| Campo | Impacto |
|---|---|
| `card_bin` | Aumenta a precisão do match com a transação em disputa |
| `auth_code` | Melhora a identificação da transação |
| `customer.first_name` e `customer.last_name` | Ajuda o portador a reconhecer a compra |
| `customer.email` | Ajuda o portador a reconhecer a compra |

### Para a proteção contra fraude

A proteção contra fraude atende disputas de **fraude**. Ela precisa de **dois sinais** de que quem comprou é o dono do cartão: um identificador da compra (a âncora) e mais um dado que confirme a pessoa.

Para qualificar uma transação, envie uma das 3 combinações abaixo. A âncora (`ip_address`, `device_id` ou `device_fingerprint`) é **obrigatória**; ao lado dela, envie **ao menos um** campo da coluna de complementos.

| Formato | Âncora obrigatória | Pelo menos um dos complementos |
|---|---|---|
| **Opção 1** | `ip_address` | `customer.account_id`, `addresses` (shipping), `device_id` ou `device_fingerprint` |
| **Opção 2** | `device_id` | `customer.account_id`, `addresses` (shipping) ou `ip_address` |
| **Opção 3** | `device_fingerprint` | `customer.account_id`, `addresses` (shipping) ou `ip_address` |

#### Campos: formato e restrições

| Campo | Requisitos |
|---|---|
| `ip_address` | IP público do comprador no momento da compra. Texto claro, não pode ser hash. Formatos IPv4 ou IPv6 |
| `device_id` | Identificador único do dispositivo (ex: IMEI). Texto claro, mín. 15 caracteres, não pode ser hash |
| `device_fingerprint` | Fingerprint derivada de atributos do dispositivo (SO, modelo, versão, etc.). Mín. 20 caracteres. Pode ser hash |
| `customer.account_id` | Identificador de autenticação do comprador no seu sistema (email, username). Um único valor |
| `addresses` (type: shipping) | Endereço de entrega completo: `street` (address1), `city`, `state` (region), `postal_code`, `country`. Não pode ser endereço de loja |

> **Você não escolhe a opção.** Envie o máximo de campos que tiver: a Rapid usa automaticamente a combinação que a sua transação cobre. Por exemplo, se você envia `ip_address + device_id + account_id`, sua transação se qualifica tanto para a Opção 1 quanto para a Opção 2, a combinação com mais campos maximiza a chance de deflexão.

#### Digital goods: não envie endereço de entrega

Se sua empresa vende **bens digitais** (software, SaaS, streaming, ebooks, cursos online, serviços sem entrega física), **não envie `addresses` com type `shipping`**. As regras da bandeira proíbem quem vende bem digital de informar endereço de entrega, e o envio pode **suspender a proteção contra fraude** da sua conta.

Para digital goods, foque nestes complementos:

| Opção | Âncora | Complementos práticos |
|---|---|---|
| 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` tendem a ser os campos mais naturais de capturar em e-commerce digital.

## Exemplo de transação 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": "192.168.1.100",
  "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 exemplo inclui todos os campos recomendados para máxima cobertura de deflexão.