Este guia descreve o caminho principal para colocar um novo vendedor em produção: a sequência única e comum de chamadas que um desenvolvedor deve seguir para registrar um lojista, vincular uma conta bancária de liquidação, atribuir um plano de split, enviar documentos de KYC e acompanhar a conta avançar até o estado ativo. Se o seu vendedor precisa existir abaixo de um lojista já cadastrado (por exemplo, uma filial ou uma loja virtual), pule para a Etapa 1 — Registro e use o ramo de subconta.

​
Visão geral

O onboarding produz uma conta unificada totalmente provisionada e espelhada na infraestrutura de processamento. Ao final do fluxo você terá:
  • Uma conta unificada visível em GET /unified/accounts/sellers/ com zoop_id preenchido.
  • Uma conta bancária unificada com os dados de liquidação, propagada para a infraestrutura de processamento.
  • Um split unificado vinculado a um plano de split (atribuído automaticamente no fluxo padrão), de modo que taxas e comissões sejam calculadas a cada venda.
  • Um ou mais documentos unificados com as imagens de KYC enviadas à infraestrutura de processamento.
  • A capacidade de chamar POST /unified/accounts/sellers/{sellers_pk}/transactions/ e demais endpoints relacionados.
Por trás dos panos, a plataforma utiliza o padrão Sales / Unified / Jobs: o registro unificado é a verdade local, e um job em segundo plano o propaga para a infraestrutura de processamento e traz os resultados de volta.
Toda a sequência é assíncrona após a Etapa 1. A resposta HTTP da chamada de criação retorna imediatamente com zoop_id: null — o identificador histórico na infraestrutura de processamento e as associações de banco e plano são preenchidos nos segundos seguintes, assim que o job de registro for executado.

​
Decisão: pessoa física ou jurídica? Independente ou subconta?

Duas escolhas ortogonais moldam o seu payload.
O campo type da conta define o formato jurídico.
  • SELLER_PF / SUB_SELLER_PF — pessoa física brasileira. Exige um objeto person com CPF (taxpayer_id, 11 dígitos). Os documentos de KYC são da pessoa física (selfie + RG ou CNH).
  • SELLER_PJ / SUB_SELLER_PJ — pessoa jurídica brasileira. Exige tanto um objeto person (o representante legal / titular) quanto um objeto company com CNPJ (tax_id, 14 dígitos).
A criação é rejeitada com 400 se type for SELLER_PJ/SUB_SELLER_PJ e o objeto company estiver ausente.Taxas, exigências de KYC e planos de split disponíveis dependem do tipo — escolha com cuidado, raramente é alterado depois.
  • Vendedores independentes (SELLER_PF / SELLER_PJ) são lojistas de nível superior, registrados diretamente na infraestrutura de processamento. Eles possuem a própria conta bancária, o próprio split e o próprio zoop_id.
  • Subcontas (SUB_SELLER_PF / SUB_SELLER_PJ) ficam abaixo de um vendedor existente (seu parent). Elas não são registradas separadamente na infraestrutura de processamento — reutilizam o zoop_id do pai para chamadas à rede de adquirência, mas mantêm seus próprios dados de pessoa/empresa para fins de relatório, extrato e roteamento de split. Use este modelo para filiais, quiosques ou agentes de venda que devem aparecer distintos nos relatórios, mas liquidar sob um único guarda-chuva.
Na prática, isso é exposto pela flag de subconta e usado pelos consumidores ao rotear transações pelo vendedor pai.

​
Etapa 1 — Registrar o vendedor

Existem dois pontos de entrada HTTP, dependendo de o caso ser um vendedor independente ou uma subconta.
1

Vendedor independente — POST /unified/accounts/sellers/

