Atualização Cadastral de Sellers

A atualização cadastral é o processo pelo qual a Zoop solicita ao marketplace que revise os dados de um seller após o onboarding. A revisão pode ser disparada por dois motivos:

• ACP — Atualização Cadastral Periódica: recorrente, em intervalos pré-definidos pela Zoop.
• ACI — Atualização por Inconsistência: pontual, quando a Zoop identifica inconsistência ou insuficiência nos dados do seller.

Ambos os fluxos usam o mesmo evento de webhook (regulatory.registration.review.required) e o mesmo endpoint de envio (PUT /registration/review). O que diferencia o fluxo é o campo payload.object.type, que define também as regras de prazo e completude.

⚠️

Obrigatório

O cumprimento dos fluxos de ACP e ACI faz parte das exigências regulatórias do setor de meios de pagamento. O não atendimento aos prazos pode sujeitar o seller a penalidades, incluindo bloqueio de movimentações financeiras.

Conceitos

ACP — Atualização Cadastral Periódica

Disparada de forma recorrente pela Zoop em um momento pré-determinado do ciclo de vida do seller. O marketplace não tem visibilidade prévia da data do próximo disparo de cada seller e deve manter o endpoint receptor de webhooks sempre operacional.

A ACP exige envio completo de todos os campos cadastrais previstos em uma atualização cadastral para o tipo de seller (PF ou PJ), independentemente de já estarem corretos na base da Zoop.

ACI — Atualização por Inconsistência

Disparada pela Zoop quando uma inconsistência ou insuficiência é identificada nos dados de um seller. Pode ocorrer:

• após o onboarding;
• após uma ACP (quando os dados enviados ainda apresentam inconsistência);
• após uma ACI anterior (quando a inconsistência persiste).

A ACI permite envio parcial: o marketplace deve atualizar apenas os campos listados em payload.requested_fields. Os demais campos do seller permanecem inalterados.

Fluxo end-to-end

O processo envolve três atores: Zoop, marketplace e seller.

┌─────────┐    1. webhook    ┌──────────────┐    2. coleta    ┌────────┐
│  Zoop   │ ───────────────> │  Marketplace │ ──────────────> │ Seller │
│         │                  │              │                 │        │
│         │                  │              │ <────────────── │        │
│         │                  │              │   3. devolve    │        │
│         │ <─────────────── │              │                 │        │
└─────────┘   4. envio API   └──────────────┘                 └────────┘

1. A Zoop dispara o webhook O evento regulatory.registration.review.required é entregue ao endpoint de webhooks configurado pelo marketplace. O payload identifica o seller, o tipo de fluxo (ACP ou ACI), o prazo e os campos a serem atualizados.

2. O marketplace solicita os dados ao seller Ao receber o webhook, o marketplace deve iniciar uma jornada de coleta com o seller (in-app, e-mail, push, formulário etc.) para obter os dados solicitados. Os dados devem ser coletados diretamente do seller no momento da solicitação.

3. O seller devolve os dados ao marketplace O seller informa os dados atualizados pela jornada criada pelo marketplace.

4. O marketplace envia os dados à Zoop Com os dados em mãos, o marketplace chama PUT /registration/review enviando o payload conforme o tipo de fluxo. A Zoop processa a requisição, atualiza o cadastro e marca o processo como FINISHED.

Webhook

Evento

Payload

{
  "id": "evt_abc123",
  "type": "regulatory.registration.review.required",
  "created_at": "2026-06-15T10:30:00Z",
  "payload": {
    "object": {
      "type": "REGISTRATION_REVIEW_REQUIRED",
      "process_id": "prc_9f8e7d6c5b4a",
      "customer_id": "sel_1a2b3c4d5e6f",
      "status": "PENDING",
      "deadline_at": "2026-08-14T23:59:59Z",
      "requested_fields": [
        "revenue",
        "address.line1",
        "address.postal_code"
      ]
    }
  }
}

