PT EN

Caixa

URL base: $BUSINESS_API

O objecto

idstring · obrigatório
tenant_idstring · obrigatório
cashier_user_idstring · obrigatório
counter_idstring · obrigatório
currencystring · obrigatório
opened_atstring (date-time) · obrigatório
closed_atstring (date-time) · opcional
opening_float_minorinteger (int64) · obrigatório
total_cash_collected_minorinteger (int64) · obrigatório
total_pos_card_minorinteger (int64) · obrigatório
physical_cash_counted_minorinteger (int64) · opcional
cash_variance_minorinteger (int64) · opcional
statusstring · obrigatório

um de open, closed, reconciled

supervisor_user_idstring · opcional
reconciled_atstring (date-time) · opcional
notesstring · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
O objecto
{
  "id": "idx_2xBW8Tr0oR5YsrNoIdzQO7t4Gjn",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "cashier_user_id": "cas_2lLSOpTOoH9i2pBYWFnyGRHEoT7",
  "counter_id": "cou_2uw1pq0Jt8ANJccnPIcJ9Ae7RIk",
  "currency": "MZN",
  "opened_at": "2026-11-19T09:30:00Z",
  "closed_at": "2026-11-19T09:30:00Z",
  "opening_float_minor": 1,
  "total_cash_collected_minor": 125000,
  "total_pos_card_minor": 125000,
  "physical_cash_counted_minor": 1,
  "cash_variance_minor": 1,
  "status": "open",
  "supervisor_user_id": "sup_2Ss1vcYf3QW1jQEDvEChTaUlN6A",
  "reconciled_at": "2026-11-19T09:30:00Z",
  "notes": "Leitura confirmada no local.",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Listar turnos de caixa

Registos

GET /cashier/shifts

Returns a paginated list of cashier shifts in the tenant, filterable by cashier_user_id, counter_id and status (open, closed or reconciled). Each shift carries its opening float, cash collected, counted cash and variance once closed, and the supervisor who reconciled it. Requires cashier:read.

Parâmetros

limitinteger · consulta · opcional

Maximum resources to return (default 20, maximum 100).

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões cashier:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/cashier/shifts" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Success

Abrir um turno de caixa

Registos

POST /cashier/shifts/open

Opens a shift for the calling user at the given counter with an opening cash float, in the tenant currency, and returns it with 201. counter_id is required and opening_float_minor must not be negative; only one open shift per cashier and counter is allowed, so a second one returns 409. Send an Idempotency-Key header (1 to 255 visible ASCII characters) to make retries safe; a reused key with a different request is rejected. A cashier.shift.opened event is emitted. Requires cashier:write.

Parâmetros

Idempotency-Keystring · cabeçalho · opcional

Makes the shift command safe to retry. 1 to 255 visible ASCII characters, scoped to the tenant and endpoint and kept for 7 days. A completed success is stored and returned again with its original status and body, with the response header Idempotent-Replayed: true and no second transition. The same key on a different request (body, path, or caller) is refused with 409 Conflict. A refusal (4xx) or a server error (5xx) is never stored, so the same key can be sent again with the corrected values. Omitting the header keeps the behaviour without retry protection.

Corpo application/json

counter_idstring · opcional
opening_float_minorinteger · opcional

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões cashier:write · Funções: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/cashier/shifts/open" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "counter_id": "cou_2uw1pq0Jt8ANJccnPIcJ9Ae7RIk",
  "opening_float_minor": 1
}'
Resposta 200

Success

Fechar um turno de caixa

Registos

POST /cashier/shifts/close

Count the drawer and close the shift; variance = counted - (float + cash)

Closes a shift by recording the physical cash counted in the drawer; the variance is computed as counted minus (opening float + cash collected). Without shift_id the caller's own open shift is closed. A shift that is not open returns 409, and no open shift returns 404. Send an Idempotency-Key header (1 to 255 visible ASCII characters) so a retry returns the stored result instead of failing; a cashier.shift.closed event is emitted. Requires cashier:write.

Parâmetros

Idempotency-Keystring · cabeçalho · opcional

