PDV e terminal de balcão

Um PDV (ponto de venda, ou POS) é o computador ou celular do caixa de uma loja física. Na plataforma antiga (Venddor 1.0), o aplicativo de balcão falava com a loja por quatro operações: entrar como caixa, baixar produtos, baixar clientes e fechar a venda. Estas rotas continuam no ar para que os terminais já instalados não parem. Elas não são a forma recomendada de começar uma integração nova.

Cada operação responde por vários nomes (pos_login, wk_pos_login, wkposlogin), com e sem o prefixo /api/v1.0. Todos os nomes de uma operação chamam o mesmo código e devolvem a mesma resposta.

Como funciona

1. Credencial do terminal

   Um administrador gera uma chave de API no painel (HTTP Basic e-mail:chave_de_api) ou o terminal usa um JWT. Sem isso até o login responde 401.

2. Login do caixa

   Login do caixa confere e-mail e senha do operador e devolve perfil, formas de pagamento e de envio da loja e um access_token.

3. Carga de dados

   Produtos e clientes alimentam a base local do terminal. Ambos são paginados.

4. Venda

   Fechar a venda cria o pedido, baixa o estoque e devolve o número do pedido para o recibo.

Conceitos-chave

Os nomes de cada operação

A plataforma antiga derivava o endereço do nome da classe do aplicativo (WkPosLogin virou wk_pos_login). A Venddor 2.0 renomeou para pos_*. Para não quebrar terminais instalados, os três nomes existem, e o servidor ignora maiúsculas e minúsculas e a barra final (/api/WkPosLogin funciona).

O envelope das respostas

Toda resposta das quatro operações tem o mesmo formato:

{ "status": 200, "data": { "success": true, "message": "" } }

status é sempre 200. Quem diz se deu certo é data.success; quando é false, data.message traz o motivo (em inglês, como o servidor devolve). Os campos específicos de cada operação vêm dentro de data.

Ids e dinheiro

Em /api/v1.0 todo id é UUID. Em /api (sem versão) o servidor troca os UUID por números decimais em string ("1487324647") em toda a resposta, e aceita esses decimais na entrada. Exceção: payment_id e shipping_id das listas de pos_login continuam UUID. Valores em dinheiro são strings decimais com ponto ("1678.95"), nunca centavos.

O que o login devolve e o que ele não faz

O access_token do login é um JWT do caixa. Ele serve de Bearer em chamadas seguintes, mas só abre as rotas de catálogo e venda se o caixa for administrador. manager_id, ec_user_level e manager_discount_limit voltam sempre vazios, balance é sempre "0.00" e usergroups é sempre uma lista vazia: existem só para o app antigo não quebrar ao ler o JSON.

Endpoints

Erros comuns

• Chamar pos_login sem credencial. O login não é público: sem Authorization a resposta é 401 Authentication required. Gere antes a chave de API do terminal.
• Tratar o HTTP 200 como sucesso. Senha errada, produto inexistente e pedido recusado voltam com 200. Leia data.success.
• Esperar que o caixa comum consiga vender. Catálogo, clientes e fechamento exigem administrador; um caixa sem esse perfil vê 403 Forbidden: admin scope required.
• Mandar preço no fechamento. O preço de cada item vem do catálogo; price, subtotal e total do corpo são ignorados.
• Vender produto físico e esperar que funcione. O fechamento não envia forma de envio; em lojas com frete ligado a venda é recusada com shipping_service_unavailable.
• Misturar ids de /api e de /api/v1.0. Escolha uma forma e mantenha.

Próximos passos