Crie a conta unificada por meio do mesmo roteador usado para listar vendedores. O corpo é validado e exige o formato aninhado completo: person (sempre), company (quando type for PJ), bank_account, além dos campos regulatórios mcc, category, revenue, statement_descriptor e email.Opcional: informe um invitation_link (um short_id vindo de POST …/invitation-links/) para pré-preencher o split (agente / N1 / N2 / plano) e, se o link carregar um parent, promover automaticamente a conta a subconta.
curl -X POST https://api.dlpay.cloud/unified/accounts/sellers/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SELLER_PJ",
    "email": "owner@acme.com.br",
    "mcc": "5311",
    "category": "RETAIL",
    "revenue": 5000000,
    "statement_descriptor": "ACME",
    "person": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "taxpayer_id": "12345678901",
      "mother_name": "Anne Byron",
      "birthdate": "1990-01-15",
      "phone": "+5511999990000",
      "email": "ada@acme.com.br",
      "address": {
        "street": "Av. Paulista", "number": "1000",
        "neighborhood": "Bela Vista", "city": "São Paulo",
        "state": "SP", "postal_code": "01310100", "country_code": "BR"
      }
    },
    "company": {
      "name": "ACME Comércio LTDA",
      "tax_id": "12345678000199",
      "email": "contato@acme.com.br",
      "phone": "+551133334444",
      "address": {
        "street": "Av. Paulista", "number": "1000",
        "neighborhood": "Bela Vista", "city": "São Paulo",
        "state": "SP", "postal_code": "01310100", "country_code": "BR"
      }
    },
    "bank_account": {
      "number": "00012345-7",
      "agency": "0001",
      "code": "001",
      "type": "CHECKING_ACCOUNT"
    }
  }'
A resposta é a nova conta no formato aninhado completo. O chamador recebe automaticamente um vínculo de acesso ligando o seu usuário à nova conta, de modo que as leituras subsequentes funcionem sem configuração adicional.
2

Subconta — POST /unified/accounts/sellers/{parent}/sub/

Quando o novo lojista pertence a um vendedor já existente, use POST /unified/accounts/sellers/{sellers_pk}/sub/ com type igual a SUB_SELLER_PF ou SUB_SELLER_PJ. A validação exige person (e company para PJ), mas não exige bank_account, mcc, category, revenue ou statement_descriptor de imediato — subcontas herdam o registro na rede de adquirência por meio do pai e podem ser preenchidas depois com PATCH .../sellers/{sellers_pk}/.O parent da nova conta é definido automaticamente a partir da URL.
3

Alternativa — endpoint de registro direto (legado)

O endpoint legado POST /seller/register/ faz proxy diretamente para os endpoints de pessoas físicas ou jurídicas da infraestrutura de processamento. Ele não cria uma conta unificada nem persiste nada localmente, e não exige autenticação no nível da view. Use-o apenas para sondagens pontuais de integração ou em migrações de dados — nunca para onboarding em produção. Os fluxos produtivos devem passar pelo roteador unificado, para que o acesso, os splits e o espelho unificado permaneçam consistentes.

​
Etapa 2 — Definir a conta bancária de liquidação

Se você usou POST /unified/accounts/sellers/, o bloco bank_account já está no payload e essa etapa pode ser pulada. Para subcontas, ou quando for necessário trocar a conta bancária posteriormente, envie uma atualização parcial do vendedor. A conta bancária é criada na primeira escrita, caso ainda não exista. 
curl -X PATCH https://api.dlpay.cloud/unified/accounts/sellers/$SELLER_ID/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_account": {
      "number": "00012345-7",
      "agency": "0001",
      "code": "001",
      "type": "CHECKING_ACCOUNT"
    }
  }'
Os campos mapeiam de forma direta para o schema de conta bancária da infraestrutura de processamento e são encaminhados quando o job de registro é executado (ou, após o registro, imediatamente, por meio da rotina de propagação da conta bancária).
CampoTipoSignificado
numberstringNúmero da conta, incluindo o dígito verificador.
agencystringNúmero da agência.
codestringCódigo bancário brasileiro de 3 dígitos (FEBRABAN). Zeros à esquerda são normalizados quando enviados à infraestrutura de processamento.
typeenumCHECKING_ACCOUNT ou SAVINGS_ACCOUNT.
Veja a referência completa dos campos em PATCH sellers.

​
Etapa 3 — Atribuir um plano de split

