VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/ERP Frente de caixa (PDV)

Vendas do PDV

Registra vendas numa sessão aberta (com baixa de estoque e NFC-e opcionais), lista as vendas e lê o recibo.

Listar vendas

GET/api/v1/vendor/erp/pdv/salesSeller

Lista as vendas do PDV

Parâmetros de consulta

session_iduuid
Só vendas desta sessão.
register_iduuid
Só vendas das sessões deste caixa.
fromstring
Início, sobre a data da venda. Data ou data e hora RFC 3339.
tostring
Fim, inclusivo. Uma data sem hora vale meia-noite do início do dia.
pageintegerpadrão: 1
Página, a partir de 1. Valor inválido ou menor que 1 volta para 1.
per_pageintegerpadrão: 50
Itens por página, de 1 a 200. Fora dessa faixa vale o padrão.

Exemplo de requisição: Listar vendas

bash
curl "$BASE_URL/api/v1/vendor/erp/pdv/sales?session_id=f403dacc-b763-4866-bf47-a5caee6319f8" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar vendas

200Vendas
json
{
  "sales": [
    {
      "id": "2b3c4d5e-6f70-4812-93a4-b5c6d7e8f901",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "session_id": "f403dacc-b763-4866-bf47-a5caee6319f8",
      "total_cents": 11980,
      "payment_method": "pix",
      "created_at": "2026-10-11T14:30:00Z",
      "establishment_id": "9e8d7c6b-5a49-4837-a6b5-c4d3e2f1a0b9",
      "order_id": "87fdfd05-07bf-4031-a468-219fc35e4e39",
      "nfe_record_id": "5a6b7c8d-9e0f-4102-a3b4-c5d6e7f80912",
      "emission_status": "authorized"
    }
  ],
  "total": 1
}

Campos da resposta

salesarray

Vendas da página, da mais nova para a mais antiga.

iduuid
Id da venda.
vendor_iduuid
Seller dono.
session_iduuid
Sessão.
total_centsinteger
Total em centavos.
payment_methodstring
cashcreditdebitpixother
Forma de pagamento.
created_atdatetime
Quando foi registrada.
stock_appliedinteger
Só na criação: linhas cujo estoque foi baixado no ERP. Ausente quando 0.
itemsarray

Só na criação: o carrinho. A listagem não traz itens.

product_iduuid
Produto.
product_namestring
Nome gravado na venda.
warehouse_iduuid
Depósito de onde sai o estoque.
quantityinteger
Quantidade.
unit_price_centsinteger
Preço unitário em centavos.
line_total_centsinteger
Quantidade vezes preço.
establishment_iduuid
Estabelecimento fiscal usado. Ausente sem emissão.
order_iduuid
Pedido interno criado pela emissão fiscal. Ausente sem emissão.
nfe_record_iduuid
Documento fiscal (NFC-e). Ausente sem emissão.
emission_statusstring
pendingauthorizedfailed
Situação da emissão. Ausente sem emissão.
fiscal_errorstring
Motivo da falha, só na criação quando failed.
totalinteger
Total que atende ao filtro.

Erros: Listar vendas

