Sellers

Lista, lê, cadastra e altera sellers (lojistas) do marketplace, com a comissão e o modelo de pagamento de cada um.

Um seller (lojista) é uma empresa que vende dentro do marketplace da loja. Cada seller tem seus produtos, seus pedidos (sub-pedidos), sua comissão (percentual que a loja retém de cada venda), seu modelo de pagamento e sua situação. Use estas operações para sincronizar o cadastro de lojistas com um ERP ou com o CRM da operação.

Todo cadastro novo entra com a situação P (pendente) e a comissão padrão da plataforma. A aprovação, a suspensão e a troca de comissão são feitas depois, com a alteração (PUT) ou no painel.

GET/api/v2/vendorsAdmin

Listar sellers

Lista os sellers não excluídos, com os campos de administração (e-mail, comissão, modelo de pagamento).

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100.

sortstringpadrão: created_at

created_atcompany_nameemailcommission_rateproduct_count

Campo de ordenação. Outro valor cai em created_at.

orderstringpadrão: desc

ascdesc

Direção da ordenação.

statusstring

APDRactivependingsuspendedrejected

Situação, por letra ou por nome. Sem resultado, data volta null.

searchstring

Texto contido no nome fantasia ou no e-mail.

citystring

Texto contido na cidade.

statestring

UF exata (SP).

created_fromstring

Cadastrados a partir desta data (YYYY-MM-DD). Data inválida é ignorada.

created_tostring

Cadastrados até o fim deste dia (YYYY-MM-DD).

fieldsstring

Chaves a devolver em cada item, separadas por vírgula.

GET/api/v2/vendors/{id}Admin

Ler um seller

Devolve o seller com todos os campos de cadastro. Só aceita o UUID; o slug público não vale aqui.

Parâmetros de caminho

iduuidobrigatório

Id do seller.

POST/api/v2/vendorsAdmin

Cadastrar um seller

Cria o seller na situação P (pendente). Se slug vier vazio, é gerado a partir do nome; se já existir, a plataforma acrescenta um sufixo (loja-exemplo-2). O corpo aceita muitos campos de cadastro; os principais estão abaixo. Também são aceitos address_line2, os campos do representante legal (rep_full_name, rep_cpf, rep_birth_date, rep_email, rep_phone, rep_mother_name) e descriptions (uma descrição por idioma).

Corpo da requisição

company_namestringobrigatório

Nome fantasia, mostrado na vitrine.

emailstringobrigatório

E-mail do seller. Precisa ser válido e único na loja.

slugstring

Parte do endereço público do seller. Letras minúsculas, números e hífen. Termos reservados são recusados.

user_iduuid

Usuário que será o dono da conta do seller. Opcional: o cadastro pode existir sem usuário.

cnpjstring

CNPJ, com ou sem pontuação. Validado e único na loja.

legal_namestring

Razão social.

state_regstring

Inscrição estadual.

cnae_codestring

Código CNAE. Se a loja restringe os CNAEs aceitos, um código fora da lista é recusado.

tax_regimestring

meisimples_nacionallucro_presumidolucro_reallucro_arbitrado

Regime tributário.

phonestring

Telefone fixo.

mobile_phonestring

Celular.

websitestring

Site do seller.

descriptionstring

Descrição pública.

address_line1string

Logradouro.

address_numberstring

Número.

address_complementstring

Complemento.

address_districtstring

Bairro.

citystring

Cidade.

statestring

UF.

postal_codestring

CEP.

countrystringpadrão: BR

País.

PUT/api/v2/vendors/{id}Admin

Alterar um seller

Alteração parcial: só os campos enviados mudam. Além dos campos do cadastro acima, aceita os de administração abaixo e outros que o painel edita, como legal_name, state_reg, cnae_code, address_line2, latitude, longitude, bank_name, bank_account_type, bank_account_holder, banner_url e os avisos por e-mail email_new_order, email_order_status, email_low_stock e email_payout.

Parâmetros de caminho

iduuidobrigatório

Id do seller.

Corpo da requisição

statusstring

APDRactivependingsuspendedrejected

Situação: aprovar (A), suspender (D) ou recusar (R).

commission_ratenumber

Comissão em percentual (10 = 10%). De 0 a 100.

commission_typestring

percentage

Tipo da comissão.

payment_modelstring

marketplace_collectsdirect_to_vendor

Quem recebe o pagamento do cliente: a loja (e repassa ao seller) ou o próprio seller.

fulfillment_typestring

vendor_fulfilledmarketplace_fulfilled