Campos relevantes

Como diferenciar ACP de ACI

O evento é o mesmo em ambos os fluxos. A diferenciação se faz pelo campo payload.object.type:

if (payload.object.type === "REGISTRATION_REVIEW_REQUIRED") {
  // Fluxo ACP — envie todos os campos cadastrais previstos para o tipo de seller
} else if (payload.object.type === "INCONSISTENT_DATA_UPDATE_REQUIRED") {
  // Fluxo ACI — envie apenas os campos listados em requested_fields
}

Endpoint de envio

Após coletar os dados com o seller, o marketplace envia a atualização à Zoop.

PUT /v1/marketplaces/{marketplace_id}/sellers/{seller_id}/registration/review

Documentação de referência: Atualizar registro de revisão cadastral.

Autenticação

A chamada exige mTLS combinado com autenticação Basic ou Bearer, conforme configuração do marketplace no ambiente de produção.

Headers

Body — ACP (envio completo)

Para o fluxo ACP, o marketplace deve enviar todos os campos cadastrais previstos para o tipo de seller.

Pessoa Física:

{
  "process_id": "prc_9f8e7d6c5b4a",
  "revenue": "10000_to_50000",
  "address": {
    "line1": "Avenida Paulista, 1000",
    "line2": "Apto 502",
    "line3": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01310100",
    "country_code": "BR"
  }
}

Pessoa Jurídica: inclui adicionalmente owner.revenue e owner.address referentes ao representante legal.

{
  "process_id": "prc_9f8e7d6c5b4a",
  "revenue": "100000_to_500000",
  "address": {
    "line1": "Avenida Paulista, 1000",
    "line2": "Conj. 1501",
    "line3": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01310100",
    "country_code": "BR"
  },
  "owner": {
    "revenue": "50000_to_100000",
    "address": {
      "line1": "Rua das Flores, 250",
      "line2": "Casa 2",
      "line3": "Vila Madalena",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "05432010",
      "country_code": "BR"
    }
  }
}

Body — ACI (envio parcial)

Para o fluxo ACI, o marketplace deve enviar apenas os campos listados em requested_fields no webhook. Os demais campos do seller serão preservados.

{
  "process_id": "prc_9f8e7d6c5b4a",
  "revenue": "50000_to_100000",
  "address": {
    "postal_code": "01310100"
  }
}

Validações de campos

ℹ️

Atenção ao formato de endereço

A Seller API utiliza o formato line1 / line2 / line3, distinto do formato adotado pelos endpoints bancários (street / number / complement). Ao chamar PUT /registration/review, utilize sempre o formato line*.

Respostas

Status e prazos

Cada processo de atualização passa por até quatro status ao longo de seu ciclo de vida.

Prazo da ACP

A ACP tem prazo total de 60 dias, divididos em duas fases:

• Dias 0–30 (PENDING): prazo regular para regularização.
• Dias 30–60 (OVERDUE): período de tolerância. O envio permanece válido.

Prazo da ACI

A ACI tem prazo total de 30 dias e não possui fase PENDING: o processo inicia diretamente em OVERDUE.

Envio após EXPIRED

O endpoint PUT /registration/review continua aceitando envios mesmo após o status EXPIRED — não há bloqueio técnico ao envio. Contudo, sellers em EXPIRED ficam sujeitos a penalidades regulatórias, que podem incluir o bloqueio de movimentações financeiras (cash-in e cash-out).

A recomendação é que o marketplace priorize o envio dos dados de processos OVERDUE e EXPIRED o quanto antes para mitigar riscos ao seller.

Regras de coleta

As regras a seguir são obrigatórias e podem ser objeto de auditoria pela Zoop. O descumprimento pode acarretar penalidades regulatórias ao marketplace.

1. Os dados devem ser coletados diretamente do seller

Os dados enviados em ACP ou ACI devem ser obtidos diretamente do seller no momento da solicitação, por meio de jornada ativa (in-app, e-mail, formulário etc.).

