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

Sessões de caixa

Abre e fecha o turno do caixa, lista as sessões e confere o dinheiro esperado na gaveta.

Listar sessões

Uma sessão (turno de caixa) vai da abertura ao fechamento do caixa. Todas as vendas e movimentações de dinheiro pertencem a uma sessão. A lista vem da mais recente para a mais antiga, sem paginação.

GET/api/v1/vendor/erp/pdv/sessionsSeller

Lista as sessões de caixa

Parâmetros de consulta

register_iduuid
Só sessões deste caixa.
statusstring
openclosed
Estado. Valor desconhecido devolve lista vazia.

Exemplo de requisição: Listar sessões

bash
curl "$BASE_URL/api/v1/vendor/erp/pdv/sessions?status=open" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar sessões

200Sessões
json
{
  "sessions": [
    {
      "id": "f403dacc-b763-4866-bf47-a5caee6319f8",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "register_id": "db8100b6-51bf-488e-8d77-810d6e7002b4",
      "register_name": "Caixa 01",
      "opened_by": "b00d3e7c-d5b4-4942-827a-06e2c43645af",
      "opened_at": "2026-10-11T14:30:00Z",
      "opening_cents": 10000,
      "status": "open"
    }
  ],
  "total": 1
}

Campos da resposta

sessionsarray

Sessões.

iduuid
Id da sessão.
vendor_iduuid
Seller dono.
register_iduuid
Caixa.
register_namestring
Nome do caixa.
opened_byuuid
Quem abriu.
opened_atdatetime
Abertura.
closed_atdatetime
Fechamento. Ausente enquanto aberta.
opening_centsinteger
Troco inicial (fundo de caixa) em centavos.
closing_centsinteger
Dinheiro contado no fechamento. Ausente enquanto aberta.
expected_cash_centsinteger
Dinheiro que deveria haver: abertura + vendas em dinheiro + suprimentos - sangrias. Ausente enquanto aberta.
difference_centsinteger
Quebra de caixa: contado menos esperado (negativo é falta). Ausente enquanto aberta.
statusstring
openclosed
Estado.
totalinteger
Quantidade devolvida.

Erros: Listar sessões

StatusQuandoCorpo
500Um filtro de id não é um UUID válido (a plataforma devolve 500, não 400).{"error":"failed to list sessions","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"}

Abrir sessão

POST/api/v1/vendor/erp/pdv/sessions/openSeller

Abre uma sessão de caixa

Corpo da requisição

register_iduuidobrigatório
Caixa ativo do seller.
opening_centsintegerpadrão: 0
Troco inicial em centavos, zero ou mais. Padrão 0.

Exemplo de requisição: Abrir sessão

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/pdv/sessions/open" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "register_id": "db8100b6-51bf-488e-8d77-810d6e7002b4",
  "opening_cents": 10000
}'

Resposta: Abrir sessão

201Sessão aberta
json
{
  "id": "f403dacc-b763-4866-bf47-a5caee6319f8",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "register_id": "db8100b6-51bf-488e-8d77-810d6e7002b4",
  "register_name": "Caixa 01",
  "opened_by": "b00d3e7c-d5b4-4942-827a-06e2c43645af",
  "opened_at": "2026-10-11T14:30:00Z",
  "opening_cents": 10000,
  "status": "open"
}

Campos da resposta

iduuid
Id da sessão.
vendor_iduuid
Seller dono.
register_iduuid
Caixa.
register_namestring
Nome do caixa.
opened_byuuid
Quem abriu.
opened_atdatetime
Abertura.
closed_atdatetime
Fechamento. Ausente enquanto aberta.
opening_centsinteger
Troco inicial (fundo de caixa) em centavos.
closing_centsinteger
Dinheiro contado no fechamento. Ausente enquanto aberta.
expected_cash_centsinteger
Dinheiro que deveria haver: abertura + vendas em dinheiro + suprimentos - sangrias. Ausente enquanto aberta.
difference_centsinteger
Quebra de caixa: contado menos esperado (negativo é falta). Ausente enquanto aberta.
statusstring
openclosed
Estado.

Erros: Abrir sessão

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400register_id em branco.{"error":"vendorerp: register_id required"}
400Valor negativo.{"error":"vendorerp: opening_cents must be >= 0"}
400O caixa está inativo.{"error":"register is inactive"}
400O caixa já tem uma sessão aberta.{"error":"register already has an open session"}
404O caixa não existe ou é de outro seller.{"error":"register 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"}

