VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API legada/Referência completa/PDV e terminal de balcão

Fechar a venda

Cria o pedido de uma venda de balcão a partir dos itens lidos no terminal, baixa o estoque e devolve os dados para o recibo.

Quando o caixa conclui a venda, o terminal manda os itens, o cliente e a forma de pagamento para esta rota. A plataforma cria um pedido normal (ele aparece no painel e na lista de pedidos), baixa o estoque dos itens e devolve o número do pedido e o total para o terminal imprimir o recibo.

O preço de cada item é sempre o do catálogo: o price do corpo é ignorado. Frete e desconto são os únicos valores que o terminal controla (shipping_cost e discount, em string decimal).

Produto físico é recusado em lojas que calculam frete

Esta rota não tem campo para a forma de envio. Quando a loja calcula frete e o pedido tem um produto que exige envio, a plataforma recusa a venda com shipping_service_unavailable: a shipping method is required for physical products (medido no ambiente de desenvolvimento com um produto comum). Só passam produtos marcados como "não exige envio" (serviços, produtos digitais). Para vender produto físico no balcão, crie o pedido por Criar pedido, que aceita endereço e forma de envio.

POST/api/v1.0/pos_checkoutAdmin

Venddor 1.0: fechar uma venda de balcão (ids UUID)

Cria o pedido. Exige um usuário administrador. Nomes alternativos em Nomes alternativos do fechamento.

Corpo da requisição

scopestringobrigatório
place_order
Tem de ser exatamente place_order. Qualquer outro valor responde Unsupported scope. Use scope=place_order.
order_agentstringobrigatório
Identificação do caixa ou do terminal. É obrigatório, mas o valor não é gravado no pedido.
product_infoarrayobrigatório

Itens da venda. Pelo menos um item que não seja brinde.

product_idstringobrigatório
Id do produto (UUID, ou decimal em /api/pos_checkout). Um id que não existe recusa a venda.
qtyintegerpadrão: 1
Quantidade. Valor menor que 1 ou ausente vale 1.
is_free_productbooleanpadrão: false
Quando true, o item é descartado (brinde calculado pelo terminal não vira linha do pedido).
selected_optionsobject
Opções escolhidas (cor, tamanho). Guardadas na linha do pedido como vieram.
pricestring
Aceito e ignorado: o preço vem do catálogo.
customer_infoobjectobrigatório

Quem compra.

emailstringobrigatório
E-mail do cliente. Sem ele a venda é recusada com Required params missing.
user_idstring
Id do cliente (UUID, ou decimal em /api). Se faltar, vale o user_id do nível acima.
firstnamestring
Nome do cliente. Forma o nome do pedido.
lastnamestring
Sobrenome do cliente.
phonestring
Aceito e ignorado.
user_idstring
Id do cliente, usado quando customer_info.user_id não vem.
payment_infoobject

Pagamento.

payment_typestringpadrão: cash
Código da forma de pagamento (o payment_code devolvido pelo login, por exemplo pix ou pagamento-na-entrega). Sem ele o pedido é gravado como cash.
shipping_coststringpadrão: 0
Frete cobrado, em string decimal ("12.50").
discountstringpadrão: 0
Desconto total concedido no balcão, em string decimal.
order_commentstring
Observação do cliente gravada no pedido.
qtyinteger
Aceito e ignorado (a quantidade vale por item).
currency_codestring
Aceito e ignorado: a moeda é a da loja.
subtotalstring
Aceito e ignorado: o servidor recalcula.
totalstring
Aceito e ignorado: o servidor recalcula.
shipping_idstring
Aceito e ignorado. Não escolhe a forma de envio (veja o aviso acima).
couponsarray
Aceito e ignorado: cupons não são aplicados por esta rota.
POST/api/pos_checkoutAdmin

Fechar uma venda de balcão, forma sem versão (ids decimais)

Igual a POST /api/v1.0/pos_checkout. Os ids do corpo (product_id, user_id) podem ser decimais, e order_data.order_id volta decimal.

Corpo da requisição

