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

Vendas de balcão

Registra uma venda de balcão com NFC-e, lista as vendas do período e cancela uma venda.

Três operações cobrem o ciclo da venda: registrar, listar e cancelar. Todas exigem o módulo fiscal ligado; vender e listar pedem manage_pos ou manage_settings, e cancelar pede manage_nfe ou manage_settings.

Registrar uma venda

Cria o pedido de balcão (já pago), grava a venda e tenta emitir a NFC-e na hora, esperando até 15 segundos. Os preços são relidos do catálogo. Ao final, um evento de venda concluída é publicado para integrações internas.

POST/api/v1/admin/pos/salesAdmin

Registra uma venda de balcão e emite a NFC-e

Corpo da requisição

establishment_iduuidobrigatório

Estabelecimento fiscal emissor. Precisa existir e estar provisionado no provedor de notas.

itemsarrayobrigatório

Linhas da venda. Não pode ser vazia, e o total (soma de preço vezes quantidade menos descontos) precisa ser maior que zero.

product_iduuidobrigatório

Produto do catálogo. Produto inexistente ou apagado recusa a venda inteira.

quantityintegerobrigatório

Quantidade, maior que zero.

unit_price_centsinteger

Ignorado: o servidor usa o preço atual do catálogo.

discount_centsintegerpadrão: 0

Desconto da linha, em centavos. Negativo vira 0 e nunca passa do total da linha.

customer_cpfstring

CPF do consumidor (só os dígitos são gravados). Obrigatório quando o total chega a R$ 3.000,00 (300000 centavos) ou mais.

customer_namestring

Nome do consumidor na nota.

payment_methodstring

cashcardpix

Forma de pagamento única. Use só esses três valores.

amount_paid_centsinteger

Valor recebido, em centavos. O troco é este valor menos o total, no mínimo 0.

paymentsarray

Pagamento dividido (opcional). Quando enviado, substitui payment_method e amount_paid_cents: a forma principal é a de maior valor e o recebido é a soma. A soma precisa cobrir o total.

methodstringobrigatório

cashcardpix

Forma de pagamento da parcela.

amount_centsintegerobrigatório

Valor da parcela, maior que zero.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/pos/sales" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "establishment_id": "11111111-1111-1111-1111-111111111111",
    "items": [
      { "product_id": "4cbcf967-23e0-4705-88f7-a74a9a8c63f3", "quantity": 2, "discount_cents": 100 }
    ],
    "customer_cpf": "123.456.789-09",
    "customer_name": "Maria Souza",
    "payments": [
      { "method": "cash", "amount_cents": 2000 },
      { "method": "pix", "amount_cents": 1880 }
    ]
  }'

Resposta

201Venda registrada

json

{
  "sale_id": "6f1d6b4e-0a52-4f6a-9d3f-0e1f2a3b4c5d",
  "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
  "nfe_record_id": "3b9c1a6e-77a1-4c0e-8f60-2a4d5e6f7a8b",
  "emission_status": "authorized",
  "danfe_url": "https://exemplo.com/danfe/abc123.pdf"
}

Campos da resposta

sale_iduuid

Id da venda de balcão. Use nos recibos e no cancelamento.

order_iduuid

Id do pedido criado (canal pos, pago).

nfe_record_iduuid

Registro da nota. Só aparece quando a nota foi autorizada na hora.

emission_statusstring

pendingauthorizedfailed

Situação da NFC-e. Veja a tabela de estados no índice.

danfe_urlstring

Link do documento auxiliar da nota (DANFE NFC-e). Só aparece com a nota autorizada.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid body","detail":"..."}`
401 / 403	Sem token, sem privilégio, ou módulo fiscal desligado	`{"error":"module_disabled","module":"focusnfe"}`
422	Carrinho vazio ou total zero	`{"error":"failed to complete sale","detail":"fiscal: carrinho vazio"}`
422	Quantidade zero ou negativa	`{"error":"failed to complete sale","detail":"fiscal: item com quantidade inválida"}`
422	Produto inexistente ou apagado	`{"error":"failed to complete sale","detail":"fiscal: produto inválido ou indisponível"}`
422	Total de R$ 3.000,00 ou mais sem CPF	`{"error":"failed to complete sale","detail":"fiscal: identificação do consumidor obrigatória acima de R$ 3.000,00"}`
422	Pagamento dividido com forma inválida, parcela menor ou igual a zero, ou soma menor que o total	`{"error":"failed to complete sale","detail":"fiscal: soma dos pagamentos é menor que o total da venda"}`
422	NFC-e desabilitada nas configurações	`{"error":"failed to complete sale","detail":"fiscal: emissão de NFC-e desabilitada nas configurações"}`
422	Estabelecimento inexistente	`{"error":"failed to complete sale","detail":"fiscal: estabelecimento inválido"}`
422	Estabelecimento sem provisionamento	`{"error":"establishment not provisioned","detail":"..."}`
503	Serviço fiscal indisponível	`{"error":"fiscal service unavailable"}`