Um plano de split descreve como dividir cada venda entre o vendedor, o master, o agente, os distribuidores N1/N2 e o desenvolvedor, por tipo de pagamento e parcela. Todo vendedor ativo precisa ter um, caso contrário o número máximo de parcelas cai para 1 e o cálculo de split não é executado nas transações.
Quando uma conta é criada sem invitation_link, o servidor lê a configuração de plano de split padrão da plataforma (cujo valor padrão é "Plano Pro Padrão") e atribui o primeiro plano cujo nome contenha esse trecho. O split criado fica sinalizado como gerenciado pelo sistema.Se a configuração de plano padrão estiver vazia, nenhum split automático é criado e você precisará defini-lo explicitamente (próximo accordion).
Para sobrescrever o plano ou os destinatários da comissão, liste os planos disponíveis e, em seguida, atualize o split da conta:
curl https://api.dlpay.cloud/plans/plans/split/ \
  -H "Authorization: Bearer $ACCESS_TOKEN"

curl -X PATCH https://api.dlpay.cloud/unified/accounts/sellers/$SELLER_ID/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "split": {
      "plan": "5f1e2a4b-3c5d-4f6a-9b7c-1e2d3f4a5b6c",
      "agent": "0c8a2b81-9d31-4b30-9d1f-8a8f43f1f1a1"
    }
  }'
Veja GET /plans/plans/split/ e PATCH sellers. A assinatura correspondente na infraestrutura de processamento é atualizada automaticamente quando o plano de split do vendedor muda.

​
Etapa 4 — Enviar documentos de KYC

As imagens de KYC são enviadas uma por vez via POST /unified/accounts/sellers/{sellers_pk}/documents/upload/ como multipart/form-data. O arquivo é armazenado no S3 em account/{seller_id}/documents/{document_id}.{ext}, um documento unificado é criado com status='pending' e um job é enfileirado para enviar o arquivo à infraestrutura de processamento. Formatos aceitos: PNG, JPEG, WEBP, BMP, HEIC, HEIF — validados tanto pelo tipo MIME quanto pela extensão. O campo de formulário document_type é obrigatório e deve ser um dos valores:
document_typeQuando usar
SELFIEFoto do rosto do titular, capturada ao vivo. Obrigatória para toda conta.
CNH_FULL, CNH_FRONT, CNH_BACKCarteira Nacional de Habilitação — documento aberto completo ou cada um dos lados.
RG_FRONT, RG_BACKRG brasileiro, ambos os lados.
Envie, no mínimo:
  1. Uma SELFIE.
  2. Ou CNH_FULL, ou ambos CNH_FRONT + CNH_BACK, ou ambos RG_FRONT + RG_BACK.
O representante legal (o objeto person informado no registro) precisa passar pelo KYC, e não a empresa em si neste endpoint. Envie o mesmo conjunto exigido para uma conta PF, vinculado ao identificador da conta jurídica.A documentação corporativa (contrato social etc.) é tratada hoje fora deste endpoint — alinhe com o time de operações.
curl -X POST https://api.dlpay.cloud/unified/accounts/sellers/$SELLER_ID/documents/upload/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "file=@./selfie.jpg" \
  -F "document_type=SELFIE"
Os documentos podem ser listados e inspecionados via GET …/documents/; os campos zoop_id e zoop_acquirer_status são preenchidos quando o job de envio é concluído do lado da infraestrutura de processamento.

​
Etapa 5 — Acompanhar o status de ativação

Dois campos da conta descrevem onde ela está no pipeline de onboarding. Faça polling em GET /unified/accounts/sellers/{id}/ e observe:
CampoOrigemO que significa
zoop_idDefinido pelo job de registro após a criação na infraestrutura de processamento.null até a chamada de registro ser bem-sucedida. Quando não nulo, já é possível cobrar.
zoop_internal_statusEstado interno de sincronização, mais o ciclo de vida do job local.WAITING enquanto o job de registro está enfileirado; OK depois que o vendedor é aceito; FAILED se o registro for rejeitado. A partir daí, texto livre — valores como ENABLED vindos da infraestrutura de processamento fluem verbatim.
zoop_acquirer_statusÚltima resposta ou erro conhecido na rede de adquirência.Útil para suporte quando zoop_internal_status for FAILED — carrega os primeiros 100 caracteres da mensagem de erro.
Um vendedor é considerado onboardado quando todos os itens a seguir são verdadeiros:
  1. zoop_id não é nulo.
  2. zoop_internal_status é OK (ou um valor de sucesso vindo da infraestrutura de processamento, como ENABLED).
  3. Existe uma conta bancária cadastrada.
  4. Há um plano de split definido.
  5. Documentos de KYC cobrindo selfie + identidade foram enviados e aceitos pela infraestrutura de processamento.