Quem despacha o pedido: o seller ou a loja.

products_require_approvalboolean

Se produtos novos do seller passam por aprovação antes de aparecer.

company_namestring

Novo nome fantasia.

emailstring

Novo e-mail (válido e único).

slugstring

Novo slug.

cnpjstring

Novo CNPJ.

logo_urlstring

Logotipo do seller.

pix_keystring

Chave PIX para repasse.

bank_codestring

Código do banco (3 dígitos) para repasse.

bank_agencystring

Agência bancária.

bank_accountstring

Conta bancária.

Exemplo de requisição

bash

curl "$BASE_URL/api/v2/vendors?status=A&sort=company_name&order=asc&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Cadastrar e depois aprovar:

bash

curl -X POST "$BASE_URL/api/v2/vendors" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "company_name": "Loja Exemplo",
  "email": "contato@lojaexemplo.com.br",
  "cnpj": "11.222.333/0001-81",
  "tax_regime": "simples_nacional",
  "city": "São Paulo",
  "state": "SP",
  "postal_code": "01310-100"
}'

bash

curl -X PUT "$BASE_URL/api/v2/vendors/9d9d9d56-eb43-4719-889d-055632f7c7da" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "A",
  "commission_rate": 12.5
}'

Resposta

200Sellers retornados

json

{
  "data": [
    {
      "id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "display_id": 274,
      "user_id": "a1a25b87-5e32-4439-b3df-f98eb03b6434",
      "company_name": "Loja Exemplo",
      "slug": "loja-exemplo",
      "status": "A",
      "email": "contato@lojaexemplo.com.br",
      "commission_rate": 10,
      "commission_type": "percentage",
      "payment_model": "marketplace_collects",
      "fulfillment_type": "vendor_fulfilled",
      "product_count": 1,
      "is_system": false,
      "created_at": "2026-09-15T14:20:06.269342Z",
      "updated_at": "2026-09-15T19:00:17.894213Z"
    }
  ],
  "meta": { "pagination": { "page": 1, "per_page": 20, "total": 12, "total_pages": 1 } }
}

200Seller lido

json

{
  "data": {
    "id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
    "display_id": 274,
    "user_id": "a1a25b87-5e32-4439-b3df-f98eb03b6434",
    "company_name": "Loja Exemplo",
    "slug": "loja-exemplo",
    "status": "A",
    "ignore_email": "",
    "email": "contato@lojaexemplo.com.br",
    "country": "BR",
    "commission_rate": 10,
    "commission_type": "percentage",
    "payment_model": "marketplace_collects",
    "fulfillment_type": "vendor_fulfilled",
    "marketplace_shipping_fee_bps": 0,
    "payout_method": "pix",
    "terms_accepted": false,
    "products_require_approval": true,
    "email_new_order": true,
    "email_order_status": true,
    "email_low_stock": true,
    "email_payout": true,
    "is_on_vacation": false,
    "debt_balance": 0,
    "created_at": "2026-09-15T14:20:06.269342Z",
    "updated_at": "2026-09-15T19:00:17.894213Z"
  }
}

Campos da resposta

iduuid

Id do seller.

display_idinteger

Número amigável usado no painel.

user_iduuid | null

Usuário dono da conta.

company_namestring

Nome fantasia.

slugstring

Parte do endereço público.

statusstring

APDR

Situação: A ativo, P pendente, D suspenso, R recusado.

emailstring

E-mail de contato.

commission_ratenumber

Comissão retida pela loja, em percentual.

commission_typestring

Sempre percentage.

payment_modelstring

marketplace_collectsdirect_to_vendor

Quem recebe o pagamento do cliente.

fulfillment_typestring

vendor_fulfilledmarketplace_fulfilled

Quem despacha o pedido.

product_countinteger

Quantidade de produtos do seller. Só na lista.

is_systemboolean

Verdadeiro para o seller interno da própria loja. Só na lista.

debt_balanceinteger

Saldo devedor com a loja, em centavos. Só na leitura por id.

created_atstring

Cadastro (RFC 3339, UTC).

updated_atstring

Última alteração (RFC 3339, UTC).

