API atual/Referência completa/Venda de balcão (PDV)

Recibos da venda

Obtém o recibo não fiscal de uma venda de balcão em ESC/POS, em HTML ou em JSON estruturado.

O recibo é o comprovante entregue ao cliente. Ele é não fiscal: a validade fiscal está na NFC-e, consultada à parte. Há dois caminhos: o recibo pronto para imprimir (/receipt, em ESC/POS para impressora térmica ou em HTML) e o recibo como dados (/receipt.json), para você desenhar do seu jeito.

Recibo para impressão

Devolve os bytes ESC/POS (a linguagem de comandos das impressoras térmicas de cupom), como texto simples. Com format=html, devolve uma página HTML legível, boa para reimprimir pelo navegador.

GET/api/v1/admin/pos/sales/{id}/receiptAdmin

Recibo da venda em ESC/POS ou HTML

Parâmetros de caminho

iduuidobrigatório

Id da venda (sale_id).

Parâmetros de consulta

formatstring

html

Com html (sem diferenciar maiúsculas), devolve HTML com Content-Type: text/html; charset=utf-8. Qualquer outro valor, ou a ausência, devolve ESC/POS em text/plain; charset=utf-8.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/pos/sales/6f1d6b4e-0a52-4f6a-9d3f-0e1f2a3b4c5d/receipt?format=html" \
  -H "Authorization: Bearer $TOKEN" \
  -o recibo.html

Resposta

200Recibo

html

<!doctype html>
<html lang="pt-BR">
  <body>
    <!-- recibo não fiscal: loja, itens, totais e pagamento -->
  </body>
</html>

Sem format=html, o corpo são os bytes ESC/POS, que incluem a situação da NFC-e e o link do DANFE quando a nota existe. Mande esse conteúdo direto para a impressora térmica.

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, ou módulo fiscal desligado	`{"error":"module_disabled","module":"focusnfe"}`
500	Venda inexistente ou id que não é UUID	`{"error":"failed to build receipt","detail":"sql: no rows in result set"}`

Recibo em JSON

Os mesmos dados do recibo, estruturados, para renderizar na sua tela ou no seu app de caixa.

GET/api/v1/admin/pos/sales/{id}/receipt.jsonAdmin

Recibo da venda em JSON

Parâmetros de caminho

iduuidobrigatório

Id da venda (sale_id).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/pos/sales/6f1d6b4e-0a52-4f6a-9d3f-0e1f2a3b4c5d/receipt.json" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Recibo estruturado

json

{
  "store": { "name": "Loja Exemplo Ltda", "cnpj": "12.345.678/0001-90", "address": "Av. Paulista, 1000 - Bela Vista - São Paulo/SP - CEP 01310100" },
  "order": {
    "id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
    "order_number": "PEDIDO-20261011-0007",
    "created_at": "2026-10-11T14:32:10Z",
    "items": [
      { "name": "Chinelo Clássico Bege 00748", "sku": "SD-000748", "quantity": 2, "unit_price_cents": 1990, "total_cents": 3880 }
    ],
    "subtotal_cents": 3980,
    "discount_total_cents": 100,
    "total_cents": 3880
  },
  "payments": [
    { "method": "cash", "amount_cents": 4000, "change_cents": 120, "installments": 1 }
  ],
  "change_cents": 120,
  "discount_cents": 100,
  "operator_name": "caixa@exemplo.com",
  "session_code": "",
  "sale_code": "6f1d6b4e",
  "footer": "",
  "printed_at": "2026-10-11T14:40:00Z"
}

session_code e footer hoje vêm sempre vazios nesta rota.

Campos da resposta

storeobject

Cabeçalho do emissor: name, cnpj e address (rua e número, bairro, cidade/UF e CEP numa linha só), do estabelecimento fiscal. Se o estabelecimento não tiver nome, name vem como Venddor.

orderobject

Pedido de balcão: id, order_number, created_at, items, subtotal_cents, discount_total_cents e total_cents, todos os valores em centavos.

order.items[]object

Linha do recibo: name, sku, quantity (número), unit_price_cents e total_cents.

paymentsarray

Pagamento declarado da venda, sempre com uma única linha: method (cash, credit_card, debit_card, pix ou other; a forma card da venda aparece como credit_card), amount_cents (total recebido), change_cents e installments (sempre 1). Em pagamento dividido, a linha mostra a forma principal e o total recebido somado.

change_centsinteger

Troco total, em centavos.

discount_centsinteger

Desconto total, em centavos.

operator_namestring

Operador que registrou a venda (e-mail do usuário).

session_codestring

Reservado para o código da sessão de caixa; vem sempre vazio nesta rota.

sale_codestring

Código curto da venda para o cliente, derivado do início do sale_id.

footerstring

Reservado para a mensagem de rodapé; vem sempre vazio nesta rota.