​
O que acontece nos bastidores

Quando a chamada de criação retorna, o vendedor ainda não existe na infraestrutura de processamento. A plataforma armazena tudo localmente primeiro e, em seguida, apoia-se no pipeline Sales / Unified / Jobs para propagar os dados.
  1. A criação salva a conta (e os objetos aninhados de pessoa, empresa, conta bancária e split) em uma única transação de banco e cria o vínculo de acesso do chamador.
  2. O split é materializado — a partir do link de convite, se houver, ou então a partir da configuração de plano de split padrão da plataforma.
  3. Se a nova conta não for subconta e a configuração de registro automático estiver ativa (o padrão é ligado), a criação enfileira o job de registro na infraestrutura de processamento.
  4. O job em segundo plano: (a) monta o vendedor e os endereços a partir dos dados unificados, (b) marca a conta como WAITING, (c) envia o vendedor para a infraestrutura de processamento, (d) associa a conta bancária, (e) anexa o plano de split como uma assinatura na infraestrutura de processamento e (f) grava de volta o zoop_id e altera zoop_internal_status para OK.
  5. Ao enviar um documento, um job paralelo baixa o arquivo do S3, o envia para a infraestrutura de processamento e atualiza o documento unificado.

​
Armadilhas comuns

O registro é rejeitado com 400 se o CPF (PF) ou CNPJ (PJ) já estiver vinculado a outro vendedor no marketplace. O job de registro captura o erro, grava a mensagem em zoop_acquirer_status e muda zoop_internal_status para FAILED. Consulte esse campo para ver o erro real — a conta unificada permanece no banco, mas não é utilizável para transações.
Para um vendedor independente, o job de registro emite um aviso e prossegue sem associar conta bancária quando ela está ausente. O vendedor é criado na infraestrutura de processamento, mas não consegue liquidar. Atualize a conta bancária depois — a alteração é detectada e a propagação é executada novamente.
Se a configuração de plano de split padrão da plataforma não combinar com nenhum plano (erro de digitação, idioma errado, plano renomeado), nenhum split é criado. A etapa de assinatura no job de registro é ignorada e o número máximo de parcelas passa a ser 1 em todas as transações futuras. Confirme sempre, em GET /plans/plans/split/, que existe um plano contendo o trecho configurado.
Em ambientes de homologação ou local, operadores às vezes desligam o registro automático. Quando ele está desligado, as contas são criadas e persistidas, mas nunca enviadas à infraestrutura de processamento — zoop_id permanece null, transações não podem ser criadas e não há erro a inspecionar. Verifique essa configuração antes de supor que o job está quebrado. O job pode ser disparado manualmente por um operador.
Subcontas são intencionalmente puladas na criação — reutilizam o zoop_id do pai. Postar transações contra uma subconta cujo pai não possui zoop_id falha com Seller not found. Sempre conclua o onboarding do pai primeiro.
O job de envio de documento precisa do zoop_id da conta pai para encaminhá-lo. Se você enviar documentos nos poucos segundos entre a criação e a conclusão do job de registro, o job de envio se reagenda. O documento unificado é criado de qualquer forma — se a espera durar mais do que o esperado, verifique antes o zoop_internal_status do vendedor.

​
Próximos passos

Fluxo de transação

Conduza o novo vendedor por sua primeira venda em cartão, PIX ou boleto.

Splits e planos

Entenda como as regras dos planos de split governam taxas, MDR e destinatários de comissão em cada transação.

Webhooks e jobs

Aprofunde-se no padrão Sales / Unified / Jobs que sustenta a propagação assíncrona.

Links de convite

Gere links de cadastro que pré-vinculam comissões aos lojistas onboardados.