O seller completo traz ainda os campos de cadastro enviados (CNPJ, razão social, endereço, contatos), de repasse (banco, PIX), de notificação (email_*) e de férias (is_on_vacation, vacation_message, vacation_until). Campos sem valor são omitidos. A criação responde 201 com o seller e a alteração responde 200.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":{"code":"bad_request","message":"invalid request body","details":"..."}}`
400	CNPJ inválido	`{"error":{"code":"vendor_cnpj_invalid","message":"vendor_cnpj_invalid: ..."}}`
400	Regime tributário inválido	`{"error":{"code":"vendor_tax_regime_invalid","message":"..."}}`
400	E-mail, slug ou comissão fora da regra	`{"error":{"code":"bad_request","message":"..."}}`
404	Seller inexistente	`{"error":{"code":"not_found","message":"vendor not found"}}`
409	CNPJ já usado por outro seller	`{"error":{"code":"vendor_cnpj_in_use","message":"..."}}`
409	E-mail ou slug já usado	`{"error":{"code":"conflict","message":"..."}}`
500	`company_name` ou `email` ausentes na criação	`{"error":{"code":"internal_error","message":"an unexpected error occurred","details":"company_name and email are required"}}`

Veja também

Sellers

Lista, lê, cadastra e altera sellers (lojistas) do marketplace, com a comissão e o modelo de pagamento de cada um.

GET/api/v2/vendorsAdmin

Listar sellers

Lista os sellers não excluídos, com os campos de administração (e-mail, comissão, modelo de pagamento).

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100.

sortstringpadrão: created_at

created_atcompany_nameemailcommission_rateproduct_count

Campo de ordenação. Outro valor cai em created_at.

orderstringpadrão: desc

ascdesc

Direção da ordenação.

statusstring

APDRactivependingsuspendedrejected

Situação, por letra ou por nome. Sem resultado, data volta null.

searchstring

Texto contido no nome fantasia ou no e-mail.

citystring

Texto contido na cidade.

statestring

UF exata (SP).

created_fromstring

Cadastrados a partir desta data (YYYY-MM-DD). Data inválida é ignorada.

created_tostring

Cadastrados até o fim deste dia (YYYY-MM-DD).

fieldsstring

Chaves a devolver em cada item, separadas por vírgula.

GET/api/v2/vendors/{id}Admin

Ler um seller

Devolve o seller com todos os campos de cadastro. Só aceita o UUID; o slug público não vale aqui.

Parâmetros de caminho

iduuidobrigatório

Id do seller.

POST/api/v2/vendorsAdmin

Cadastrar um seller

Corpo da requisição

company_namestringobrigatório

Nome fantasia, mostrado na vitrine.

emailstringobrigatório

E-mail do seller. Precisa ser válido e único na loja.

slugstring

Parte do endereço público do seller. Letras minúsculas, números e hífen. Termos reservados são recusados.

user_iduuid

Usuário que será o dono da conta do seller. Opcional: o cadastro pode existir sem usuário.

cnpjstring

CNPJ, com ou sem pontuação. Validado e único na loja.

legal_namestring

Razão social.

state_regstring

Inscrição estadual.

cnae_codestring

Código CNAE. Se a loja restringe os CNAEs aceitos, um código fora da lista é recusado.

tax_regimestring

meisimples_nacionallucro_presumidolucro_reallucro_arbitrado

Regime tributário.

phonestring

Telefone fixo.

mobile_phonestring

Celular.

websitestring

Site do seller.

descriptionstring

Descrição pública.

address_line1string

Logradouro.

address_numberstring

Número.

address_complementstring

Complemento.

address_districtstring

Bairro.

citystring

Cidade.

statestring

UF.

postal_codestring

CEP.

countrystringpadrão: BR

País.

PUT/api/v2/vendors/{id}Admin

Alterar um seller

Parâmetros de caminho

iduuidobrigatório

Id do seller.

Corpo da requisição

statusstring

APDRactivependingsuspendedrejected

Situação: aprovar (A), suspender (D) ou recusar (R).

commission_ratenumber

Comissão em percentual (10 = 10%). De 0 a 100.

commission_typestring

percentage

Tipo da comissão.

payment_modelstring

marketplace_collectsdirect_to_vendor

Quem recebe o pagamento do cliente: a loja (e repassa ao seller) ou o próprio seller.

fulfillment_typestring

vendor_fulfilledmarketplace_fulfilled

Quem despacha o pedido: o seller ou a loja.

products_require_approvalboolean

Se produtos novos do seller passam por aprovação antes de aparecer.

company_namestring

Novo nome fantasia.

emailstring

Novo e-mail (válido e único).

slugstring

Novo slug.

cnpjstring

Novo CNPJ.

logo_urlstring

Logotipo do seller.

pix_keystring

Chave PIX para repasse.

bank_codestring

Código do banco (3 dígitos) para repasse.

bank_agencystring

Agência bancária.

