# Guia de sincronização

> O fluxo recomendado para manter os seus vendedores, os enrollments deles e os alertas em dia com a Rapid pela API, sem duplicar nada.

Página: https://doc.rapidchargeback.com/canais/merchants/guia-de-sincronizacao/

Este guia é para quem tem muitos vendedores (lojas, marcas, subcontas) e quer manter o cadastro deles na Rapid igual ao do próprio sistema, pedir os enrollments e ligar cada alerta ao vendedor certo. Tudo se apoia no `merchant_ref`, o ID do vendedor no **seu** sistema.

## 1. Merchants: a base inteira, todo dia

Mande a sua base de vendedores pelo [Lote de merchants](https://doc.rapidchargeback.com/canais/merchants/lote-de-merchants/), até 500 por chamada, uma vez por dia (ou quando ela mudar). A chave é o `merchant_ref`:

- vendedor novo vira merchant novo (`created`);
- vendedor que mudou é atualizado (`updated`);
- vendedor igual não é gravado (`unchanged`), então reenviar a base inteira não gera falsa mudança.

Cuidados:

- **Merchant que já estava no painel, sem referência.** O lote responde `MERCHANT_DUPLICATE` com o `merchant_id` do merchant que já tem o nome. Grave a referência nele uma vez com [Editar merchant](https://doc.rapidchargeback.com/canais/merchants/editar-merchant/) (`PATCH` com `merchant_ref`); daí em diante o lote o atualiza.
- **`merchant_ref` não diferencia maiúsculas nem acentos.** `PB-a1` e `pb-A1` são a mesma referência. Se o seu sistema tem vendedores que só diferem nisso, a API recusa o segundo com `MERCHANT_REF_CONFLICT` em vez de juntar os dois.
- **A referência não se troca** depois de gravada (`MERCHANT_REF_IMMUTABLE`).

## 2. Enrollments: pedidos uma vez, quando o vendedor entra

O enrollment é o que liga os alertas a um merchant: o descriptor ou o BIN + CAID dele (ver [Enrollments](https://doc.rapidchargeback.com/canais/enrollments/visao-geral/)). Peça cada um **uma vez**, quando o vendedor entra na sua base, com [Pedir enrollment](https://doc.rapidchargeback.com/canais/enrollments/pedir-enrollment/) ou o [Lote de enrollments](https://doc.rapidchargeback.com/canais/enrollments/lote-de-enrollments/). Não inclua os enrollments no envio diário.

- Pedir de novo o mesmo enrollment devolve `existing`, sem criar outro: repetir depois de uma falha é seguro.
- Todo pedido passa pela aprovação da equipe da Rapid e nasce `pending`.
- Pedido recusado pela equipe não volta sozinho: pedir de novo responde `ENROLLMENT_PREVIOUSLY_REJECTED`. Corrija o dado e mande com `retry_rejected: true`.

## 3. Acompanhar a aprovação

Consulte [Listar enrollments](https://doc.rapidchargeback.com/canais/enrollments/listar-enrollments/) com `updated_since` a cada poucos minutos. A regra é a mesma nas três listas que aceitam esse filtro (merchants, enrollments e alertas):

1. Guarde o maior `updated_at` que você recebeu.
2. Na consulta seguinte, mande esse valor **menos 2 minutos** como `updated_since`.
3. Ignore o par (`id`, `updated_at`) que você já processou.
4. Leia as páginas até `total_pages`.

O status de cada produto do enrollment diz onde ele está: `pending`, `active`, `rejected` (com `rejection_reason`), `deactivation_requested` ou `inactive`.

## 4. Alertas com o seu vendedor

Cada alerta traz o `merchant_ref` do vendedor, na [consulta de alertas](https://doc.rapidchargeback.com/callback/consultar-alertas/) e no [webhook](https://doc.rapidchargeback.com/canais/webhook/payload/) no formato `v2` (em `merchant.merchant_ref`), junto com o `merchant_enrollment_id` do enrollment que casou. Para buscar os alertas de um vendedor, filtre por `merchant_ref`. Para buscar o que mudou, use `updated_since` com a mesma regra do passo 3.

## 5. Saída de um vendedor

Liste os enrollments dele com [Listar enrollments](https://doc.rapidchargeback.com/canais/enrollments/listar-enrollments/) filtrando por `merchant_ref` e [peça a desativação](https://doc.rapidchargeback.com/canais/enrollments/pedir-desativacao/) de cada um. A equipe da Rapid confirma, e o enrollment continua recebendo alertas até a confirmação. Se quiser, marque o merchant com `status: "inactive"` em [Editar merchant](https://doc.rapidchargeback.com/canais/merchants/editar-merchant/).

## 6. Uso do mês por vendedor

[Uso por merchant](https://doc.rapidchargeback.com/canais/uso/uso-por-merchant/) devolve quantos alertas cobráveis cada vendedor teve no ciclo de cobrança atual ou num ciclo fechado.

## 7. Antes da carga real

Ainda não há ambiente de teste: todo pedido de enrollment feito na sua conta entra de verdade na fila de aprovação da equipe da Rapid. Antes da primeira carga grande, fale com o suporte da Rapid para combinar como validar a sua integração.

---

## Limites que valem para este fluxo

| Limite | Valor |
|---|---|
| Itens por lote | 500 |
| Escritas por minuto (cada lote conta uma) | 60 por empresa |
| Lotes ao mesmo tempo | 1 de merchants e 1 de enrollments por empresa (`BATCH_IN_PROGRESS`) |
| Enrollments esperando aprovação | 20.000 por empresa (`ENROLLMENT_PENDING_LIMIT`) |
| Consultas de uso por minuto | 10 por empresa |

Ver também [Rate limit](https://doc.rapidchargeback.com/referencia/codigos-de-resposta/#rate-limit).
