API legada/Referência completa/Lojas, vendors e companies

Criar loja

Cadastra um seller novo, pendente de aprovação, e devolve o id.

Cadastra um seller novo. Use quando o seller nasce em outro sistema (ERP, CRM, planilha de onboarding) e precisa existir na loja. A resposta traz só o store_id; o seller entra pendente (P) e só passa a vender depois de aprovado com Alterar loja.

Duas regras que surpreendem: o e-mail é obrigatório (a plataforma recusa o cadastro sem ele, mesmo que o contrato da 1.0 só cite o nome) e o campo address é ignorado na criação.

POST/api/v1.0/storesAdmin

Criar uma loja

Corpo da requisição

companystringobrigatório

Nome fantasia do seller. Obrigatório (ou company_name).

company_namestring

Sinônimo de company. Se os dois vierem, vale company_name.

emailstringobrigatório

E-mail do seller. Obrigatório, deve ser um e-mail válido e único entre sellers ativos (sem diferenciar maiúsculas).

storefrontstring

Endereço de vitrine, por exemplo modaaurora.venddor.com.br. Só a primeira parte, antes do primeiro ponto, vira o slug. Se o slug já existe, a plataforma acrescenta um sufixo (tech-brasil-2). Sem este campo o slug sai do nome da empresa (minúsculas, espaços viram hífen).

phonestring

Telefone.

urlstring

Site.

citystring

Cidade.

statestring

UF.

zipcodestring

CEP.

countrystringpadrão: BR

País, código ISO de 2 letras.

company_phonestring

Sinônimo de phone; vale este se os dois vierem. O mesmo vale para company_city, company_state, company_country, company_zipcode e company_website (sinônimo de url).

addressstring

Aceito, mas ignorado na criação. Grave o endereço com PUT depois.

statusstring

Aceito, mas ignorado na criação: o seller sempre nasce P.

POST/api/storesAdmin

Mesma operação, caminho alternativo

Mesmo comportamento, parâmetros e resposta de POST /api/v1.0/stores. Use este caminho se o seu cliente já foi escrito para ele. Na forma sem versão (/api/...) os ids saem como números decimais em string, mas os caminhos só aceitam o UUID (veja a home da seção).

POST/api/v1.0/vendorsAdmin

Mesma operação, caminho alternativo

Mesmo comportamento, parâmetros e resposta de POST /api/v1.0/stores. Use este caminho se o seu cliente já foi escrito para ele.

POST/api/vendorsAdmin

Mesma operação, caminho alternativo

POST/api/v1.0/companiesAdmin

Mesma operação, caminho alternativo

Mesmo comportamento, parâmetros e resposta de POST /api/v1.0/stores. Use este caminho se o seu cliente já foi escrito para ele.

POST/api/companiesAdmin

Mesma operação, caminho alternativo

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1.0/stores" \
  -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company": "Moda Aurora Ltda",
  "email": "contato@modaaurora.example",
  "phone": "(11) 98888-7777",
  "url": "https://modaaurora.example",
  "city": "São Paulo",
  "state": "SP",
  "zipcode": "01310-100",
  "country": "BR",
  "storefront": "modaaurora.venddor.com.br"
}'

Resposta

201Loja criada

json

{ "store_id": "3b617148-8a28-4d07-8040-a8903b4238d6" }

Campos da resposta

store_idstring

Id do seller criado (UUID em /api/v1.0; decimal em string em /api).

Erros

Status	Quando	Corpo de exemplo
401	Sem credencial.	`{"status":401,"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>."}`
401	E-mail ou chave de API inválidos.	`{"status":401,"message":"Invalid credentials"}`
403	A credencial é válida, mas o usuário não é administrador.	`{"status":403,"message":"Forbidden: admin scope required"}`
400	Corpo que não é JSON.	`{"status":400,"message":"invalid request body"}`
400	Sem `company`/`company_name`.	`{"status":400,"message":"company is required"}`
400	Sem `email`.	`{"status":400,"message":"company_name and email are required"}`
400	E-mail mal formado.	`{"status":400,"message":"vendor_email_invalid: mail: missing '@' or angle-addr"}`
400	E-mail já usado por outro seller ativo.	`{"status":400,"message":"vendor_email_in_use"}`
400	Endereço de vitrine com formato inválido ou reservado (`admin`, por exemplo).	`{"status":400,"message":"slug_reserved: \"admin\" is a reserved storefront path"}`