bank_accountstring

Conta bancária.

Exemplo de requisição

bash

curl "$BASE_URL/api/v2/vendors?status=A&sort=company_name&order=asc&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Cadastrar e depois aprovar:

bash

curl -X POST "$BASE_URL/api/v2/vendors" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "company_name": "Loja Exemplo",
  "email": "contato@lojaexemplo.com.br",
  "cnpj": "11.222.333/0001-81",
  "tax_regime": "simples_nacional",
  "city": "São Paulo",
  "state": "SP",
  "postal_code": "01310-100"
}'

bash

curl -X PUT "$BASE_URL/api/v2/vendors/9d9d9d56-eb43-4719-889d-055632f7c7da" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "A",
  "commission_rate": 12.5
}'

Resposta

200Sellers retornados

json

{
  "data": [
    {
      "id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "display_id": 274,
      "user_id": "a1a25b87-5e32-4439-b3df-f98eb03b6434",
      "company_name": "Loja Exemplo",
      "slug": "loja-exemplo",
      "status": "A",
      "email": "contato@lojaexemplo.com.br",
      "commission_rate": 10,
      "commission_type": "percentage",
      "payment_model": "marketplace_collects",
      "fulfillment_type": "vendor_fulfilled",
      "product_count": 1,
      "is_system": false,
      "created_at": "2026-09-15T14:20:06.269342Z",
      "updated_at": "2026-09-15T19:00:17.894213Z"
    }
  ],
  "meta": { "pagination": { "page": 1, "per_page": 20, "total": 12, "total_pages": 1 } }
}

200Seller lido

json

{
  "data": {
    "id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
    "display_id": 274,
    "user_id": "a1a25b87-5e32-4439-b3df-f98eb03b6434",
    "company_name": "Loja Exemplo",
    "slug": "loja-exemplo",
    "status": "A",
    "ignore_email": "",
    "email": "contato@lojaexemplo.com.br",
    "country": "BR",
    "commission_rate": 10,
    "commission_type": "percentage",
    "payment_model": "marketplace_collects",
    "fulfillment_type": "vendor_fulfilled",
    "marketplace_shipping_fee_bps": 0,
    "payout_method": "pix",
    "terms_accepted": false,
    "products_require_approval": true,
    "email_new_order": true,
    "email_order_status": true,
    "email_low_stock": true,
    "email_payout": true,
    "is_on_vacation": false,
    "debt_balance": 0,
    "created_at": "2026-09-15T14:20:06.269342Z",
    "updated_at": "2026-09-15T19:00:17.894213Z"
  }
}

Campos da resposta

iduuid

Id do seller.

display_idinteger

Número amigável usado no painel.

user_iduuid | null

Usuário dono da conta.

company_namestring

Nome fantasia.

slugstring

Parte do endereço público.

statusstring

APDR

Situação: A ativo, P pendente, D suspenso, R recusado.

emailstring

E-mail de contato.

commission_ratenumber

Comissão retida pela loja, em percentual.

commission_typestring

Sempre percentage.

payment_modelstring

marketplace_collectsdirect_to_vendor

Quem recebe o pagamento do cliente.

fulfillment_typestring

vendor_fulfilledmarketplace_fulfilled

Quem despacha o pedido.

product_countinteger

Quantidade de produtos do seller. Só na lista.

is_systemboolean

Verdadeiro para o seller interno da própria loja. Só na lista.

debt_balanceinteger

Saldo devedor com a loja, em centavos. Só na leitura por id.

created_atstring

Cadastro (RFC 3339, UTC).

updated_atstring

Última alteração (RFC 3339, UTC).

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":{"code":"bad_request","message":"invalid request body","details":"..."}}`
400	CNPJ inválido	`{"error":{"code":"vendor_cnpj_invalid","message":"vendor_cnpj_invalid: ..."}}`
400	Regime tributário inválido	`{"error":{"code":"vendor_tax_regime_invalid","message":"..."}}`
400	E-mail, slug ou comissão fora da regra	`{"error":{"code":"bad_request","message":"..."}}`
404	Seller inexistente	`{"error":{"code":"not_found","message":"vendor not found"}}`
409	CNPJ já usado por outro seller	`{"error":{"code":"vendor_cnpj_in_use","message":"..."}}`
409	E-mail ou slug já usado	`{"error":{"code":"conflict","message":"..."}}`
500	`company_name` ou `email` ausentes na criação	`{"error":{"code":"internal_error","message":"an unexpected error occurred","details":"company_name and email are required"}}`