Makes the shift command safe to retry. 1 to 255 visible ASCII characters, scoped to the tenant and endpoint and kept for 7 days. A completed success is stored and returned again with its original status and body, with the response header Idempotent-Replayed: true and no second transition. The same key on a different request (body, path, or caller) is refused with 409 Conflict. A refusal (4xx) or a server error (5xx) is never stored, so the same key can be sent again with the corrected values. Omitting the header keeps the behaviour without retry protection.

Corpo application/json

shift_idstring · opcional
physical_cash_counted_minorinteger · opcional
notesstring · opcional

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões cashier:write · Funções: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/cashier/shifts/close" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "shift_id": "shi_2YyDVSEZlsg7D4aHDGavnEgbPcU",
  "physical_cash_counted_minor": 1,
  "notes": "Leitura confirmada no local."
}'
Resposta 200

Success

Obter o turno de caixa aberto

Registos

GET /cashier/shifts/current

Returns the calling user's open shift, optionally at one counter given by counter_id. When the caller has no open shift the response is 200 with a null body, not 404, so a till application can decide whether to prompt for opening a shift. Requires cashier:read.

Devolve

200 The caller's open shift, or null when no shift is open

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
cashier_user_idstring · obrigatório
counter_idstring · obrigatório
currencystring · obrigatório
opened_atstring (date-time) · obrigatório
closed_atstring (date-time) · opcional
opening_float_minorinteger (int64) · obrigatório
total_cash_collected_minorinteger (int64) · obrigatório
total_pos_card_minorinteger (int64) · obrigatório
physical_cash_counted_minorinteger (int64) · opcional
cash_variance_minorinteger (int64) · opcional
statusstring · obrigatório

um de open, closed, reconciled

supervisor_user_idstring · opcional
reconciled_atstring (date-time) · opcional
notesstring · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 403

Permissões cashier:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/cashier/shifts/current" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "id": "idx_2xBW8Tr0oR5YsrNoIdzQO7t4Gjn",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "cashier_user_id": "cas_2lLSOpTOoH9i2pBYWFnyGRHEoT7",
  "counter_id": "cou_2uw1pq0Jt8ANJccnPIcJ9Ae7RIk",
  "currency": "MZN",
  "opened_at": "2026-11-19T09:30:00Z",
  "closed_at": "2026-11-19T09:30:00Z",
  "opening_float_minor": 1,
  "total_cash_collected_minor": 125000,
  "total_pos_card_minor": 125000,
  "physical_cash_counted_minor": 1,
  "cash_variance_minor": 1,
  "status": "open",
  "supervisor_user_id": "sup_2Ss1vcYf3QW1jQEDvEChTaUlN6A",
  "reconciled_at": "2026-11-19T09:30:00Z",
  "notes": "Leitura confirmada no local.",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Obter um turno de caixa

Registos

GET /cashier/shifts/{id}

Returns one cashier shift with its counter, cashier, opening float, cash collected, counted cash, variance, notes and its open, close and reconcile timestamps. Returns 404 when the shift is not in this tenant. Requires cashier:read.

Parâmetros

idstring · caminho · obrigatório

Id of the cashier shift (prefix shf).

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões cashier:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/cashier/shifts/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Success

Conferir um turno de caixa

Registos

POST /cashier/shifts/{id}/reconcile

Supervisor sign-off of a closed shift: sets its status to reconciled, records the caller as supervisor with a timestamp, and appends any notes to the shift notes. Only a closed shift can be reconciled; any other status returns 409. Supports an Idempotency-Key header for safe retries. Requires the cashier:supervise permission.

Parâmetros

idstring · caminho · obrigatório

Id of the closed cashier shift to reconcile (prefix shf).

Idempotency-Keystring · cabeçalho · opcional

Makes the shift command safe to retry. 1 to 255 visible ASCII characters, scoped to the tenant and endpoint and kept for 7 days. A completed success is stored and returned again with its original status and body, with the response header Idempotent-Replayed: true and no second transition. The same key on a different request (body, path, or caller) is refused with 409 Conflict. A refusal (4xx) or a server error (5xx) is never stored, so the same key can be sent again with the corrected values. Omitting the header keeps the behaviour without retry protection.

Corpo application/json

notesstring · opcional

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões cashier:supervise · Funções: admin, finance, owner

curl -X POST "$BUSINESS_API/cashier/shifts/{id}/reconcile" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "notes": "Leitura confirmada no local."
}'
Resposta 200

Success