Plano e documentos

Duas coisas definem a relação comercial de um seller (lojista) com a loja: o plano (quanto paga, qual comissão a loja retém, quantos produtos pode ter) e os documentos de cadastro (CNPJ, comprovantes) que a loja analisa para aprovar o seller. Esta seção documenta as cinco rotas /api/v1/vendor/plan e /api/v1/vendor/documents.

Como funciona

1. Veja o plano atual

   GET /vendor/plan devolve o plano, quanto o seller já usa (produtos e receita) e todos os recursos do plano.

2. Escolha outro plano

   A lista de planos disponíveis fica em GET /vendor/plans/available. PUT /vendor/plan troca. Se o seller já passou dos limites do plano novo, a resposta é 409 e nada muda.

3. Envie os documentos

   POST /vendor/documents (multipart) envia cada arquivo com seu tipo. O administrador revisa e o status muda.

Conceitos-chave

Limites do plano

products_limit e revenue_limit_cents valem 0 quando não há limite. Ao trocar de plano a plataforma compara o que o seller tem hoje: número de produtos e receita acumulada de todos os pedidos que não foram cancelados, reembolsados, recusados ou estornados (o histórico inteiro, não um mês). Quem já passou do limite não consegue entrar no plano.

Comissão

commission_bps é a comissão percentual em pontos-base (800 = 8%). fixed_commission_cents é um valor fixo por pedido, em centavos. include_shipping e include_taxes dizem se frete e impostos entram na base de cálculo da comissão.

Status do plano

Documentos

Aceitos: PDF, JPG, PNG e WebP, até 10 MB (o formato é conferido pelo conteúdo, não pela extensão). Status do documento: P pendente, A aprovado, R rejeitado.

Endpoints

Erros comuns

• Assumir que plan sempre existe. Seller sem plano recebe "plan": null.
• Ler price_cents como reais. 4990 é R$ 49,90 por período.
• Tentar um plano abaixo do uso atual. O 409 traz errors dizendo o que excede, em inglês.
• Enviar o arquivo como JSON. O envio é multipart/form-data, com os campos file, doc_type e notes.
• Mandar um doc_type fora da lista. Hoje isso volta 500, não 400. Use só os tipos documentados.
• Contar com o DELETE de documento. Ele só aceita documentos "ainda não revisados", mas veja o aviso na página de Documentos.

Próximos passos