As mensagens de detail voltam em português, como mostrado.

Listar vendas

Lista as vendas de balcão, da mais nova para a mais antiga. Sem from e to, devolve só as vendas do dia atual (é a lista "vendas do dia" do caixa). Para um período maior, informe as datas.

GET/api/v1/admin/pos/salesAdmin

Lista as vendas de balcão

Parâmetros de consulta

fromstring

Início do período: RFC 3339 ou YYYY-MM-DD. Valor ilegível é ignorado.

tostring

Fim do período: RFC 3339 ou YYYY-MM-DD. Com YYYY-MM-DD o dia inteiro entra.

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 50

Itens por página, de 1 a 200. Valor fora disso volta ao padrão (50).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/pos/sales?from=2026-10-01&to=2026-10-11&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Vendas retornadas

json

{
  "items": [
    {
      "id": "6f1d6b4e-0a52-4f6a-9d3f-0e1f2a3b4c5d",
      "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "establishment_id": "11111111-1111-1111-1111-111111111111",
      "customer_cpf": "12345678909",
      "payment_method": "cash",
      "amount_paid_cents": 4000,
      "change_cents": 120,
      "nfe_record_id": "3b9c1a6e-77a1-4c0e-8f60-2a4d5e6f7a8b",
      "status": "completed",
      "created_at": "2026-10-11T14:32:10.512Z"
    }
  ],
  "total": 1
}

Sem nenhuma venda no período, items vem null e total vem 0.

Campos da resposta

items[].iduuid

Id da venda.

items[].order_iduuid

Pedido de balcão correspondente.

items[].establishment_iduuid

Estabelecimento emissor.

items[].customer_cpfstring

CPF só com dígitos. Ausente em venda sem identificação.

items[].payment_methodstring

cashcardpix

Forma principal de pagamento. Em pagamento dividido, a de maior valor.

items[].amount_paid_centsinteger

Total recebido, em centavos.

items[].change_centsinteger

Troco, em centavos.

items[].nfe_record_iduuid

Registro da nota. Ausente enquanto a nota não foi autorizada.

items[].statusstring

completedcancelled

Situação da venda.

items[].created_atstring

Criação, RFC 3339 em UTC.

totalinteger

Total de vendas no período, em todas as páginas.

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, ou módulo fiscal desligado	`{"error":"module_disabled","module":"focusnfe"}`
500	Falha interna	`{"error":"failed to list sales","detail":"..."}`

Cancelar uma venda

Cancela a NFC-e no provedor fiscal e, se isso deu certo, cancela o pedido de balcão e marca a venda como cancelled. A ordem importa: a venda só muda para cancelled depois que o provedor confirma. O cancelamento de NFC-e só é aceito dentro do prazo da SEFAZ (a secretaria da Fazenda do estado); passado o prazo, o provedor recusa e a venda continua completed.

POST/api/v1/admin/pos/sales/{id}/cancelAdmin

Cancela uma venda de balcão

Parâmetros de caminho

iduuidobrigatório

Id da venda (sale_id, não o do pedido).

Corpo da requisição

justificationstring

Motivo do cancelamento, enviado ao provedor fiscal. Se vazio, o pedido é cancelado com o motivo pos_sale_cancelled.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/pos/sales/6f1d6b4e-0a52-4f6a-9d3f-0e1f2a3b4c5d/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"justification": "Cliente desistiu da compra no caixa"}'

Resposta

200Venda cancelada

json