Não é permitido preencher o payload de envio com:

• dados de bureaus ou fontes externas;
• dados da base interna do marketplace;
• dados coletados no onboarding do seller;
• dados de envios anteriores (ACP ou ACI prévias).

A Zoop poderá solicitar evidências (telas, fluxos, logs) que comprovem a coleta direta no momento da revisão.

2. Envio completo em ACP, parcial em ACI

• Em ACP, todos os campos cadastrais previstos para o tipo de seller (PF ou PJ) devem ser enviados, independentemente de o dado já estar correto na base.
• Em ACI, apenas os campos listados em payload.requested_fields devem ser enviados. Enviar campos fora dessa lista pode resultar em rejeição da requisição.

3. Um seller pode ter múltiplos processos abertos

Um mesmo seller pode receber notificações sucessivas — por exemplo, uma nova ACI após o envio de uma ACP, caso persista inconsistência nos dados. Cada notificação possui seu próprio process_id e deve ser tratada como um processo independente, com coleta e envio próprios.

O marketplace deve ser capaz de armazenar e processar múltiplos process_id simultâneos para o mesmo seller.

4. Use process_id como chave de idempotência

Em caso de retentativa (timeout, erro 5xx, falha de rede), a requisição deve ser reenviada utilizando o process_id como Idempotency-Key. Isso evita reprocessamento duplicado do mesmo processo.

Cenários comuns

Cenário 1 — ACP após onboarding

1. O seller foi cadastrado há N períodos. A Zoop dispara o webhook com type=REGISTRATION_REVIEW_REQUIRED.
2. O marketplace recebe o webhook, responde 200 OK e aciona o seller para coleta.
3. O seller informa os dados atualizados pela jornada criada pelo marketplace.
4. O marketplace chama PUT /registration/review com todos os campos previstos para o tipo do seller.
5. A Zoop responde 200 OK e o processo passa a FINISHED.

Cenário 2 — ACI após inconsistência identificada

1. A Zoop identifica inconsistência em campos específicos do cadastro do seller e dispara o webhook com type=INCONSISTENT_DATA_UPDATE_REQUIRED. O campo requested_fields lista os campos com inconsistência.
2. O marketplace responde 200 OK e aciona o seller para coleta dos campos solicitados.
3. O seller informa os dados pela jornada criada pelo marketplace.
4. O marketplace chama PUT /registration/review enviando apenas os campos listados em requested_fields.
5. A Zoop responde 200 OK e o processo passa a FINISHED.

Cenário 3 — ACI subsequente a uma ACP

1. O marketplace concluiu uma ACP com sucesso (processo FINISHED).
2. Durante o processamento dos dados recebidos, a Zoop identifica inconsistência em um ou mais campos. Minutos depois, um novo webhook é disparado com type=INCONSISTENT_DATA_UPDATE_REQUIRED e um novo process_id, listando os campos a serem corrigidos.
3. O marketplace trata como um processo novo e independente: aciona o seller, coleta os dados solicitados e envia.

Cenário 4 — Múltiplas ACIs em sequência

Se uma ACI for finalizada e ainda restar inconsistência nos dados, a Zoop poderá disparar nova ACI com novo process_id. O marketplace deve ser capaz de processar quantas ACIs forem necessárias até a estabilização do cadastro.

Cenário 5 — Retentativa após erro 500

1. O marketplace envia PUT /registration/review. A Zoop responde 500 Internal Server Error.
2. O marketplace reenvia a mesma requisição, com o mesmo payload e utilizando process_id como Idempotency-Key.
3. Em caso de persistência do erro, o marketplace deve abrir chamado no suporte. O processo permanece em seu status atual (PENDING ou OVERDUE) e o prazo continua correndo.

Referências

• POST webhook regulatory.registration.review.required
• PUT /v1/marketplaces/{marketplace_id}/sellers/{seller_id}/registration/review
• Configuração de notificações e eventos