VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa

Planos de seller

Como a loja define planos para os sellers do marketplace: mensalidade, comissão, limites e recursos.

Em um marketplace, cada seller (lojista) vende na plataforma sob um plano. O plano define o que ele paga (mensalidade e comissão sobre as vendas) e o que pode fazer (limite de produtos, limite de faturamento, loja própria e recursos como WhatsApp). Esta área cria os planos e coloca cada seller em um deles.

Pontos principais
  • Tudo fica atrás do módulo vendor-plans. Leitura aceita manage_vendors ou view_vendors; escrita exige manage_vendors.
  • O id do plano é um inteiro, não um UUID. O id do seller é UUID.
  • Preços e comissões fixas são em centavos; comissão percentual em pontos-base (800 = 8,00%).
  • 0 em products_limit e revenue_limit_cents significa sem limite.
  • Só pode existir um plano padrão (is_default), que é o que um seller novo recebe.
  • O administrador pode colocar um seller num plano mesmo acima do limite; a resposta avisa mas não bloqueia.

Como funciona

  1. Crie os planos (por exemplo Básico, Pro, Enterprise).
  2. Marque um como padrão (is_default).
  3. Atribua o plano a cada seller e acompanhe os assinantes.
  4. Os limites e a comissão do plano passam a valer para o seller.

Status do plano

ValorSignificado
AAtivo: aparece e pode ser atribuído.
HOculto: não aparece na página pública de preços, mas pode ser atribuído.
DDesativado: não pode ser atribuído, e não pode ser colocado nesse estado enquanto houver sellers nele.

Periodicidade

month (mensal), year (anual) ou onetime (pagamento único).

Como a comissão é calculada

A comissão de um pedido é commission_bps sobre o valor comissionável mais fixed_commission_cents por pedido. include_shipping e include_taxes dizem se o frete e os impostos entram na base.

Endpoints

MétodoCaminhoPara quê
GET/api/v1/admin/vendor-plansLista planos
POST/api/v1/admin/vendor-plansCria plano
GET/api/v1/admin/vendor-plans/{id}Consulta plano
PUT/api/v1/admin/vendor-plans/{id}Altera plano
DELETE/api/v1/admin/vendor-plans/{id}Apaga plano
GET/api/v1/admin/vendor-plans/{id}/subscribersLista assinantes
POST/api/v1/admin/vendor-plans/{id}/assignAtribui a um seller

Erros comuns

  • Apagar um plano com sellers. Volta 409; mova os sellers antes.
  • Desativar (D) um plano em uso. Volta 400 com a contagem de sellers.
  • Atribuir um plano desativado. Volta 400 plan N is disabled.
  • Esperar que atribuir bloqueie quem passou do limite. Para o administrador, não bloqueia: leia assigned_over_limit.
  • Confundir price_cents com reais. 7770 é R$ 77,70.
  • Mandar só parte do corpo no PUT e esperar zerar o resto. O PUT é parcial: campos omitidos não mudam.

Próximos passos

Planos
Crie e edite planos.
Assinantes
Veja quem usa e atribua planos.
Anterior
Vitrines dos sellers
Próxima
Planos
Nesta página
  • Como funciona
  • Status do plano
  • Periodicidade
  • Como a comissão é calculada
  • Endpoints
  • Erros comuns
  • Próximos passos