{ "id": "6f1d6b4e-0a52-4f6a-9d3f-0e1f2a3b4c5d", "status": "cancelled" }

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, ou módulo fiscal desligado	`{"error":"module_disabled","module":"focusnfe"}`
422	Venda inexistente	`{"error":"failed to cancel","detail":"sql: no rows in result set"}`
422	O provedor fiscal recusou o cancelamento (por exemplo, fora do prazo) ou o pedido não pôde ser cancelado	`{"error":"failed to cancel","detail":"..."}`

Veja também

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

Vendas de balcão

Registra uma venda de balcão com NFC-e, lista as vendas do período e cancela uma venda.

Registrar uma venda

POST/api/v1/admin/pos/salesAdmin

Registra uma venda de balcão e emite a NFC-e

Corpo da requisição

establishment_iduuidobrigatório

Estabelecimento fiscal emissor. Precisa existir e estar provisionado no provedor de notas.

itemsarrayobrigatório

Linhas da venda. Não pode ser vazia, e o total (soma de preço vezes quantidade menos descontos) precisa ser maior que zero.

product_iduuidobrigatório

Produto do catálogo. Produto inexistente ou apagado recusa a venda inteira.

quantityintegerobrigatório

Quantidade, maior que zero.

unit_price_centsinteger

Ignorado: o servidor usa o preço atual do catálogo.

discount_centsintegerpadrão: 0

Desconto da linha, em centavos. Negativo vira 0 e nunca passa do total da linha.

customer_cpfstring

CPF do consumidor (só os dígitos são gravados). Obrigatório quando o total chega a R$ 3.000,00 (300000 centavos) ou mais.

customer_namestring

Nome do consumidor na nota.

payment_methodstring

cashcardpix

Forma de pagamento única. Use só esses três valores.

amount_paid_centsinteger

Valor recebido, em centavos. O troco é este valor menos o total, no mínimo 0.

paymentsarray

Pagamento dividido (opcional). Quando enviado, substitui payment_method e amount_paid_cents: a forma principal é a de maior valor e o recebido é a soma. A soma precisa cobrir o total.

methodstringobrigatório

cashcardpix

Forma de pagamento da parcela.

amount_centsintegerobrigatório

Valor da parcela, maior que zero.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/pos/sales" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "establishment_id": "11111111-1111-1111-1111-111111111111",
    "items": [
      { "product_id": "4cbcf967-23e0-4705-88f7-a74a9a8c63f3", "quantity": 2, "discount_cents": 100 }
    ],
    "customer_cpf": "123.456.789-09",
    "customer_name": "Maria Souza",
    "payments": [
      { "method": "cash", "amount_cents": 2000 },
      { "method": "pix", "amount_cents": 1880 }
    ]
  }'

Resposta

201Venda registrada

json

{
  "sale_id": "6f1d6b4e-0a52-4f6a-9d3f-0e1f2a3b4c5d",
  "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
  "nfe_record_id": "3b9c1a6e-77a1-4c0e-8f60-2a4d5e6f7a8b",
  "emission_status": "authorized",
  "danfe_url": "https://exemplo.com/danfe/abc123.pdf"
}

Campos da resposta

sale_iduuid

Id da venda de balcão. Use nos recibos e no cancelamento.

order_iduuid

Id do pedido criado (canal pos, pago).

nfe_record_iduuid

Registro da nota. Só aparece quando a nota foi autorizada na hora.

emission_statusstring

pendingauthorizedfailed

Situação da NFC-e. Veja a tabela de estados no índice.

danfe_urlstring

Link do documento auxiliar da nota (DANFE NFC-e). Só aparece com a nota autorizada.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid body","detail":"..."}`
401 / 403	Sem token, sem privilégio, ou módulo fiscal desligado	`{"error":"module_disabled","module":"focusnfe"}`
422	Carrinho vazio ou total zero	`{"error":"failed to complete sale","detail":"fiscal: carrinho vazio"}`
422	Quantidade zero ou negativa	`{"error":"failed to complete sale","detail":"fiscal: item com quantidade inválida"}`
422	Produto inexistente ou apagado	`{"error":"failed to complete sale","detail":"fiscal: produto inválido ou indisponível"}`
422	Total de R$ 3.000,00 ou mais sem CPF	`{"error":"failed to complete sale","detail":"fiscal: identificação do consumidor obrigatória acima de R$ 3.000,00"}`
422	Pagamento dividido com forma inválida, parcela menor ou igual a zero, ou soma menor que o total	`{"error":"failed to complete sale","detail":"fiscal: soma dos pagamentos é menor que o total da venda"}`
422	NFC-e desabilitada nas configurações	`{"error":"failed to complete sale","detail":"fiscal: emissão de NFC-e desabilitada nas configurações"}`
422	Estabelecimento inexistente	`{"error":"failed to complete sale","detail":"fiscal: estabelecimento inválido"}`
422	Estabelecimento sem provisionamento	`{"error":"establishment not provisioned","detail":"..."}`
503	Serviço fiscal indisponível	`{"error":"fiscal service unavailable"}`

