Lojas, vendors e companies

Na Venddor um seller (lojista) é a empresa que vende dentro de uma loja-marketplace. A plataforma 1.0 chamava essa empresa de company (e, em partes da documentação, de store ou vendor). Esta seção documenta as rotas de compatibilidade que cadastram, consultam, alteram e excluem sellers com o mesmo contrato que os clientes antigos (ERP, painéis, apps) já usam.

Como funciona

Situação do seller

No filtro status e no corpo do PUT você pode mandar a letra ou o nome (active, pending, disabled, suspended, rejected). Mande a letra: é o que as respostas devolvem.

Fluxo típico de uma integração

1. Cadastrar o seller

   Criar loja devolve o store_id. Guarde-o: é a chave para tudo.

2. Completar os dados

   O cadastro aceita só parte dos campos. Complete (endereço, nome, e-mail) com Alterar loja.

3. Aprovar

   Mande {"status":"A"} no mesmo PUT. Enquanto estiver P o seller não vende.

4. Sincronizar o catálogo dele

   Produtos da loja lista os produtos do seller no formato de produto da 1.0.

Conceitos importantes

Ids

• Em /api/v1.0/... o id é um UUID (c0000000-0000-0000-0000-000000000001).
• Em /api/... (sem a versão) as respostas trocam o UUID por um número decimal em string ("1034851747"), para clientes que só entendem inteiros.
• Nos caminhos (/stores/{id}) só o UUID funciona. Se você pegar o id decimal de uma resposta de /api/stores e chamar /api/stores/1034851747, recebe erro (500; no PUT, 400). Para operar um seller, leia o UUID em /api/v1.0/stores e use-o nos caminhos, nas duas formas.

Três nomes, um recurso

stores, vendors e companies apontam para as mesmas operações. Escolha o que o seu cliente já usa. Cada rota existe também sem /v1.0, e as maiúsculas e minúsculas do caminho são ignoradas.

Datas e dinheiro

A única data é timestamp (Unix, segundos). Estas rotas não trazem valores em dinheiro.

Exclusão lógica

Excluir marca o seller como excluído e D. Ele continua no banco, não aparece em listas e responde 404. O login do dono também é desativado, a menos que ele administre outro seller ativo.

Endpoints

Cada linha vale também para /api/v1.0/vendors..., /api/v1.0/companies... e para as três formas sem /v1.0 (/api/stores..., /api/vendors..., /api/companies...).

Erros comuns

• Usar o id decimal de /api/stores nos caminhos. Dá erro (500; no PUT, 400). Use o UUID.
• Mandar address na criação. O campo é ignorado em POST; o endereço só é gravado por PUT.
• Esperar que o seller criado já venda. Ele nasce P.
• Mandar um status com nome desconhecido ("ativo"). O texto longo estoura a coluna de 1 caractere e a resposta é 400.
• Confiar nas contagens da lista. product_count, order_count e avg_rating só vêm preenchidos no detalhe.
• Pedir mais de 100 itens por página. A lista volta com 20, apesar de params.items_per_page repetir o valor pedido.

Próximos passos