StatusQuandoCorpo
500Um filtro de id não é um UUID válido (a plataforma devolve 500, não 400).{"error":"failed to list sales","detail":"o valor \"xyz\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Registrar venda

Grava uma venda numa sessão aberta. Com items, o total é calculado pelo servidor a partir das linhas (e o total_cents enviado é ignorado, exceto na emissão fiscal, veja o aviso). Sem itens, vale o total_cents informado, útil para venda avulsa sem carrinho. Dois comportamentos opcionais: baixar estoque e emitir a NFC-e (nota fiscal de consumidor).

POST/api/v1/vendor/erp/pdv/salesSeller

Registra uma venda no PDV

Corpo da requisição

session_iduuidobrigatório
Sessão aberta do seller.
payment_methodstringobrigatório
cashcreditdebitpixother
Forma de pagamento. Aceita maiúsculas.
total_centsinteger
Total em centavos. Obrigatório se não há items com preço.
itemsarray

Carrinho.

product_iduuidobrigatório
Produto.
quantityintegerobrigatório
Quantidade, maior que zero.
unit_price_centsinteger
Preço unitário em centavos, zero ou mais.
product_namestring
Nome para guardar na venda.
warehouse_iduuid
Depósito de onde baixar o estoque. Sem ele, a linha não baixa estoque.
emit_fiscalbooleanpadrão: false
true pede a emissão da NFC-e. Exige establishment_id e itens com produto e preço.
establishment_iduuid
Estabelecimento fiscal (veja Estabelecimentos).
customer_cpfstring
CPF do consumidor na nota, opcional.
customer_namestring
Nome do consumidor, opcional.

Exemplo de requisição: Registrar venda

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/pdv/sales" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "session_id": "f403dacc-b763-4866-bf47-a5caee6319f8",
  "payment_method": "pix",
  "total_cents": 11980,
  "items": [
    {
      "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
      "product_name": "Camiseta Básica Preta M",
      "quantity": 2,
      "unit_price_cents": 5990,
      "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8"
    }
  ],
  "emit_fiscal": true,
  "establishment_id": "9e8d7c6b-5a49-4837-a6b5-c4d3e2f1a0b9",
  "customer_cpf": "123.456.789-09"
}'

Resposta: Registrar venda

201Venda registrada
json
{
  "id": "2b3c4d5e-6f70-4812-93a4-b5c6d7e8f901",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "session_id": "f403dacc-b763-4866-bf47-a5caee6319f8",
  "total_cents": 11980,
  "payment_method": "pix",
  "created_at": "2026-10-11T14:30:00Z",
  "stock_applied": 1,
  "items": [
    {
      "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
      "product_name": "Camiseta Básica Preta M",
      "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
      "quantity": 2,
      "unit_price_cents": 5990,
      "line_total_cents": 11980
    }
  ],
  "establishment_id": "9e8d7c6b-5a49-4837-a6b5-c4d3e2f1a0b9",
  "order_id": "87fdfd05-07bf-4031-a468-219fc35e4e39",
  "nfe_record_id": "5a6b7c8d-9e0f-4102-a3b4-c5d6e7f80912",
  "emission_status": "authorized"
}

Campos da resposta

iduuid
Id da venda.
vendor_iduuid
Seller dono.
session_iduuid
Sessão.
total_centsinteger
Total em centavos.
payment_methodstring
cashcreditdebitpixother
Forma de pagamento.
created_atdatetime
Quando foi registrada.
stock_appliedinteger
Só na criação: linhas cujo estoque foi baixado no ERP. Ausente quando 0.
itemsarray

Só na criação: o carrinho. A listagem não traz itens.

product_iduuid
Produto.
product_namestring
Nome gravado na venda.
warehouse_iduuid
Depósito de onde sai o estoque.
quantityinteger
Quantidade.
unit_price_centsinteger
Preço unitário em centavos.
line_total_centsinteger
Quantidade vezes preço.
establishment_iduuid
Estabelecimento fiscal usado. Ausente sem emissão.
order_iduuid
Pedido interno criado pela emissão fiscal. Ausente sem emissão.
nfe_record_iduuid
Documento fiscal (NFC-e). Ausente sem emissão.
emission_statusstring
pendingauthorizedfailed
Situação da emissão. Ausente sem emissão.
fiscal_errorstring
Motivo da falha, só na criação quando failed.

