Guia de sincronização
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
Seção intitulada “1. Merchants: a base inteira, todo dia”Mande a sua base de vendedores pelo 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_DUPLICATEcom omerchant_iddo merchant que já tem o nome. Grave a referência nele uma vez com Editar merchant (PATCHcommerchant_ref); daí em diante o lote o atualiza. merchant_refnão diferencia maiúsculas nem acentos.PB-a1epb-A1são a mesma referência. Se o seu sistema tem vendedores que só diferem nisso, a API recusa o segundo comMERCHANT_REF_CONFLICTem 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
Seção intitulada “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). Peça cada um uma vez, quando o vendedor entra na sua base, com Pedir enrollment ou o 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 comretry_rejected: true.
3. Acompanhar a aprovação
Seção intitulada “3. Acompanhar a aprovação”Consulte 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):
- Guarde o maior
updated_atque você recebeu. - Na consulta seguinte, mande esse valor menos 2 minutos como
updated_since. - Ignore o par (
id,updated_at) que você já processou. - 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
Seção intitulada “4. Alertas com o seu vendedor”Cada alerta traz o merchant_ref do vendedor, na consulta de alertas e no webhook 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
Seção intitulada “5. Saída de um vendedor”Liste os enrollments dele com Listar enrollments filtrando por merchant_ref e peça a desativação 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.
6. Uso do mês por vendedor
Seção intitulada “6. Uso do mês por vendedor”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
Seção intitulada “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
Seção intitulada “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.