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

Planos

Lista, consulta, cria, altera e apaga os planos de seller.

Cada plano tem preço, comissão, limites e recursos, além de nome e descrição por idioma.

Listar planos

GET/api/v1/admin/vendor-plansAdmin

Lista planos de seller

Parâmetros de consulta

pageintegerpadrão: 1
Página.
per_pageintegerpadrão: 50
Itens por página, de 1 a 100; fora disso vale 20.
lang_codestringpadrão: pt-BR
Idioma (padrão pt-BR).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/vendor-plans?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Planos
json
{
  "plans": [
    {
      "id": 8,
      "status": "A",
      "position": 0,
      "is_default": false,
      "price_cents": 9900,
      "periodicity": "month",
      "commission_bps": 700,
      "fixed_commission_cents": 0,
      "products_limit": 6000,
      "revenue_limit_cents": 0,
      "vendor_store": false,
      "categories": "",
      "include_shipping": false,
      "include_taxes": false,
      "price_on_request": false,
      "ministore_enabled": false,
      "ministore_whatsapp_payment": false,
      "ministore_pix_auto": false,
      "ministore_search_text": false,
      "ministore_search_audio": false,
      "ministore_search_image": false,
      "ministore_search_list_ai": false,
      "ministore_dashboard_simple": false,
      "ministore_dashboard_metrics": false,
      "ministore_dashboard_custom": false,
      "ministore_cart_recovery": false,
      "ministore_crm": false,
      "ministore_human_transfer": false,
      "ministore_integrations": false,
      "ministore_orders_included": 0,
      "ministore_excess_per_order_cents": 0,
      "ministore_excess_percentage_bps": 0,
      "created_at": "2026-07-11T19:45:31Z",
      "updated_at": "2026-09-10T13:29:00Z",
      "descriptions": [
        {
          "plan_id": 8,
          "lang_code": "pt-BR",
          "name": "Pro",
          "description": "Plano para sellers em crescimento"
        }
      ],
      "vendors_count": 1
    }
  ],
  "total": 14,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

totalinteger
Total de planos.
pageinteger
Página.
per_pageinteger
Tamanho da página.
total_pagesinteger
Total de páginas.
plansarray
Planos.
idinteger
Id do plano.
statusstring
AHD
A ativo, H oculto, D desativado.
positioninteger
Ordem de exibição.
is_defaultboolean
Plano padrão dos sellers novos.
price_centsinteger
Preço por período em centavos.
periodicitystring
monthyearonetime
month, year ou onetime.
commission_bpsinteger
Comissão percentual em pontos-base.
fixed_commission_centsinteger
Comissão fixa por pedido em centavos.
products_limitinteger
Máximo de produtos. 0 = ilimitado.
revenue_limit_centsinteger
Teto de faturamento em centavos. 0 = ilimitado.
vendor_storeboolean
Permite loja/página própria do seller.
categoriesstring
Ids de categorias permitidas, separados por vírgula. Vazio = todas.
include_shippingboolean
O frete entra na base da comissão.
include_taxesboolean
Os impostos entram na base da comissão.
price_on_requestboolean
Plano sob consulta: esconde o preço fixo.
ministore_*mixed
Recursos da mini-loja de WhatsApp, todos opcionais: ministore_enabled, ministore_whatsapp_payment, ministore_pix_auto, ministore_search_text|audio|image|list_ai, ministore_dashboard_simple|metrics|custom, ministore_cart_recovery, ministore_crm, ministore_human_transfer, ministore_integrations (booleanos), ministore_orders_included (inteiro, 0 = ilimitado), ministore_excess_per_order_cents (centavos) e ministore_excess_percentage_bps (pontos-base).
descriptionsarray
Nome e descrição por idioma: plan_id, lang_code, name, description.
vendors_countinteger
Sellers no plano.
created_atstring
Criação.
updated_atstring
Última alteração.

Erros

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_vendors nem view_vendors.{"error":"insufficient privileges","privilege_required_any":["manage_vendors","view_vendors"]}
403O módulo vendor-plans está desligado na loja.{"error":"module_disabled","module":"vendor-plans"}
Descrições podem vir nulas

Um plano sem textos cadastrados devolve "descriptions": null.

Consultar um plano

GET/api/v1/admin/vendor-plans/{id}Admin

Consulta um plano

Parâmetros de caminho

idintegerobrigatório
Id numérico do plano.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/vendor-plans/8" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Plano
json
{
  "id": 8,
  "status": "A",
  "position": 0,
  "is_default": false,
  "price_cents": 9900,
  "periodicity": "month",
  "commission_bps": 700,
  "fixed_commission_cents": 0,
  "products_limit": 6000,
  "revenue_limit_cents": 0,
  "vendor_store": false,
  "categories": "",
  "include_shipping": false,
  "include_taxes": false,
  "price_on_request": false,
  "ministore_enabled": false,
  "ministore_whatsapp_payment": false,
  "ministore_pix_auto": false,
  "ministore_search_text": false,
  "ministore_search_audio": false,
  "ministore_search_image": false,
  "ministore_search_list_ai": false,
  "ministore_dashboard_simple": false,
  "ministore_dashboard_metrics": false,
  "ministore_dashboard_custom": false,
  "ministore_cart_recovery": false,
  "ministore_crm": false,
  "ministore_human_transfer": false,
  "ministore_integrations": false,
  "ministore_orders_included": 0,
  "ministore_excess_per_order_cents": 0,
  "ministore_excess_percentage_bps": 0,
  "created_at": "2026-07-11T19:45:31Z",
  "updated_at": "2026-09-10T13:29:00Z",
  "descriptions": [
    {
      "plan_id": 8,
      "lang_code": "pt-BR",
      "name": "Pro",
      "description": "Plano para sellers em crescimento"
    }
  ],
  "vendors_count": 1
}

Campos da resposta

idinteger
Id do plano.
statusstring
AHD
A ativo, H oculto, D desativado.
positioninteger
Ordem de exibição.
is_defaultboolean
Plano padrão dos sellers novos.
price_centsinteger
Preço por período em centavos.
periodicitystring
monthyearonetime
month, year ou onetime.
commission_bpsinteger
Comissão percentual em pontos-base.
fixed_commission_centsinteger
Comissão fixa por pedido em centavos.
products_limitinteger
Máximo de produtos. 0 = ilimitado.
revenue_limit_centsinteger
Teto de faturamento em centavos. 0 = ilimitado.
vendor_storeboolean
Permite loja/página própria do seller.
categoriesstring
Ids de categorias permitidas, separados por vírgula. Vazio = todas.
include_shippingboolean
O frete entra na base da comissão.
include_taxesboolean
Os impostos entram na base da comissão.
price_on_requestboolean
Plano sob consulta: esconde o preço fixo.
ministore_*mixed
Recursos da mini-loja de WhatsApp, todos opcionais: ministore_enabled, ministore_whatsapp_payment, ministore_pix_auto, ministore_search_text|audio|image|list_ai, ministore_dashboard_simple|metrics|custom, ministore_cart_recovery, ministore_crm, ministore_human_transfer, ministore_integrations (booleanos), ministore_orders_included (inteiro, 0 = ilimitado), ministore_excess_per_order_cents (centavos) e ministore_excess_percentage_bps (pontos-base).
descriptionsarray
Nome e descrição por idioma: plan_id, lang_code, name, description.
vendors_countinteger
Sellers no plano.
created_atstring
Criação.
updated_atstring
Última alteração.

Erros

StatusQuandoCorpo de exemplo
400id não numérico.{"error":"invalid plan ID"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_vendors nem view_vendors.{"error":"insufficient privileges","privilege_required_any":["manage_vendors","view_vendors"]}
403O módulo vendor-plans está desligado na loja.{"error":"module_disabled","module":"vendor-plans"}
404Plano inexistente.{"error":"plan not found"}

Criar um plano

POST/api/v1/admin/vendor-plansAdmin

Cria um plano

Corpo da requisição

statusstringpadrão: A
AHD
A (padrão), H ou D.
positioninteger
Ordem de exibição.
is_defaultboolean
Torna este o plano padrão e tira a marca dos outros.
price_centsinteger
Preço em centavos.
periodicitystringpadrão: month
monthyearonetime
month (padrão), year ou onetime.
commission_bpsinteger
Comissão em pontos-base.
fixed_commission_centsinteger
Comissão fixa por pedido, em centavos.
products_limitinteger
0 = ilimitado.
revenue_limit_centsinteger
0 = ilimitado.
vendor_storeboolean
Loja própria.
categoriesstring
Ids de categorias separados por vírgula.
include_shippingboolean
Frete na base.
include_taxesboolean
Impostos na base.
price_on_requestboolean
Sob consulta.
ministore_*mixed
Os mesmos recursos ministore_* da resposta.
descriptionsarray

Nome e descrição por idioma. Cada item: lang_code (pt-BR, en...), name, description.

lang_codestringobrigatório
Idioma.
namestringobrigatório
Nome do plano.
descriptionstring
Descrição.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/vendor-plans" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "A",
    "price_cents": 9900,
    "periodicity": "month",
    "commission_bps": 700,
    "products_limit": 6000,
    "descriptions": [
      {
        "lang_code": "pt-BR",
        "name": "Pro",
        "description": "Plano para sellers em crescimento"
      }
    ]
  }'

Resposta

201Plano criado
json
{
  "id": 8,
  "status": "A",
  "position": 0,
  "is_default": false,
  "price_cents": 9900,
  "periodicity": "month",
  "commission_bps": 700,
  "fixed_commission_cents": 0,
  "products_limit": 6000,
  "revenue_limit_cents": 0,
  "vendor_store": false,
  "categories": "",
  "include_shipping": false,
  "include_taxes": false,
  "price_on_request": false,
  "ministore_enabled": false,
  "ministore_whatsapp_payment": false,
  "ministore_pix_auto": false,
  "ministore_search_text": false,
  "ministore_search_audio": false,
  "ministore_search_image": false,
  "ministore_search_list_ai": false,
  "ministore_dashboard_simple": false,
  "ministore_dashboard_metrics": false,
  "ministore_dashboard_custom": false,
  "ministore_cart_recovery": false,
  "ministore_crm": false,
  "ministore_human_transfer": false,
  "ministore_integrations": false,
  "ministore_orders_included": 0,
  "ministore_excess_per_order_cents": 0,
  "ministore_excess_percentage_bps": 0,
  "created_at": "2026-07-11T19:45:31Z",
  "updated_at": "2026-09-10T13:29:00Z",
  "descriptions": [
    {
      "plan_id": 8,
      "lang_code": "pt-BR",
      "name": "Pro",
      "description": "Plano para sellers em crescimento"
    }
  ],
  "vendors_count": 1
}

Campos da resposta

idinteger
Id do plano.
statusstring
AHD
A ativo, H oculto, D desativado.
positioninteger
Ordem de exibição.
is_defaultboolean
Plano padrão dos sellers novos.
price_centsinteger
Preço por período em centavos.
periodicitystring
monthyearonetime
month, year ou onetime.
commission_bpsinteger
Comissão percentual em pontos-base.
fixed_commission_centsinteger
Comissão fixa por pedido em centavos.
products_limitinteger
Máximo de produtos. 0 = ilimitado.
revenue_limit_centsinteger
Teto de faturamento em centavos. 0 = ilimitado.
vendor_storeboolean
Permite loja/página própria do seller.
categoriesstring
Ids de categorias permitidas, separados por vírgula. Vazio = todas.
include_shippingboolean
O frete entra na base da comissão.
include_taxesboolean
Os impostos entram na base da comissão.
price_on_requestboolean
Plano sob consulta: esconde o preço fixo.
ministore_*mixed
Recursos da mini-loja de WhatsApp, todos opcionais: ministore_enabled, ministore_whatsapp_payment, ministore_pix_auto, ministore_search_text|audio|image|list_ai, ministore_dashboard_simple|metrics|custom, ministore_cart_recovery, ministore_crm, ministore_human_transfer, ministore_integrations (booleanos), ministore_orders_included (inteiro, 0 = ilimitado), ministore_excess_per_order_cents (centavos) e ministore_excess_percentage_bps (pontos-base).
descriptionsarray
Nome e descrição por idioma: plan_id, lang_code, name, description.
vendors_countinteger
Sellers no plano.
created_atstring
Criação.
updated_atstring
Última alteração.

Erros

StatusQuandoCorpo de exemplo
400Corpo inválido, status fora de A/H/D ou periodicity inválida.{"error":"failed to create plan","detail":"invalid status: X (must be A, H, or D)"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem o privilégio manage_vendors.{"error":"insufficient privileges","required":"manage_vendors"}
403O módulo vendor-plans está desligado na loja.{"error":"module_disabled","module":"vendor-plans"}

Alterar um plano

Atualização parcial: só os campos enviados mudam. Enviar descriptions grava os textos dos idiomas informados.

PUT/api/v1/admin/vendor-plans/{id}Admin

Altera um plano

Parâmetros de caminho

idintegerobrigatório
Id numérico do plano.

Corpo da requisição

statusstringpadrão: A
AHD
A (padrão), H ou D.
positioninteger
Ordem de exibição.
is_defaultboolean
Torna este o plano padrão e tira a marca dos outros.
price_centsinteger
Preço em centavos.
periodicitystringpadrão: month
monthyearonetime
month (padrão), year ou onetime.
commission_bpsinteger
Comissão em pontos-base.
fixed_commission_centsinteger
Comissão fixa por pedido, em centavos.
products_limitinteger
0 = ilimitado.
revenue_limit_centsinteger
0 = ilimitado.
vendor_storeboolean
Loja própria.
categoriesstring
Ids de categorias separados por vírgula.
include_shippingboolean
Frete na base.
include_taxesboolean
Impostos na base.
price_on_requestboolean
Sob consulta.
ministore_*mixed
Os mesmos recursos ministore_* da resposta.
descriptionsarray

Nome e descrição por idioma. Cada item: lang_code (pt-BR, en...), name, description.

lang_codestringobrigatório
Idioma.
namestringobrigatório
Nome do plano.
descriptionstring
Descrição.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/vendor-plans/8" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "price_cents": 10900,
    "commission_bps": 650
  }'

Resposta

200Plano alterado
json
{
  "id": 8,
  "status": "A",
  "position": 0,
  "is_default": false,
  "price_cents": 10900,
  "periodicity": "month",
  "commission_bps": 650,
  "fixed_commission_cents": 0,
  "products_limit": 6000,
  "revenue_limit_cents": 0,
  "vendor_store": false,
  "categories": "",
  "include_shipping": false,
  "include_taxes": false,
  "price_on_request": false,
  "ministore_enabled": false,
  "ministore_whatsapp_payment": false,
  "ministore_pix_auto": false,
  "ministore_search_text": false,
  "ministore_search_audio": false,
  "ministore_search_image": false,
  "ministore_search_list_ai": false,
  "ministore_dashboard_simple": false,
  "ministore_dashboard_metrics": false,
  "ministore_dashboard_custom": false,
  "ministore_cart_recovery": false,
  "ministore_crm": false,
  "ministore_human_transfer": false,
  "ministore_integrations": false,
  "ministore_orders_included": 0,
  "ministore_excess_per_order_cents": 0,
  "ministore_excess_percentage_bps": 0,
  "created_at": "2026-07-11T19:45:31Z",
  "updated_at": "2026-09-10T13:29:00Z",
  "descriptions": [
    {
      "plan_id": 8,
      "lang_code": "pt-BR",
      "name": "Pro",
      "description": "Plano para sellers em crescimento"
    }
  ],
  "vendors_count": 1
}

Campos da resposta

idinteger
Id do plano.
statusstring
AHD
A ativo, H oculto, D desativado.
positioninteger
Ordem de exibição.
is_defaultboolean
Plano padrão dos sellers novos.
price_centsinteger
Preço por período em centavos.
periodicitystring
monthyearonetime
month, year ou onetime.
commission_bpsinteger
Comissão percentual em pontos-base.
fixed_commission_centsinteger
Comissão fixa por pedido em centavos.
products_limitinteger
Máximo de produtos. 0 = ilimitado.
revenue_limit_centsinteger
Teto de faturamento em centavos. 0 = ilimitado.
vendor_storeboolean
Permite loja/página própria do seller.
categoriesstring
Ids de categorias permitidas, separados por vírgula. Vazio = todas.
include_shippingboolean
O frete entra na base da comissão.
include_taxesboolean
Os impostos entram na base da comissão.
price_on_requestboolean
Plano sob consulta: esconde o preço fixo.
ministore_*mixed
Recursos da mini-loja de WhatsApp, todos opcionais: ministore_enabled, ministore_whatsapp_payment, ministore_pix_auto, ministore_search_text|audio|image|list_ai, ministore_dashboard_simple|metrics|custom, ministore_cart_recovery, ministore_crm, ministore_human_transfer, ministore_integrations (booleanos), ministore_orders_included (inteiro, 0 = ilimitado), ministore_excess_per_order_cents (centavos) e ministore_excess_percentage_bps (pontos-base).
descriptionsarray
Nome e descrição por idioma: plan_id, lang_code, name, description.
vendors_countinteger
Sellers no plano.
created_atstring
Criação.
updated_atstring
Última alteração.

Erros

StatusQuandoCorpo de exemplo
400id inválido, corpo inválido, status/periodicity inválidos ou tentativa de desativar plano com sellers.{"error":"failed to update plan","detail":"cannot disable plan with 3 active vendors"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem o privilégio manage_vendors.{"error":"insufficient privileges","required":"manage_vendors"}
403O módulo vendor-plans está desligado na loja.{"error":"module_disabled","module":"vendor-plans"}
404Plano inexistente.{"error":"plan not found"}

Apagar um plano

DELETE/api/v1/admin/vendor-plans/{id}Admin

Apaga um plano

Parâmetros de caminho

idintegerobrigatório
Id numérico do plano.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/vendor-plans/8" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Apagado
json
{
  "status": "deleted"
}

Erros

StatusQuandoCorpo de exemplo
400id não numérico.{"error":"invalid plan ID"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem o privilégio manage_vendors.{"error":"insufficient privileges","required":"manage_vendors"}
403O módulo vendor-plans está desligado na loja.{"error":"module_disabled","module":"vendor-plans"}
409Há sellers usando o plano.{"error":"cannot delete plan","detail":"cannot delete plan: 1 vendors are using it"}

Veja também

  • Planos de seller
Anterior
Planos de seller
Próxima
Assinantes e atribuição
Nesta página
  • Listar planos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar um plano
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar um plano
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar um plano
  • Exemplo de requisição
  • Resposta
  • Erros
  • Apagar um plano
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também