API atual/Referência completa/Plano e documentos

Plano do seller

Consulta o plano atual do seller com seu uso e troca de plano respeitando os limites.

Consultar o plano atual

Devolve o plano do seller e o quanto dos limites ele já usa. Exige o módulo vendor-plans ligado.

GET/api/v1/vendor/planSeller

Consultar o plano atual

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/plan" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Plano e uso

json

{
  "plan": {
    "id": 8,
    "status": "A",
    "position": 0,
    "is_default": false,
    "price_cents": 0,
    "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:31.455028Z",
    "updated_at": "2026-09-10T13:29:00.462474Z",
    "descriptions": [
      {
        "plan_id": 8,
        "lang_code": "pt-BR",
        "name": "Plano Pro",
        "description": "Até 6.000 produtos"
      }
    ],
    "vendors_count": 1
  },
  "product_count": 4987,
  "revenue_cents": 2737616362
}

Campos da resposta

planobject|null

O plano. null se o seller não tem plano.

idinteger

Id do plano (inteiro, não UUID).

statusstring

AHD

A ativo, H oculto, D desativado.

positioninteger

Ordem de exibição.

is_defaultboolean

Plano padrão para novos sellers.

price_centsinteger

Preço por período, em centavos.

periodicitystring

monthyearonetime

Período da cobrança.

commission_bpsinteger

Comissão percentual em pontos-base (700 = 7%).

fixed_commission_centsinteger

Comissão fixa por pedido, em centavos.

products_limitinteger

Máximo de produtos. 0 = sem limite.

revenue_limit_centsinteger

Teto de receita acumulada, em centavos. 0 = sem limite.

vendor_storeboolean

Se o plano dá página de loja própria.

categoriesstring

Categorias permitidas, ids separados por vírgula. Vazio = todas.

include_shippingboolean

Frete entra na base da comissão.

include_taxesboolean

Impostos entram na base da comissão.

price_on_requestboolean

Preço sob consulta (esconde price_cents).

ministore_*mixed

Recursos da mini-loja do plano. Booleanos: ministore_enabled, ministore_whatsapp_payment, ministore_pix_auto, ministore_search_text, ministore_search_audio, ministore_search_image, ministore_search_list_ai, ministore_dashboard_simple, ministore_dashboard_metrics, ministore_dashboard_custom, ministore_cart_recovery, ministore_crm, ministore_human_transfer, ministore_integrations. Números: ministore_orders_included (0 = sem limite), ministore_excess_per_order_cents e ministore_excess_percentage_bps (cobrança sobre pedidos acima do incluído).

descriptionsobject[]

Nome e descrição por idioma: plan_id, lang_code, name, description. Pode vir null.

vendors_countinteger

Quantos sellers estão neste plano.

created_atstring

Criação, RFC 3339 em UTC.

updated_atstring

Última alteração, RFC 3339 em UTC.

product_countinteger

Produtos do seller que não foram apagados.

revenue_centsinteger

Receita acumulada de todos os pedidos, exceto cancelados, reembolsados, recusados e estornados, em centavos. É o número comparado com revenue_limit_cents.

Erros

Status	Quando	Corpo de exemplo
404	O usuário não está vinculado a nenhum seller.	`{"error":"vendor not found"}`
403	O módulo `vendor-plans` está desligado nesta loja.	`{"error":"module_disabled","module":"vendor-plans"}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`

Trocar de plano

Troca o plano do seller imediatamente, se ele cumpre os limites do plano novo. Planos desativados (D) não podem ser escolhidos; os ocultos (H) podem.

PUT/api/v1/vendor/planSeller

Trocar de plano

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Content-Typestringobrigatório

application/json.

Corpo da requisição

plan_idintegerobrigatório

Id do plano de destino (inteiro).

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/plan" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan_id": 8}'

Resposta

200Plano trocado

json

{
  "plan_id": 8,
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "current_products": 4987,
  "products_limit": 6000,
  "products_ok": true,
  "current_revenue_cents": 2737616362,
  "revenue_limit_cents": 0,
  "revenue_ok": true,
  "available": true
}

409Limites excedidos, nada mudou

json

{
  "plan_id": 3,
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "current_products": 4987,
  "products_limit": 1000,
  "products_ok": false,
  "current_revenue_cents": 2737616362,
  "revenue_limit_cents": 0,
  "revenue_ok": true,
  "available": false,
  "errors": [
    "vendor has 4987 products but plan allows 1000"
  ]
}

Campos da resposta

plan_idinteger

Plano avaliado.

vendor_iduuid

Seller.

current_productsinteger

Produtos atuais do seller.

products_limitinteger

Limite de produtos do plano (0 = sem limite).

products_okboolean

Se o limite de produtos é cumprido.

current_revenue_centsinteger

Receita acumulada atual, em centavos.

revenue_limit_centsinteger

Limite de receita do plano (0 = sem limite).

revenue_okboolean

Se o limite de receita é cumprido.

availableboolean

true se a troca foi feita. No 409 vem false.

errorsstring[]

Só quando algo excede: explica o quê, em inglês.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON, `plan_id` ausente ou menor que 1, plano inexistente ou desativado.	`{"error":"plan_id is required"}`
409	O seller excede os limites do plano de destino.	`{"plan_id":3,"available":false,"errors":["..."]}`
404	O usuário não está vinculado a nenhum seller.	`{"error":"vendor not found"}`
403	O módulo `vendor-plans` está desligado nesta loja.	`{"error":"module_disabled","module":"vendor-plans"}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`

