API 4.0 (app móvel)

A API 4.0 (/api/4.0) é o contrato do app móvel da loja, herdado da plataforma Venddor 1.0. O app mostra a home com banners e vitrines, lista categorias e produtos, abre a ficha do seller e do produto, mostra as formas de pagamento e permite ao cliente pedir o cancelamento ou contestar um pedido. As respostas imitam o formato antigo: chaves no singular e no plural misturadas (sra_products devolve products), números como texto e dinheiro em reais.

Use a 4.0 quando você mantém um app que já foi escrito para ela.

Como funciona

Um app típico começa anônimo e passa a usar a sessão do cliente depois do login.

1. Monte a home

   Chame Blocos da home com o layout 2572. A resposta já traz banners, categorias, produtos e sellers prontos para desenhar.

2. Navegue pelo catálogo

   Use Categorias para o menu e Produtos para as listas, a busca e a ficha do produto.

3. Entre com o cliente

   Faça o login do cliente (Autenticação) e guarde o token de acesso (JWT). Ele vira a ekey das rotas do cliente.

4. Use as rotas do cliente

   Com a ekey, chame Sellers, Avisos e Cancelamento e contestação.

Conceitos-chave

Os três níveis de acesso

Atenção ao catálogo: as rotas de catálogo aceitam a ekey como opcional. Sem cabeçalho, a chamada é anônima. Com cabeçalho, ele precisa ser uma ekey válida de cliente da loja: um Bearer, um token vencido ou um token de outra loja responde 401 {"error":"unauthorized"}. Com a ekey, os preços e a visibilidade seguem o grupo do cliente.

A ekey monta-se assim: pegue o JWT do cliente, codifique em Base64 e acrescente : no fim do cabeçalho.

EKEY="$(printf '%s' "$CUSTOMER_TOKEN" | base64 -w0):"
curl "$BASE_URL/api/4.0/CpNotifications/1" -H "Authorization: Basic $EKEY"

Só serve JWT de cliente (user_type cliente). Token de administrador ou de seller é recusado com 401.

Ids

Um id da 4.0 é um inteiro decimal escrito como texto ("1585658495"), sempre dentro do intervalo de 32 bits. Nas lojas migradas da plataforma 1.0 ele é o id antigo do registro; nas demais, é derivado do UUID. Os caminhos e filtros aceitam o id decimal ou o UUID. company_id é o seller; "0" é a própria loja.

Dinheiro, textos numéricos e imagens

• Preços saem como número em reais (52.9) e em price_formatted.price como texto com duas casas ("52.90").
• Contagens de categoria (product_count) e position saem como texto.
• As imagens saem em três variantes (icon, detailed, icons), todas com URL absoluta. Os ícones são miniaturas (400 px).

Endpoints

Erros comuns

• Mandar Bearer nas rotas de catálogo. Qualquer Authorization que não seja uma ekey válida derruba a chamada com 401, mesmo numa rota pública. Omita o cabeçalho para ir anônimo.
• Esquecer o : no fim da ekey. O : depois do Base64 é opcional, mas o Base64 não pode conter o : dentro (não codifique token:).
• Tratar product_count e position como número. Saem como texto.
• Calcular em centavos. A 4.0 devolve reais, como número decimal. Se o seu sistema trabalha em centavos, multiplique por 100 e arredonde.
• Guardar o id como inteiro de 64 bits ou como UUID. Guarde o texto devolvido e reenvie igual.
• Esperar página de módulo ativa. Páginas do app só funciona se a loja ligou o recurso; senão responde 403 module_disabled.

Próximos passos