Catálogo do app do vendedor

Como o app móvel do seller da Venddor 1.0 lê e grava produtos, as duas famílias de nomes de URL, o formato de resposta e o mapa das rotas.

Na plataforma antiga, os lojistas (sellers) gerenciavam o catálogo por um aplicativo móvel. O app chamava um conjunto de URLs com a marca dele, e a plataforma atual mantém essas URLs funcionando para que as versões já instaladas nos celulares dos sellers não parem. Esta seção cobre a parte de catálogo desse contrato: categorias, produtos (listar, ler, criar, alterar, excluir em lote), opções, anexos, itens obrigatórios, upload de arquivo e as listas de mix de produtos.

São rotas de compatibilidade, mantidas para os apps de seller já instalados.

Pontos-chave

A resposta é sempre HTTP 200 com {"status": 200, "data": {"success": true|false, "message": "..."}}. Falhas de negócio (produto não encontrado, token de não seller) vêm dentro de data, com success: false. Só falta de credencial (401) e de permissão (403) usam o status HTTP.
Quem chama precisa ser o usuário de um seller ativo. Um administrador autenticado passa pela porta mas recebe success: false com "User is not a vendor" e action: "logout".
Cada rota existe com duas grafias: a canônica vendor_* e a do app antigo vn_*_api. Respondem igual.
Preços saem como string decimal em reais ("49.90") e entram como número em reais (49.9). Não são centavos.
Use /api/v1.0/.... Na URL sem versão os ids viram números e a leitura e a alteração de um produto por id não funcionam.

Como funciona

Listar categorias→Criar produto→Enviar imagens→Conferir na lista→Alterar ou excluir

O seller entra no app com e-mail e chave de API (HTTP Basic) ou com um JWT de usuário do tipo seller. Tudo o que ele lê ou grava é filtrado pelo seller dele: uma lista devolve só os produtos dele, e ler, alterar ou excluir produto de outro seller responde "Access denied" ou ignora o id.

Duas famílias de nomes

Recurso	Nome canônico	Nome do app antigo
Categorias	`vendor_categories`	`vn_categories_api`
Produtos (lista, exclusão em lote)	`vendor_products`	`vn_products_api`
Produto (ler, criar, alterar)	`vendor_product`	`vn_product_api`
Opções do produto	`vendor_product_options`	`vn_product_option`
Anexos do produto	`vendor_product_attachments`	`vn_product_attachment`
Produtos obrigatórios	`vendor_required_products`	`vn_required_products_api`
Envio de arquivo	`vendor_upload`	`vn_upload_file`

Em cada página, a primeira entrada é a canônica sob /api/v1.0; as outras três combinações (nome do app antigo e/ou sem /v1.0) aparecem como aliases.

Conceitos-chave

Envelope de resposta

json

{ "status": 200, "data": { "success": true, "message": "", "products": [] } }

data.success diz se a operação deu certo e data.message traz o motivo quando não deu. Quando a conta não pode usar o app, data ainda traz "action": "logout": o app antigo desloga o usuário.

Mensagens de conta (todas com `success: false` e `action: "logout"`)

`message`	Quando
`Authentication required`	Não há usuário autenticado.
`No vendor assigned to this account`	O usuário não está ligado a nenhum seller.
`User is not a vendor`	O usuário é administrador ou cliente, sem seller.
`Vendor account is not active`	O seller existe, mas não está ativo.

Dinheiro

A API devolve preço como string decimal em reais ("price": "300.00"). Para gravar, você envia número em reais ("price": 300, 49.9). O servidor converte para centavos truncando: veja o aviso em Produto: escrita.

Duas URLs, dois formatos de id

Em /api/v1.0/... o id do produto é UUID. Em /api/... o id sai como inteiro derivado do UUID. O inteiro não é traduzido de volta quando está no caminho (/api/vendor_product/{id}), então ler ou alterar um produto por esse id falha. Use /api/v1.0.

Endpoints

Método e caminho	Para que serve	Autenticação	Página
`GET /api/v1.0/vendor_categories` (e `vn_categories_api`, sem `v1.0`)	Lista as categorias	Seller	Categorias
`GET /api/v1.0/vendor_products` (idem)	Lista os produtos do seller	Seller	Produtos
`POST /api/v1.0/vendor_products` (idem)	Exclui produtos em lote	Seller	Produtos
`GET /api/v1.0/vendor_product/{id}` (idem)	Lê um produto	Seller	Produto: leitura
`POST /api/v1.0/vendor_product` (idem)	Cria um produto	Seller	Produto: escrita
`PUT /api/v1.0/vendor_product/{id}` (idem)	Altera um produto	Seller	Produto: escrita
`GET /api/v1.0/vendor_product_options` (idem)	Opções e variações de um produto	Seller	Opções, anexos e obrigatórios
`GET /api/v1.0/vendor_product_attachments` (idem)	Arquivos de um produto	Seller	Opções, anexos e obrigatórios
`GET /api/v1.0/vendor_required_products` (idem)	Produtos obrigatórios (sempre vazio)	Seller	Opções, anexos e obrigatórios
`POST /api/v1.0/vendor_upload` (idem)	Envia um arquivo	Seller	Upload de arquivo
`GET` e `POST /api/v1.0/mix_products` e `/ecmixproducts` (e sem `v1.0`)	Listas de mix de produtos (ainda não implementadas)	Administrador	Mix de produtos

Erros comuns

