PDV — visão geral

:::info Estado atual O PDV hoje só tem autenticação. Sessão operacional (abrir/fechar terminal), pedidos, cobrança via QR e estornos ainda não existem — fazem parte de uma fase futura (payment intents + QR dinâmico) que depende da Fundação Regional (wallets, ledger) estar completa. Esta página será expandida assim que esses endpoints existirem. :::

O que existe hoje

O PDV é uma conta operacional (operator_type=pdv), criada pela gestão e escopada a um workspace específico. Ver Gestão → Operadores (PDV e caixa) para como a conta é provisionada.

Endpoint	O que faz
POST /v1/auth/pdv/login	Login com o username/senha gerados pela gestão. Seta wallet_pdv_access_token, wallet_pdv_refresh_token, wallet_pdv_csrf_token.
POST /v1/auth/pdv/refresh	Rotaciona o refresh token.
POST /v1/auth/pdv/logout	Revoga a sessão e limpa os cookies wallet_pdv_*.

Exemplo: login

curl

curl -X POST http://127.0.0.1:8787/v1/auth/pdv/login \
  -H "Content-Type: application/json" \
  -d '{ "username": "PDV-00184723", "password": "<senha gerada pela gestão>" }'

JavaScript

const response = await fetch("http://127.0.0.1:8787/v1/auth/pdv/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ username: "PDV-00184723", password: "<senha gerada pela gestão>" }),
});
const session = await response.json();

Python

import requests

response = requests.post(
    "http://127.0.0.1:8787/v1/auth/pdv/login",
    json={"username": "PDV-00184723", "password": "<senha gerada pela gestão>"},
)
session = response.json()

O que o JWT do PDV contém

{
  "sub": "supabase-auth-operator-id",
  "principal_type": "operator",
  "operator_account_id": "operator-uuid",
  "operator_type": "pdv",
  "event_id": "event-uuid",
  "operator_username": "PDV-00184723",
  "operator_description": "Entrada Principal",
  "session_id": "global-session-id",
  "exp": 1784000000
}

operator_description vem null quando a conta não tem descrição cadastrada. Essas duas claims viajam junto pra que o wallet-api consiga gravar quem fez cada operação (recarga, venda) sem precisar consultar o banco global — ver Caixa → extrato.

O event_id já vem no token — o PDV não escolhe/troca de evento depois do login; a conta é imutável quanto a isso (criar uma conta PDV pra outro workspace significa criar outra conta, não mover a existente).

Planejado (ainda não implementado)

• Sessão operacional do terminal (abrir/fechar).
• Criação de pedido e payment intent.
• QR dinâmico para o participante aprovar o pagamento.
• Estorno total/parcial de uma cobrança.
• Consulta das próprias vendas/estornos.