Sellers (lojistas)

Seller (lojista, ou vendor na API) é a empresa que vende dentro da loja. Cada seller tem cadastro próprio (razão social, CNPJ, endereço, dados bancários), um slug que forma a URL da vitrine dele, uma taxa de comissão que a plataforma retém de cada venda, e uma equipe de usuários que acessam o painel do seller. Esta seção é o cadastro visto pelo administrador da loja. Preferências do seller (categorias permitidas, férias, visibilidade) estão em Configurações do seller.

Como funciona

Um seller novo nasce pendente. Ao ser aprovado vira ativo e pode vender. O administrador pode suspender (os produtos ativos passam a ocultos), devolver à fila (volta a pendente) ou recusar (com motivo). A exclusão tira o seller de todas as listas.

Status do seller

1. Cadastre ou receba a candidatura

   Crie o seller pelo painel, ou o seller se candidata pela vitrine e aparece como pendente (veja Candidaturas).

2. Complete o cadastro

   Use Completude do cadastro para ver o que falta (CNPJ, banco) e edite os dados.

3. Aprove e acompanhe

   Mude o status para ativo e acompanhe saldo, extrato e receita.

Conceitos-chave

Dinheiro e comissão

commission_rate é percentual (10 = 10%) e marketplace_shipping_fee_bps é em pontos-base (500 = 5%). Saldos, extratos e receita saem em centavos. O seller recebe o valor bruto menos a comissão, conforme o payment_model (marketplace_collects: a plataforma recebe e repassa; direct_to_vendor: o pagamento vai direto ao seller).

Ids

O id do seller é UUID. Há também display_id, um número sequencial amigável para telas (não use como chave).

Slug

Minúsculas, números e hífens (^[a-z0-9]+(-[a-z0-9]+)*$), de 2 a 100 caracteres, fora a lista de nomes reservados (admin, por exemplo). Se você não enviar, ele é gerado do nome e, se já existir, ganha sufixo (-2, -3). O slug de um seller excluído não é reaproveitado.

Endpoints

Erros comuns

• Ler status como palavra. O JSON traz A, P, D, R. O objeto status_counts da lista, ao contrário, usa palavras.
• Mandar a comissão em pontos-base. commission_rate: 1000 é recusado (vendor_commission_rate_out_of_range); é percentual de 0 a 100.
• Esperar 404 em id mal formado. GET /vendors/abc devolve 404, mas outras rotas com id inválido respondem 500.
• Tentar trocar a senha por PUT /vendors/{id}. O campo password é recusado (400 password_not_updatable); use a rota de usuário.
• Confundir suspender com excluir. As duas usam a letra D, mas excluir preenche deleted_at e remove o seller das listas.
• Esquecer que criar dispara e-mail. Sem user_id, o dono é criado e recebe login e senha por e-mail.

Próximos passos