# Primeira integração

> Do zero ao primeiro alerta respondido: credenciais, webhook com assinatura validada, primeira transação e o callback de status, com os comandos prontos.

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

O caminho mais curto até a integração funcionando. Ao fim deste guia a sua aplicação recebe alertas com a assinatura validada, envia transações e responde alertas pela API. Cada passo aponta para a página com o detalhe completo.

## 1. Pegue as credenciais

No painel da Rapid, em **Configurações › API**, gere o `client_id` e o `client_secret`. O segredo aparece **uma única vez**: copie na hora. Se perder, gere de novo no mesmo lugar (as credenciais anteriores deixam de valer no mesmo instante).

Guarde as duas em variáveis de ambiente, nunca no código:

```bash
export RAPID_CLIENT_ID="seu_client_id"
export RAPID_CLIENT_SECRET="seu_client_secret"
```

Detalhes em [Autenticação](https://doc.rapidchargeback.com/referencia/autenticacao/).

## 2. Confirme que a credencial funciona

Liste o alerta mais recente da sua empresa:

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

| Resposta | O que significa |
|---|---|
| `200` com `data` e `meta` | Credencial certa. `data` pode vir vazio se ainda não chegou nenhum alerta |
| `401 UNAUTHORIZED` | `client_id` ou `client_secret` errado |
| `403 COMPANY_BLOCKED` | A empresa está bloqueada na Rapid: fale com o suporte |

## 3. Cadastre o webhook

Em **Configurações › Webhook**, cadastre a URL que vai receber os eventos. Ela precisa ser **HTTPS** e de **endereço público de internet**: o painel recusa `http://`, `localhost` e IP de rede local.

Ao salvar, a Rapid gera a **chave de assinatura** e mostra uma única vez. Guarde em `RAPID_WEBHOOK_SECRET`.

Para receber na sua máquina durante o desenvolvimento, exponha o servidor local com um túnel HTTPS (ver [Boas práticas](https://doc.rapidchargeback.com/canais/webhook/boas-praticas/#use-um-endereço-público-de-internet)).

## 4. Valide a assinatura

Toda entrega traz `X-Webhook-Signature` e `X-Webhook-Timestamp`. O seu endpoint confere a assinatura **antes** de processar qualquer coisa.

Copie o endpoint pronto da sua linguagem (Node.js, Python ou PHP) em [Autenticação do webhook](https://doc.rapidchargeback.com/canais/webhook/autenticacao/#exemplos). Os três seguem as mesmas regras:

- a assinatura é calculada sobre o **corpo bruto**: não leia como JSON antes de validar
- entrega com mais de 5 minutos é recusada (proteção contra reenvio)
- qualquer entrega que não passe recebe `401`

Responda `2xx` rápido e processe depois, numa fila: a Rapid espera até 30 segundos e, sem resposta, tenta de novo. Use o `alert_id` para não processar o mesmo alerta duas vezes. Ver [Boas práticas](https://doc.rapidchargeback.com/canais/webhook/boas-praticas/).

## 5. Envie a primeira transação

Se você usa a **Prevenção** ou a **Disputa**, elas trabalham com as transações de venda que você envia. Cada transação diz de qual merchant (loja, marca ou vendedor) ela é, pelo `merchant_id`. Veja os seus:

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

O `id` de cada item da resposta é o `merchant_id` (ver [Listar merchants](https://doc.rapidchargeback.com/canais/merchants/listar-merchants/)). Com ele, a transação 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 }
    ]
  }'
```

- O `transaction_id` é o identificador da cobrança no seu gateway de pagamento. É por ele que um chargeback futuro encontra a transação: sem ele a defesa sai sem histórico.
- A resposta é `201` com o `id` da transação na Rapid: guarde. Se perder, dá para achar a transação [pelo `external_id`](https://doc.rapidchargeback.com/canais/transactions/consultar-transacao/#pelo-id-do-seu-sistema).
- Se vier a chave `warnings`, a transação foi criada, mas faltam campos que melhoram a proteção.

Todos os campos em [Criar transação](https://doc.rapidchargeback.com/canais/transactions/criar-transacao/). Para volume, use o [envio em lote](https://doc.rapidchargeback.com/canais/transactions/envio-em-lote/).

## 6. Responda o primeiro alerta

Quando chegar um alerta de **Mastercard**, você tem **24 horas** para responder. Com o `alert_id` recebido no 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" }'
```

| Status | Quando usar |
|---|---|
| `notfound` | A transação não existe no seu sistema |
| `account_suspended` | A transação existe e já está resolvida (estorno feito, acesso cortado) |
| `other` | A transação existe, mas ainda não está resolvida |

Alerta de **Visa** chega com o estorno já feito e não tem prazo. Ver [Regras e prazos](https://doc.rapidchargeback.com/produtos/alerta/regras-e-prazos/).

## Antes de ir para produção

- [ ] Credenciais e chave de assinatura em variáveis de ambiente ou cofre de segredos
- [ ] Webhook valida a assinatura e a janela de 5 minutos, e recusa com `401`
- [ ] Webhook responde `2xx` em menos de 30 segundos e processa em fila
- [ ] O mesmo `alert_id` processado duas vezes não gera efeito duplicado
- [ ] Alerta de Mastercard respondido em até 24 horas, de forma automática ou por alguém de plantão
- [ ] Transações com `transaction_id` preenchido, se você usa a Disputa
- [ ] `429` tratado esperando o `Retry-After` (ver [Códigos de resposta](https://doc.rapidchargeback.com/referencia/codigos-de-resposta/#rate-limit))

## Próximos passos

- [Payload do webhook](https://doc.rapidchargeback.com/canais/webhook/payload/): todos os campos de cada evento.
- [Ferramentas para devs](https://doc.rapidchargeback.com/referencia/ferramentas-para-devs/): a documentação no seu assistente de IA e a coleção do Postman.