VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa

App do vendedor (mobile)

Visão geral das rotas enxutas pensadas para o aplicativo móvel do lojista e como se relacionam com as rotas completas do painel.

O aplicativo móvel do seller (lojista) precisa de poucas informações por tela e de respostas pequenas, porque roda em redes lentas. Estas rotas devolvem versões resumidas dos pedidos, produtos e números do dia, e permitem a operação mais comum do celular: conferir vendas e corrigir o estoque.

Pontos-chave
  • Tudo é do seu seller: o servidor descobre o seller pelo token e nunca aceita um vendor_id na requisição.
  • Dinheiro é inteiro em centavos (5266 = R$ 52,66). Datas são RFC 3339.
  • O status do pedido é a letra do cadastro de status da loja (por exemplo O pendente, P em processamento, C entregue). Veja Status de pedido.
  • As listas têm no máximo 50 itens por página.
  • A rota de estoque define o total: {"quantity": 50} deixa o saldo em 50, não soma 50.
  • Nenhuma destas rotas exige privilégio específico da equipe do seller além do papel de seller.

Como funciona

Um aplicativo típico abre o painel resumido (dashboard), mostra a lista de pedidos recentes, abre o detalhe de um pedido ao toque e permite ajustar o estoque de um produto. O gráfico de 7 ou 30 dias vem de stats e as mensagens recentes de notifications.

Dashboard→Lista de pedidos→Detalhe do pedido→Produtos→Ajustar estoque

Conceitos-chave

Resumo versus completo

As respostas aqui omitem campos que o app não usa (notas internas, comissões, IP). Para o contrato completo de pedidos e produtos do seller use as rotas do painel.

Dia "de hoje"

"Hoje" é o dia do relógio do servidor. Pedidos de qualquer status entram na contagem e na receita do dia, inclusive cancelados.

Quem pode ver o quê

Um pedido ou produto de outro seller responde 403, não 404. O id do pedido também aceita o número do pedido (por exemplo PEDIDO-20261010-0004).

Endpoints

MétodoCaminhoPara que servePágina
GET/api/v1/vendor/mobile/dashboardNúmeros do dia em uma chamadaPainel e gráfico
GET/api/v1/vendor/mobile/statsPedidos e receita por dia (7 ou 30 dias)Painel e gráfico
GET/api/v1/vendor/mobile/ordersLista resumida de pedidosPedidos
GET/api/v1/vendor/mobile/orders/{id}Detalhe de um pedidoPedidos
GET/api/v1/vendor/mobile/productsLista resumida de produtosProdutos e estoque
PUT/api/v1/vendor/mobile/products/{id}/stockDefinir o estoque total de um produtoProdutos e estoque
GET/api/v1/vendor/mobile/notificationsNotificações do usuárioNotificações

Erros comuns

  • Somar em vez de definir o estoque. A rota grava o valor enviado. Para "vendi 3", leia o saldo e envie o novo total.
  • Pedir mais de 50 itens. per_page=200 volta com 50; leia per_page e total_pages da resposta.
  • Tratar 403 de pedido como "não existe". 403 significa que o pedido existe e é de outro seller; 404 é pedido inexistente.
  • Esperar a receita "líquida" do dia. today_revenue soma o total de todos os pedidos do dia, qualquer que seja o status.
  • Comparar status com nomes. A resposta traz letras; o filtro status aceita letra ou nome.

Próximos passos

Painel e gráfico
Números do dia e série diária.
Pedidos
Lista e detalhe resumidos.
Produtos e estoque
Lista e ajuste de estoque.
Notificações
Avisos do usuário.
Anterior
Agir nas pendências
Próxima
Painel e gráfico
Nesta página
  • Como funciona
  • Conceitos-chave
  • Resumo versus completo
  • Dia "de hoje"
  • Quem pode ver o quê
  • Endpoints
  • Erros comuns
  • Próximos passos