As mensagens de detail voltam em português, como mostrado.

Listar vendas

Lista as vendas de balcão, da mais nova para a mais antiga. Sem from e to, devolve só as vendas do dia atual (é a lista "vendas do dia" do caixa). Para um período maior, informe as datas.

GET/api/v1/admin/pos/salesAdmin

Lista as vendas de balcão

Parâmetros de consulta

fromstring

Início do período: RFC 3339 ou YYYY-MM-DD. Valor ilegível é ignorado.

tostring

Fim do período: RFC 3339 ou YYYY-MM-DD. Com YYYY-MM-DD o dia inteiro entra.

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 50

Itens por página, de 1 a 200. Valor fora disso volta ao padrão (50).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/pos/sales?from=2026-10-01&to=2026-10-11&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Vendas retornadas

json

{
  "items": [
    {
      "id": "6f1d6b4e-0a52-4f6a-9d3f-0e1f2a3b4c5d",
      "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "establishment_id": "11111111-1111-1111-1111-111111111111",
      "customer_cpf": "12345678909",
      "payment_method": "cash",
      "amount_paid_cents": 4000,
      "change_cents": 120,
      "nfe_record_id": "3b9c1a6e-77a1-4c0e-8f60-2a4d5e6f7a8b",
      "status": "completed",
      "created_at": "2026-10-11T14:32:10.512Z"
    }
  ],
  "total": 1
}

Sem nenhuma venda no período, items vem null e total vem 0.

Campos da resposta

items[].iduuid

Id da venda.

items[].order_iduuid

Pedido de balcão correspondente.

items[].establishment_iduuid

Estabelecimento emissor.

items[].customer_cpfstring

CPF só com dígitos. Ausente em venda sem identificação.

items[].payment_methodstring

cashcardpix

Forma principal de pagamento. Em pagamento dividido, a de maior valor.

items[].amount_paid_centsinteger

Total recebido, em centavos.

items[].change_centsinteger

Troco, em centavos.

items[].nfe_record_iduuid

Registro da nota. Ausente enquanto a nota não foi autorizada.

items[].statusstring

completedcancelled

Situação da venda.

items[].created_atstring

Criação, RFC 3339 em UTC.

totalinteger

Total de vendas no período, em todas as páginas.

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, ou módulo fiscal desligado	`{"error":"module_disabled","module":"focusnfe"}`
500	Falha interna	`{"error":"failed to list sales","detail":"..."}`

Cancelar uma venda

POST/api/v1/admin/pos/sales/{id}/cancelAdmin

Cancela uma venda de balcão

Parâmetros de caminho

iduuidobrigatório

Id da venda (sale_id, não o do pedido).

Corpo da requisição

justificationstring

Motivo do cancelamento, enviado ao provedor fiscal. Se vazio, o pedido é cancelado com o motivo pos_sale_cancelled.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/pos/sales/6f1d6b4e-0a52-4f6a-9d3f-0e1f2a3b4c5d/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"justification": "Cliente desistiu da compra no caixa"}'

Resposta

200Venda cancelada

json

{ "id": "6f1d6b4e-0a52-4f6a-9d3f-0e1f2a3b4c5d", "status": "cancelled" }

Erros

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, ou módulo fiscal desligado	`{"error":"module_disabled","module":"focusnfe"}`
422	Venda inexistente	`{"error":"failed to cancel","detail":"sql: no rows in result set"}`
422	O provedor fiscal recusou o cancelamento (por exemplo, fora do prazo) ou o pedido não pôde ser cancelado	`{"error":"failed to cancel","detail":"..."}`