Veja também

API atual/Referência completa/Plano e documentos

Plano do seller

Consulta o plano atual do seller com seu uso e troca de plano respeitando os limites.

Consultar o plano atual

Devolve o plano do seller e o quanto dos limites ele já usa. Exige o módulo vendor-plans ligado.

GET/api/v1/vendor/planSeller

Consultar o plano atual

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/plan" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Plano e uso

json

{
  "plan": {
    "id": 8,
    "status": "A",
    "position": 0,
    "is_default": false,
    "price_cents": 0,
    "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:31.455028Z",
    "updated_at": "2026-09-10T13:29:00.462474Z",
    "descriptions": [
      {
        "plan_id": 8,
        "lang_code": "pt-BR",
        "name": "Plano Pro",
        "description": "Até 6.000 produtos"
      }
    ],
    "vendors_count": 1
  },
  "product_count": 4987,
  "revenue_cents": 2737616362
}

Campos da resposta

planobject|null

O plano. null se o seller não tem plano.

idinteger

Id do plano (inteiro, não UUID).

statusstring

AHD

A ativo, H oculto, D desativado.

positioninteger

Ordem de exibição.

is_defaultboolean

Plano padrão para novos sellers.

price_centsinteger

Preço por período, em centavos.

periodicitystring

monthyearonetime

Período da cobrança.

commission_bpsinteger

Comissão percentual em pontos-base (700 = 7%).

fixed_commission_centsinteger

Comissão fixa por pedido, em centavos.

products_limitinteger

Máximo de produtos. 0 = sem limite.

revenue_limit_centsinteger

Teto de receita acumulada, em centavos. 0 = sem limite.

vendor_storeboolean

Se o plano dá página de loja própria.

categoriesstring

Categorias permitidas, ids separados por vírgula. Vazio = todas.

include_shippingboolean

Frete entra na base da comissão.

include_taxesboolean

Impostos entram na base da comissão.

price_on_requestboolean

Preço sob consulta (esconde price_cents).

ministore_*mixed

descriptionsobject[]

Nome e descrição por idioma: plan_id, lang_code, name, description. Pode vir null.

vendors_countinteger

Quantos sellers estão neste plano.

created_atstring

Criação, RFC 3339 em UTC.

updated_atstring

Última alteração, RFC 3339 em UTC.

product_countinteger

Produtos do seller que não foram apagados.

revenue_centsinteger

Receita acumulada de todos os pedidos, exceto cancelados, reembolsados, recusados e estornados, em centavos. É o número comparado com revenue_limit_cents.

Erros

Status	Quando	Corpo de exemplo
404	O usuário não está vinculado a nenhum seller.	`{"error":"vendor not found"}`
403	O módulo `vendor-plans` está desligado nesta loja.	`{"error":"module_disabled","module":"vendor-plans"}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`

Trocar de plano

Troca o plano do seller imediatamente, se ele cumpre os limites do plano novo. Planos desativados (D) não podem ser escolhidos; os ocultos (H) podem.

PUT/api/v1/vendor/planSeller

Trocar de plano

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Content-Typestringobrigatório

application/json.

Corpo da requisição

plan_idintegerobrigatório

Id do plano de destino (inteiro).

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/plan" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan_id": 8}'

Resposta

200Plano trocado

json

{
  "plan_id": 8,
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "current_products": 4987,
  "products_limit": 6000,
  "products_ok": true,
  "current_revenue_cents": 2737616362,
  "revenue_limit_cents": 0,
  "revenue_ok": true,
  "available": true
}

409Limites excedidos, nada mudou

json

{
  "plan_id": 3,
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "current_products": 4987,
  "products_limit": 1000,
  "products_ok": false,
  "current_revenue_cents": 2737616362,
  "revenue_limit_cents": 0,
  "revenue_ok": true,
  "available": false,
  "errors": [
    "vendor has 4987 products but plan allows 1000"
  ]
}

Campos da resposta

plan_idinteger

Plano avaliado.

vendor_iduuid

Seller.

current_productsinteger

Produtos atuais do seller.

products_limitinteger

Limite de produtos do plano (0 = sem limite).

products_okboolean

Se o limite de produtos é cumprido.

current_revenue_centsinteger

Receita acumulada atual, em centavos.

revenue_limit_centsinteger

Limite de receita do plano (0 = sem limite).

revenue_okboolean

Se o limite de receita é cumprido.

availableboolean

true se a troca foi feita. No 409 vem false.

errorsstring[]

Só quando algo excede: explica o quê, em inglês.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON, `plan_id` ausente ou menor que 1, plano inexistente ou desativado.	`{"error":"plan_id is required"}`
409	O seller excede os limites do plano de destino.	`{"plan_id":3,"available":false,"errors":["..."]}`
404	O usuário não está vinculado a nenhum seller.	`{"error":"vendor not found"}`
403	O módulo `vendor-plans` está desligado nesta loja.	`{"error":"module_disabled","module":"vendor-plans"}`
401	Token ausente, inválido, expirado ou revogado.	`invalid or expired token`
403	O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.	`{"error":"vendor_pending_review"}`