ERP de frente de caixa (PDV)

O PDV (ponto de venda, ou frente de caixa) é a venda de balcão: o seller abre um caixa, vende, e no fim do turno confere o dinheiro. Estas rotas controlam esse ciclo e, se você quiser, emitem a NFC-e (nota fiscal ao consumidor) junto da venda.

Como funciona

Ciclo de uma sessão:

1. Cadastrar o caixa
   POST /pdv/registers.
2. Abrir a sessão
   POST /pdv/sessions/open com o troco inicial.
3. Vender
   POST /pdv/sales, e movimente dinheiro com sangria ou suprimento.
4. Conferir e fechar
   GET .../drawer para a prévia e POST .../close com o dinheiro contado.

Conceitos importantes

NFC-e e estabelecimento fiscal

NFC-e é a nota fiscal eletrônica de consumidor usada no varejo. Para emiti-la você informa um estabelecimento fiscal da loja (lista). Limitação atual: a nota sai no CNPJ do estabelecimento da loja, e o consumidor é tratado como visitante, sem divisão por seller.

Venda sem itens

Você pode registrar só total_cents e payment_method, sem carrinho. Nesse caso não há baixa de estoque nem emissão fiscal possível (a emissão exige itens).

Autenticação e escopo

Todas as rotas ficam sob /api/v1/vendor/erp e pedem o token de um usuário seller (lojista), enviado em Authorization: Bearer $TOKEN. Um seller é um vendedor que opera dentro do marketplace da loja, com catálogo, pedidos e financeiro próprios. O token de administrador recebe 403 aqui. Veja Tokens.

O seller é descoberto pelo token. Nenhuma rota aceita vendor_id no corpo ou na URL, e um registro de outro seller responde como se não existisse (404). Não há checagem de privilégio por função do ERP: qualquer usuário seller aprovado da loja que tenha um token válido alcança todas as rotas.

Dinheiro, quantidades e datas

Todo valor monetário é um inteiro em centavos (4990 = R$ 49,90) e o nome do campo termina em _cents. Quantidades são inteiros. Datas de vencimento e de período são YYYY-MM-DD; carimbos de data e hora são RFC 3339 em UTC. Veja Ids, dinheiro e datas.

Erros e listas

O corpo de erro é {"error": "texto"}, às vezes com detail. As mensagens de validação do ERP vêm em inglês, muitas com o prefixo vendorerp:, e algumas em português; as tabelas de erros mostram o texto como o servidor devolve. Regra geral: 400 para validação e para transição de estado inválida, 404 quando o registro não existe (a decisão é feita procurando a palavra not found na mensagem), 500 quando um id de filtro ou de caminho não é um UUID válido. Veja Erros.

As listas respondem {"<plural>": [...], "total": N}. Quando a rota é paginada, total é a contagem de todas as páginas; quando não é, é o tamanho do vetor. Apagar é sempre exclusão lógica (soft delete): o registro some das listas, mas não é destruído. Veja Paginação.

Endpoints

Erros comuns

• Registrar venda numa sessão fechada (400 session is not open).
• Abrir uma segunda sessão no mesmo caixa sem fechar a primeira.
• Esperar que emit_fiscal com total_cents omitido use a soma dos itens: o emissor recebe zero.
• Ignorar emission_status: failed: a venda existe mas a nota não.
• Mandar itens sem warehouse_id e esperar baixa de estoque.
• Contar vendas de cartão na gaveta ao conferir o dinheiro.

Próximos passos