Veja também

Criar loja

Cadastra um seller novo, pendente de aprovação, e devolve o id.

Duas regras que surpreendem: o e-mail é obrigatório (a plataforma recusa o cadastro sem ele, mesmo que o contrato da 1.0 só cite o nome) e o campo address é ignorado na criação.

POST/api/v1.0/storesAdmin

Criar uma loja

Corpo da requisição

companystringobrigatório

Nome fantasia do seller. Obrigatório (ou company_name).

company_namestring

Sinônimo de company. Se os dois vierem, vale company_name.

emailstringobrigatório

E-mail do seller. Obrigatório, deve ser um e-mail válido e único entre sellers ativos (sem diferenciar maiúsculas).

storefrontstring

phonestring

Telefone.

urlstring

Site.

citystring

Cidade.

statestring

UF.

zipcodestring

CEP.

countrystringpadrão: BR

País, código ISO de 2 letras.

company_phonestring

Sinônimo de phone; vale este se os dois vierem. O mesmo vale para company_city, company_state, company_country, company_zipcode e company_website (sinônimo de url).

addressstring

Aceito, mas ignorado na criação. Grave o endereço com PUT depois.

statusstring

Aceito, mas ignorado na criação: o seller sempre nasce P.

POST/api/storesAdmin

Mesma operação, caminho alternativo

POST/api/v1.0/vendorsAdmin

Mesma operação, caminho alternativo

Mesmo comportamento, parâmetros e resposta de POST /api/v1.0/stores. Use este caminho se o seu cliente já foi escrito para ele.

POST/api/vendorsAdmin

Mesma operação, caminho alternativo

POST/api/v1.0/companiesAdmin

Mesma operação, caminho alternativo

Mesmo comportamento, parâmetros e resposta de POST /api/v1.0/stores. Use este caminho se o seu cliente já foi escrito para ele.

POST/api/companiesAdmin

Mesma operação, caminho alternativo

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1.0/stores" \
  -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company": "Moda Aurora Ltda",
  "email": "contato@modaaurora.example",
  "phone": "(11) 98888-7777",
  "url": "https://modaaurora.example",
  "city": "São Paulo",
  "state": "SP",
  "zipcode": "01310-100",
  "country": "BR",
  "storefront": "modaaurora.venddor.com.br"
}'

Resposta

201Loja criada

json

{ "store_id": "3b617148-8a28-4d07-8040-a8903b4238d6" }

Campos da resposta

store_idstring

Id do seller criado (UUID em /api/v1.0; decimal em string em /api).

Erros

Status	Quando	Corpo de exemplo
401	Sem credencial.	`{"status":401,"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>."}`
401	E-mail ou chave de API inválidos.	`{"status":401,"message":"Invalid credentials"}`
403	A credencial é válida, mas o usuário não é administrador.	`{"status":403,"message":"Forbidden: admin scope required"}`
400	Corpo que não é JSON.	`{"status":400,"message":"invalid request body"}`
400	Sem `company`/`company_name`.	`{"status":400,"message":"company is required"}`
400	Sem `email`.	`{"status":400,"message":"company_name and email are required"}`
400	E-mail mal formado.	`{"status":400,"message":"vendor_email_invalid: mail: missing '@' or angle-addr"}`
400	E-mail já usado por outro seller ativo.	`{"status":400,"message":"vendor_email_in_use"}`
400	Endereço de vitrine com formato inválido ou reservado (`admin`, por exemplo).	`{"status":400,"message":"slug_reserved: \"admin\" is a reserved storefront path"}`