Venda de balcão

Uma venda de balcão é a venda feita presencialmente, com o cliente na frente do operador. A API registra a venda como um pedido da loja já pago (canal pos), grava o pagamento, e emite a NFC-e (Nota Fiscal de Consumidor Eletrônica, o cupom fiscal eletrônico do varejo) pelo provedor fiscal configurado. Serve para um caixa próprio, um totem ou qualquer sistema que venda no balcão usando o estoque e o catálogo da plataforma.

Estas são as rotas de administração do balcão. O aplicativo de caixa do operador (abertura de caixa, carrinho, sangria) usa outro conjunto de rotas que não é coberto aqui.

Como funciona

Ciclo de uma venda

1. Encontre os produtos

   GET /pos/products/lookup busca por nome, SKU ou código de barras e devolve o id e o preço de cada produto.

2. Registre a venda

   POST /pos/sales valida as linhas, recalcula os preços, cria o pedido pago, grava a venda e tenta emitir a NFC-e na hora.

3. Confira a emissão

   A resposta traz emission_status. Se vier pending, a nota entrou numa fila e será emitida em segundo plano (contingência). Consulte depois a lista de vendas.

4. Imprima o recibo

   GET /pos/sales/{id}/receipt devolve os bytes ESC/POS para impressora térmica (ou HTML com format=html), e /receipt.json devolve os mesmos dados estruturados.

Estados

Conceitos importantes

Estabelecimento fiscal

Toda venda é emitida por um estabelecimento: o CNPJ emissor cadastrado nas configurações fiscais da loja, já provisionado no provedor de notas. O establishment_id da venda é o id desse cadastro. Estabelecimento sem provisionamento devolve 422 establishment not provisioned.

Pagamento único e dividido

Para um pagamento só, envie payment_method e amount_paid_cents. Para dividir (parte em dinheiro, parte no Pix), envie a lista payments. Nesse caso ela é a fonte da verdade: a forma principal é a de maior valor e o total recebido é a soma. O troco é o recebido menos o total da venda (nunca negativo).

Contingência de 15 segundos

A API espera até 15 segundos pela autorização da nota. Passado esse tempo, devolve 201 com emission_status: "pending" e deixa a emissão para o processo de fundo, que emite uma única vez. Não reenvie a venda por causa de um pending: ela já foi gravada.

Endpoints

Erros comuns

1. Mandar o preço e esperar que valha. unit_price_cents é descartado. Se o preço mudou no catálogo, a venda usa o novo.
2. Esquecer o CPF acima de R$ 3.000,00. A venda é recusada com 422.
3. Mandar payment_method fora de cash, card ou pix no pagamento único. A validação desse campo é fraca: o pedido pode ser criado e a gravação da venda falhar depois. Envie só os três valores.
4. Repetir a venda após pending. Duplica o pedido. Espere e consulte a lista.
5. Listar sem datas e achar que sumiu. Sem from e to, a lista traz só o dia de hoje.
6. Achar que cancelar é instantâneo. A venda só passa a cancelled depois que o provedor fiscal confirma o cancelamento da nota. Se ele recusar, você recebe 422 e a venda continua completed.
7. Esperar 404 em id inexistente. Recibo e cancelamento devolvem 500/422 com sql: no rows in result set; valide o id antes.

Próximos passos