Cadastro de sellers

Em um marketplace, seller (lojista) é a empresa que vende produtos dentro da loja. Antes de vender, ela passa por uma análise de entrada (onboarding): envia uma candidatura, anexa documentos que provam quem é, aceita os termos de uso e, aprovada, ganha acesso ao painel. Opcionalmente ela monta uma vitrine própria (um "microsite") com logo, cores e domínio.

Esta seção reúne o lado do administrador desse processo. As rotas do próprio seller (enviar a candidatura, subir documentos, aceitar termos) ficam na API do painel do seller.

Como funciona

O caminho do seller

1. O seller se candidata

   Pelo painel dele, o seller envia a candidatura. Ela nasce pending.

2. O seller anexa documentos

   O seller pode anexar documentos à própria candidatura (a primeira anexação leva a candidatura para under_review) e também enviar documentos avulsos de verificação (KYC). Cada documento nasce pendente. Veja a diferença em Conceitos importantes.

3. Você analisa

   Liste as candidaturas e os documentos de verificação, abra os arquivos e aprove ou recuse cada documento. Depois decida a candidatura.

4. O seller aceita os termos

   O seller aceita a versão ativa dos termos de uso. Cada nova versão ativada pede novo aceite.

Estados da candidatura

Estados do documento

Tipos de documento aceitos

business_license, identity, tax_registration, proof_of_address, bank_statement, other, cnpj, address, bank, id_card, cpf_cnpj, company_registration, bank_info, address_proof, tax_certificate.

Conceitos importantes

Quem decide o quê

Estas rotas são do administrador. A análise de candidatura exige manage_vendor_moderation ou manage_catalog (ler também aceita view_catalog). A de documentos exige manage_documents, manage_kyc ou manage_vendors para decidir. Termos exigem manage_vendor_terms ou manage_vendors. Vitrines exigem manage_vendor_storefronts ou manage_vendors.

Dois tipos de documento

• Documentos de verificação (KYC): enviados pelo seller de forma avulsa, ligados ao seller. São os que a lista GET /vendor-documents mostra e que as rotas de revisão desta seção tratam.
• Documentos da candidatura: anexados pelo seller à própria candidatura. Ficam ligados à candidatura, não aparecem em GET /vendor-documents e são vistos no detalhe da candidatura do seller.

Se um seller diz que "enviou o documento" e ele não está na lista, confira por qual caminho ele foi enviado.

Aprovação de documentos em lote

Quando há muitos comprovantes, a revisão em lote decide vários de uma vez. Ela só altera documentos pendentes: ids já aprovados ou recusados são ignorados sem erro, e a resposta informa quantos foram de fato revisados.

Endpoints

Erros comuns

1. Achar que aprovar os documentos aprova o seller. São decisões separadas; decida também a candidatura.
2. Decidir a candidatura sem ver os documentos. A lista de candidaturas não traz os documentos; consulte os de verificação na lista de documentos filtrando por vendor_id.
3. Aprovar em lote documentos já decididos. São ignorados; confira o campo reviewed da resposta.
4. Editar um texto de termos já aceito. PUT altera a versão no lugar, sem gerar versão nova nem pedir novo aceite. Para exigir novo aceite, crie uma versão.
5. Ativar um id errado de termos. A ativação desativa a versão corrente antes de procurar a nova; com um id inexistente, a loja pode ficar sem termos ativos.
6. Tentar excluir a versão ativa. É recusado. Ative outra antes.
7. Esperar 404 em id mal formado. Muitas destas rotas respondem 500 quando o id não é um UUID.

Próximos passos