Fechar sessão

Encerra o turno. Você informa o dinheiro que contou na gaveta; a plataforma calcula o que deveria haver (abertura + vendas em dinheiro + suprimentos - sangrias) e grava a diferença, a quebra de caixa. Fechar não pode ser desfeito.

POST/api/v1/vendor/erp/pdv/sessions/{id}/closeSeller

Fecha uma sessão de caixa

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da sessão.

Corpo da requisição

closing_centsintegerobrigatório
Dinheiro contado, em centavos, zero ou mais.

Exemplo de requisição: Fechar sessão

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/pdv/sessions/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10/close" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "closing_cents": 48500
}'

Resposta: Fechar sessão

200Sessão fechada
json
{
  "id": "f403dacc-b763-4866-bf47-a5caee6319f8",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "register_id": "db8100b6-51bf-488e-8d77-810d6e7002b4",
  "register_name": "Caixa 01",
  "opened_by": "b00d3e7c-d5b4-4942-827a-06e2c43645af",
  "opened_at": "2026-10-11T14:30:00Z",
  "opening_cents": 10000,
  "status": "closed",
  "closed_at": "2026-10-11T22:00:00Z",
  "closing_cents": 48500,
  "expected_cash_cents": 49000,
  "difference_cents": -500
}

Campos da resposta

iduuid
Id da sessão.
vendor_iduuid
Seller dono.
register_iduuid
Caixa.
register_namestring
Nome do caixa.
opened_byuuid
Quem abriu.
opened_atdatetime
Abertura.
closed_atdatetime
Fechamento. Ausente enquanto aberta.
opening_centsinteger
Troco inicial (fundo de caixa) em centavos.
closing_centsinteger
Dinheiro contado no fechamento. Ausente enquanto aberta.
expected_cash_centsinteger
Dinheiro que deveria haver: abertura + vendas em dinheiro + suprimentos - sangrias. Ausente enquanto aberta.
difference_centsinteger
Quebra de caixa: contado menos esperado (negativo é falta). Ausente enquanto aberta.
statusstring
openclosed
Estado.

Erros: Fechar sessão

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400Valor negativo.{"error":"vendorerp: closing_cents must be >= 0"}
404A sessão não existe ou já foi fechada.{"error":"open 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"}

Conferir gaveta

Calcula o dinheiro esperado de uma sessão sem fechá-la, para conferir antes do fechamento. Só vendas pagas em cash entram; cartão e PIX não passam pela gaveta. A rota também responde para uma sessão já fechada.

GET/api/v1/vendor/erp/pdv/sessions/{id}/drawerSeller

Prévia do dinheiro esperado na gaveta

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da sessão.

Exemplo de requisição: Conferir gaveta

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

Resposta: Conferir gaveta

200Gaveta
json
{
  "opening_cents": 10000,
  "cash_sales_cents": 35000,
  "supply_cents": 5000,
  "withdrawal_cents": 1000,
  "expected_cash_cents": 49000
}

Campos da resposta

opening_centsinteger
Troco inicial.
cash_sales_centsinteger
Vendas em dinheiro.
supply_centsinteger
Suprimentos.
withdrawal_centsinteger
Sangrias.
expected_cash_centsinteger
Abertura + vendas em dinheiro + suprimentos - sangrias.

Erros: Conferir gaveta

StatusQuandoCorpo
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"}

Veja também

  • Sangria e suprimento
  • Vendas
Anterior
Caixas do PDV
Próxima
Sangria e suprimento
Nesta página
  • Listar sessões
  • Exemplo de requisição: Listar sessões
  • Resposta: Listar sessões
  • Erros: Listar sessões
  • Abrir sessão
  • Exemplo de requisição: Abrir sessão
  • Resposta: Abrir sessão
  • Erros: Abrir sessão
  • Fechar sessão
  • Exemplo de requisição: Fechar sessão
  • Resposta: Fechar sessão
  • Erros: Fechar sessão
  • Conferir gaveta
  • Exemplo de requisição: Conferir gaveta
  • Resposta: Conferir gaveta
  • Erros: Conferir gaveta
  • Veja também