Procurar o 404 do produto. O produto inexistente ou de outro seller responde 200 com success: false e "Product not found" ou "Access denied".
Usar POST /vendor_products para criar. Essa rota exclui produtos. Para criar, é POST /vendor_product (singular).
Mandar preço em centavos. O preço entra em reais: 49.9, não 4990.
Chamar com o JWT de administrador. Responde User is not a vendor. Use as credenciais do usuário do seller.
Usar /api/vendor_product/{id} com o id da lista. O id numérico não é traduzido. Use /api/v1.0/vendor_product/{id} com o UUID.
Esperar que vendor_required_products ou mix_products tragam dados. Ambos são tubos vazios por enquanto.

Próximos passos

Produtos

Listar e excluir produtos do seller.

Produto: escrita

Criar e alterar um produto.

Upload de arquivo

Enviar imagens e arquivos.

API legada/Referência completa

Catálogo do app do vendedor

Como o app móvel do seller da Venddor 1.0 lê e grava produtos, as duas famílias de nomes de URL, o formato de resposta e o mapa das rotas.

São rotas de compatibilidade, mantidas para os apps de seller já instalados.

Pontos-chave

A resposta é sempre HTTP 200 com {"status": 200, "data": {"success": true|false, "message": "..."}}. Falhas de negócio (produto não encontrado, token de não seller) vêm dentro de data, com success: false. Só falta de credencial (401) e de permissão (403) usam o status HTTP.
Quem chama precisa ser o usuário de um seller ativo. Um administrador autenticado passa pela porta mas recebe success: false com "User is not a vendor" e action: "logout".
Cada rota existe com duas grafias: a canônica vendor_* e a do app antigo vn_*_api. Respondem igual.
Preços saem como string decimal em reais ("49.90") e entram como número em reais (49.9). Não são centavos.
Use /api/v1.0/.... Na URL sem versão os ids viram números e a leitura e a alteração de um produto por id não funcionam.

Como funciona

Listar categorias→Criar produto→Enviar imagens→Conferir na lista→Alterar ou excluir

Duas famílias de nomes

Recurso	Nome canônico	Nome do app antigo
Categorias	`vendor_categories`	`vn_categories_api`
Produtos (lista, exclusão em lote)	`vendor_products`	`vn_products_api`
Produto (ler, criar, alterar)	`vendor_product`	`vn_product_api`
Opções do produto	`vendor_product_options`	`vn_product_option`
Anexos do produto	`vendor_product_attachments`	`vn_product_attachment`
Produtos obrigatórios	`vendor_required_products`	`vn_required_products_api`
Envio de arquivo	`vendor_upload`	`vn_upload_file`

Em cada página, a primeira entrada é a canônica sob /api/v1.0; as outras três combinações (nome do app antigo e/ou sem /v1.0) aparecem como aliases.

Conceitos-chave

Envelope de resposta

json

{ "status": 200, "data": { "success": true, "message": "", "products": [] } }

Mensagens de conta (todas com `success: false` e `action: "logout"`)

`message`	Quando
`Authentication required`	Não há usuário autenticado.
`No vendor assigned to this account`	O usuário não está ligado a nenhum seller.
`User is not a vendor`	O usuário é administrador ou cliente, sem seller.
`Vendor account is not active`	O seller existe, mas não está ativo.

Método e caminho	Para que serve	Autenticação	Página
`GET /api/v1.0/vendor_categories` (e `vn_categories_api`, sem `v1.0`)	Lista as categorias	Seller	Categorias
`GET /api/v1.0/vendor_products` (idem)	Lista os produtos do seller	Seller	Produtos
`POST /api/v1.0/vendor_products` (idem)	Exclui produtos em lote	Seller	Produtos
`GET /api/v1.0/vendor_product/{id}` (idem)	Lê um produto	Seller	Produto: leitura
`POST /api/v1.0/vendor_product` (idem)	Cria um produto	Seller	Produto: escrita
`PUT /api/v1.0/vendor_product/{id}` (idem)	Altera um produto	Seller	Produto: escrita
`GET /api/v1.0/vendor_product_options` (idem)	Opções e variações de um produto	Seller	Opções, anexos e obrigatórios
`GET /api/v1.0/vendor_product_attachments` (idem)	Arquivos de um produto	Seller	Opções, anexos e obrigatórios
`GET /api/v1.0/vendor_required_products` (idem)	Produtos obrigatórios (sempre vazio)	Seller	Opções, anexos e obrigatórios
`POST /api/v1.0/vendor_upload` (idem)	Envia um arquivo	Seller	Upload de arquivo
`GET` e `POST /api/v1.0/mix_products` e `/ecmixproducts` (e sem `v1.0`)	Listas de mix de produtos (ainda não implementadas)	Administrador	Mix de produtos

Erros comuns

Procurar o 404 do produto. O produto inexistente ou de outro seller responde 200 com success: false e "Product not found" ou "Access denied".
Usar POST /vendor_products para criar. Essa rota exclui produtos. Para criar, é POST /vendor_product (singular).
Mandar preço em centavos. O preço entra em reais: 49.9, não 4990.
Chamar com o JWT de administrador. Responde User is not a vendor. Use as credenciais do usuário do seller.
Usar /api/vendor_product/{id} com o id da lista. O id numérico não é traduzido. Use /api/v1.0/vendor_product/{id} com o UUID.
Esperar que vendor_required_products ou mix_products tragam dados. Ambos são tubos vazios por enquanto.

Próximos passos

Produtos

Listar e excluir produtos do seller.

Produto: escrita

Criar e alterar um produto.

Upload de arquivo

Enviar imagens e arquivos.