scopestringobrigatório
place_order
Tem de ser place_order.
order_agentstringobrigatório
Identificação do caixa. Não é gravado.
product_infoarrayobrigatório
Itens: product_id, qty, is_free_product, selected_options.
customer_infoobjectobrigatório
email (obrigatório), user_id, firstname, lastname.
payment_infoobject
payment_type, o código da forma de pagamento.
shipping_coststringpadrão: 0
Frete em string decimal.
discountstringpadrão: 0
Desconto em string decimal.
order_commentstring
Observação do pedido.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1.0/pos_checkout" \
  -u "$ADMIN_EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "place_order",
    "order_agent": "caixa-01",
    "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
    "product_info": [
      { "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6", "qty": 1 }
    ],
    "customer_info": {
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "email": "maria.souza@example.com",
      "firstname": "Maria",
      "lastname": "Souza"
    },
    "payment_info": { "payment_type": "pagamento-na-entrega" },
    "shipping_cost": "0.00",
    "discount": "0.00",
    "order_comment": "Venda de balcão"
  }'

Resposta

200Venda registrada
json
{
  "status": 200,
  "data": {
    "success": true,
    "message": "",
    "order_data": {
      "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
      "status": "O",
      "date": 1791749845,
      "order_info": {
        "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
        "status": "O",
        "date": 1791749845,
        "total": "1678.95",
        "subtotal": "1678.95"
      },
      "error": []
    }
  }
}
200Venda recusada (também é HTTP 200)
json
{
  "status": 200,
  "data": {
    "success": false,
    "message": "Order creation failed: shipping_service_unavailable: a shipping method is required for physical products",
    "order_data": {
      "order_id": 0,
      "error": [
        { "priority": "error", "message": "shipping_service_unavailable: a shipping method is required for physical products" }
      ]
    }
  }
}

Campos da resposta

data.successboolean
true quando o pedido foi criado.
data.messagestring
Vazio no sucesso; o motivo em inglês na falha.
data.order_data.order_idstring
Id do pedido criado (UUID; decimal em /api). Na falha vale o número 0.
data.order_data.statusstring
Status inicial do pedido, em letra.
data.order_data.dateinteger
Criação do pedido, em Unix timestamp (segundos).
data.order_data.order_infoobject
Cópia para o recibo: order_id, status, date, total e subtotal (strings decimais, em reais).
data.order_data.errorarray
Vazia no sucesso. Na falha, itens {priority, message} com o motivo.

Erros

Os erros de negócio voltam com HTTP 200 e data.success: false:

data.messageQuando
Invalid JSON bodyO corpo não é um JSON válido.
Unsupported scope. Use scope=place_orderscope ausente ou diferente de place_order.
Required params missing: order_agent, product_info, customer_infoFalta order_agent, product_info vazio ou customer_info.email vazio.
No products in orderTodos os itens são brindes (is_free_product).
Order creation failed: ...A plataforma recusou o pedido, por exemplo por produto inexistente ou por exigir forma de envio. O texto depois dos dois-pontos é a mensagem interna e pode mudar.
StatusQuandoCorpo
401Sem credenciais, chave inválida ou token expirado{"message":"Invalid credentials","status":401}
403Usuário que não é administrador{"message":"Forbidden: admin scope required","status":403}
Uma tentativa recusada não cria pedido, mas repetir uma tentativa aceita cria outro

A rota não tem chave de idempotência. Se a resposta se perder (queda de rede no terminal) depois de a venda ter sido aceita, repetir a chamada cria um segundo pedido e baixa o estoque duas vezes. Antes de repetir, procure o pedido na lista de pedidos pelo cliente e pelo horário.

Pagamento no balcão não é cobrado aqui

payment_type só registra a forma de pagamento no pedido. Esta rota não cobra cartão, não gera PIX nem boleto: a cobrança precisa acontecer por fora.

Veja também

  • Login do caixa
  • Produtos e clientes
  • Consultar pedido
  • Cancelar e excluir pedido
Anterior
Produtos e clientes do PDV
Próxima
Nomes alternativos do login
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também