printed_atstring

Momento em que o recibo foi gerado, RFC 3339.

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, ou módulo fiscal desligado	`{"error":"module_disabled","module":"focusnfe"}`
500	Venda inexistente ou id que não é UUID	`{"error":"failed to build receipt","detail":"sql: no rows in result set"}`

Veja também

API atual/Referência completa/Venda de balcão (PDV)

Recibos da venda

Obtém o recibo não fiscal de uma venda de balcão em ESC/POS, em HTML ou em JSON estruturado.

Recibo para impressão

Devolve os bytes ESC/POS (a linguagem de comandos das impressoras térmicas de cupom), como texto simples. Com format=html, devolve uma página HTML legível, boa para reimprimir pelo navegador.

GET/api/v1/admin/pos/sales/{id}/receiptAdmin

Recibo da venda em ESC/POS ou HTML

Parâmetros de caminho

iduuidobrigatório

Id da venda (sale_id).

Parâmetros de consulta

formatstring

html

Com html (sem diferenciar maiúsculas), devolve HTML com Content-Type: text/html; charset=utf-8. Qualquer outro valor, ou a ausência, devolve ESC/POS em text/plain; charset=utf-8.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/pos/sales/6f1d6b4e-0a52-4f6a-9d3f-0e1f2a3b4c5d/receipt?format=html" \
  -H "Authorization: Bearer $TOKEN" \
  -o recibo.html

Resposta

200Recibo

html

<!doctype html>
<html lang="pt-BR">
  <body>
    <!-- recibo não fiscal: loja, itens, totais e pagamento -->
  </body>
</html>

Sem format=html, o corpo são os bytes ESC/POS, que incluem a situação da NFC-e e o link do DANFE quando a nota existe. Mande esse conteúdo direto para a impressora térmica.

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, ou módulo fiscal desligado	`{"error":"module_disabled","module":"focusnfe"}`
500	Venda inexistente ou id que não é UUID	`{"error":"failed to build receipt","detail":"sql: no rows in result set"}`

Recibo em JSON

Os mesmos dados do recibo, estruturados, para renderizar na sua tela ou no seu app de caixa.

GET/api/v1/admin/pos/sales/{id}/receipt.jsonAdmin

Recibo da venda em JSON

Parâmetros de caminho

iduuidobrigatório

Id da venda (sale_id).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/pos/sales/6f1d6b4e-0a52-4f6a-9d3f-0e1f2a3b4c5d/receipt.json" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Recibo estruturado

json

{
  "store": { "name": "Loja Exemplo Ltda", "cnpj": "12.345.678/0001-90", "address": "Av. Paulista, 1000 - Bela Vista - São Paulo/SP - CEP 01310100" },
  "order": {
    "id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
    "order_number": "PEDIDO-20261011-0007",
    "created_at": "2026-10-11T14:32:10Z",
    "items": [
      { "name": "Chinelo Clássico Bege 00748", "sku": "SD-000748", "quantity": 2, "unit_price_cents": 1990, "total_cents": 3880 }
    ],
    "subtotal_cents": 3980,
    "discount_total_cents": 100,
    "total_cents": 3880
  },
  "payments": [
    { "method": "cash", "amount_cents": 4000, "change_cents": 120, "installments": 1 }
  ],
  "change_cents": 120,
  "discount_cents": 100,
  "operator_name": "caixa@exemplo.com",
  "session_code": "",
  "sale_code": "6f1d6b4e",
  "footer": "",
  "printed_at": "2026-10-11T14:40:00Z"
}

session_code e footer hoje vêm sempre vazios nesta rota.

Campos da resposta

storeobject

Cabeçalho do emissor: name, cnpj e address (rua e número, bairro, cidade/UF e CEP numa linha só), do estabelecimento fiscal. Se o estabelecimento não tiver nome, name vem como Venddor.

orderobject

Pedido de balcão: id, order_number, created_at, items, subtotal_cents, discount_total_cents e total_cents, todos os valores em centavos.

order.items[]object

Linha do recibo: name, sku, quantity (número), unit_price_cents e total_cents.

paymentsarray

change_centsinteger

Troco total, em centavos.

discount_centsinteger

Desconto total, em centavos.

operator_namestring

Operador que registrou a venda (e-mail do usuário).

session_codestring

Reservado para o código da sessão de caixa; vem sempre vazio nesta rota.

sale_codestring

Código curto da venda para o cliente, derivado do início do sale_id.

footerstring

Reservado para a mensagem de rodapé; vem sempre vazio nesta rota.

printed_atstring

Momento em que o recibo foi gerado, RFC 3339.

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, ou módulo fiscal desligado	`{"error":"module_disabled","module":"focusnfe"}`
500	Venda inexistente ou id que não é UUID	`{"error":"failed to build receipt","detail":"sql: no rows in result set"}`