Pular para o conteúdo

↑↓ navegar ↵ abrir Ctrl↵ nova aba esc fechar

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.

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_DUPLICATE com o merchant_id do merchant que já tem o nome. Grave a referência nele uma vez com 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

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 com retry_rejected: true.

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):

  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.

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.

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.

Uso por merchant devolve quantos alertas cobráveis cada vendedor teve no ciclo de cobrança atual ou num ciclo fechado.

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.


LimiteValor
Itens por lote500
Escritas por minuto (cada lote conta uma)60 por empresa
Lotes ao mesmo tempo1 de merchants e 1 de enrollments por empresa (BATCH_IN_PROGRESS)
Enrollments esperando aprovação20.000 por empresa (ENROLLMENT_PENDING_LIMIT)
Consultas de uso por minuto10 por empresa

Ver também Rate limit.