Erros: Registrar venda

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400session_id em branco.{"error":"vendorerp: session_id required"}
400Forma de pagamento inválida.{"error":"vendorerp: payment_method must be cash|credit|debit|pix|other"}
400Item sem produto.{"error":"vendorerp: item product_id required"}
400Item com quantidade <= 0.{"error":"vendorerp: item quantity must be > 0"}
400Preço negativo.{"error":"vendorerp: item unit_price_cents must be >= 0"}
400Total final menor ou igual a zero.{"error":"vendorerp: total_cents must be > 0"}
400A sessão está fechada.{"error":"session is not open"}
400emit_fiscal sem establishment_id.{"error":"vendorerp: estabelecimento obrigatório para emissão fiscal"}
400emit_fiscal sem item com preço.{"error":"vendorerp: emissão fiscal exige itens com produto e preço unitário"}
400O ambiente não tem emissão fiscal configurada.{"error":"vendorerp: emissão fiscal indisponível neste ambiente"}
404A sessão não existe ou é de outro seller.{"error":"session not found"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}
Na emissão fiscal envie total_cents igual à soma dos itens

O valor pago informado ao emissor fiscal é o total_cents que você enviou, não o total calculado das linhas. Se omitir total_cents com emit_fiscal, o emissor recebe zero.

Falha fiscal não derruba a venda

Se a emissão falhar, a venda é gravada mesmo assim (201) com emission_status: failed e o motivo em fiscal_error. Sempre confira emission_status antes de entregar o cupom.

Baixa de estoque best-effort

Sem emissão fiscal, cada linha com warehouse_id gera uma saída no estoque do ERP; se alguma saída falhar (por exemplo, saldo insuficiente) a venda continua e stock_applied conta só as que deram certo. Com emissão fiscal autorizada, o estoque é baixado pelo pedido interno, não por esta rota.

Recibo

Devolve os dados para imprimir o comprovante: caixa, sessão, total, pagamento e o vínculo fiscal quando houve emissão. Não traz as linhas do carrinho.

GET/api/v1/vendor/erp/pdv/sales/{id}/receiptSeller

Recibo de uma venda

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da venda.

Exemplo de requisição: Recibo

bash
curl "$BASE_URL/api/v1/vendor/erp/pdv/sales/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10/receipt" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Recibo

200Recibo
json
{
  "sale_id": "2b3c4d5e-6f70-4812-93a4-b5c6d7e8f901",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "register_name": "Caixa 01",
  "session_id": "f403dacc-b763-4866-bf47-a5caee6319f8",
  "total_cents": 11980,
  "payment_method": "pix",
  "customer_cpf": "123.456.789-09",
  "emission_status": "authorized",
  "nfe_record_id": "5a6b7c8d-9e0f-4102-a3b4-c5d6e7f80912",
  "order_id": "87fdfd05-07bf-4031-a468-219fc35e4e39",
  "created_at": "2026-10-11T14:30:00Z"
}

Campos da resposta

sale_iduuid
Venda.
vendor_iduuid
Seller.
register_namestring
Nome do caixa.
session_iduuid
Sessão.
total_centsinteger
Total.
payment_methodstring
Forma de pagamento.
customer_cpfstring
CPF informado. Ausente se não houve.
customer_namestring
Nome informado. Ausente se não houve.
emission_statusstring
Situação fiscal. Ausente sem emissão.
nfe_record_iduuid
Documento fiscal. Ausente sem emissão.
order_iduuid
Pedido interno. Ausente sem emissão.
created_atdatetime
Data da venda.

Erros: Recibo

StatusQuandoCorpo
404A venda não existe ou é de outro seller.{"error":"venda não encontrada"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Veja também

  • Sessões de caixa
  • Indicadores e estabelecimentos
Anterior
Sangria e suprimento
Próxima
Indicadores e estabelecimentos
Nesta página
  • Listar vendas
  • Exemplo de requisição: Listar vendas
  • Resposta: Listar vendas
  • Erros: Listar vendas
  • Registrar venda
  • Exemplo de requisição: Registrar venda
  • Resposta: Registrar venda
  • Erros: Registrar venda
  • Recibo
  • Exemplo de requisição: Recibo
  • Resposta: Recibo
  • Erros: Recibo
  • Veja também