Cash Register API – cURL Commands for Postman

This document provides a complete reference for the Cash Register module API endpoints, including cURL commands ready to import or use in Postman.

Module Overview

The CashRegisterModule (apps/backend/src/cash-register/cash-register.module.ts) exposes three controllers:

Controller	Base Path	Description
RegisterController	`/registers`	Registers (cash drawers)
CashRegisterSessionController	`/cash-register-sessions`	Sessions, open/close, X/Z reports
CashMovementController	`/cash-movements`	Cash movements (in, out, safe drop, etc.)

Dependencies

DatabaseModule – Data persistence
PdfModule – PDF report generation
SafeModule – Safe association
FirebaseModule – Firebase authentication

Authentication

All endpoints are protected by Firebase authentication:

Header: Authorization: Bearer <firebase-id-token>
Cookie: Firebase ID token can also be sent via cookie

Base URL

Local: {{BASE_URL}} (e.g. http://localhost:4000)
Production: Replace with your deployed backend URL

Enum Reference

CashRegisterSessionStatus

open, closed, reviewed

CashMovementType

cash_in, cash_out, safe_drop, tip_in, tip_out, expense

DiscrepancyReasonCode

rounding, counting_error, missing_change, extra_change, theft, other

1. Registers

Create register

curl -X POST '{{BASE_URL}}/registers' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "businessId": "{{businessId}}",
    "locationId": "{{locationId}}",
    "name": "Register 1",
    "createdBy": "{{userId}}"
  }'

Required: businessId, locationId, name, createdBy
Optional: printerConfig (object), safeId

List registers

curl -X GET '{{BASE_URL}}/registers?businessId={{businessId}}&locationId={{locationId}}&isActive=true' \
  -H 'Authorization: Bearer {token}'

Paginated (requires businessId):

curl -X GET '{{BASE_URL}}/registers?businessId={{businessId}}&locationId={{locationId}}&isActive=true&page=1&size=20' \
  -H 'Authorization: Bearer {token}'

Query params: businessId, locationId, isActive, page, size

Get register by ID

curl -X GET '{{BASE_URL}}/registers/{{registerId}}' \
  -H 'Authorization: Bearer {token}'

Update register

curl -X PATCH '{{BASE_URL}}/registers/{{registerId}}' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated Register 1",
    "printerConfig": {},
    "safeId": "{safeId}"
  }'

Optional body fields: name, printerConfig, safeId, updatedBy

Activate register

curl -X POST '{{BASE_URL}}/registers/{{registerId}}/activate' \
  -H 'Authorization: Bearer {token}'

Deactivate register

curl -X POST '{{BASE_URL}}/registers/{{registerId}}/deactivate' \
  -H 'Authorization: Bearer {token}'

Cannot deactivate a register with an open session.

Delete register

curl -X DELETE '{{BASE_URL}}/registers/{{registerId}}' \
  -H 'Authorization: Bearer {token}'

Cannot delete a register that has existing sessions.

2. Cash Register Sessions

Open session

curl -X POST '{{BASE_URL}}/cash-register-sessions' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "businessId": "{{businessId}}",
    "locationId": "{{locationId}}",
    "registerId": "{{registerId}}",
    "cashierId": "{{userId}}",
    "openingAmount": 100.00,
    "notes": "Morning shift",
    "createdBy": "{{userId}}"
  }'

Required: businessId, locationId, registerId, cashierId, openingAmount, createdBy
Optional: openingCashDenominationBreakdown (object), notes

List sessions

curl -X GET '{{BASE_URL}}/cash-register-sessions?businessId={{businessId}}&locationId={{locationId}}&registerId={{registerId}}&cashierId={{userId}}&status=open' \
  -H 'Authorization: Bearer {token}'

Paginated (requires businessId):

curl -X GET '{{BASE_URL}}/cash-register-sessions?businessId={{businessId}}&locationId={{locationId}}&status=open&page=1&size=20' \
  -H 'Authorization: Bearer {token}'

Query params: businessId, locationId, registerId, cashierId, status, page, size

Search sessions

curl -X GET '{{BASE_URL}}/cash-register-sessions/search?businessId={{businessId}}&locationId={{locationId}}&status=closed&openedFrom=2026-02-01T00:00:00Z&openedTo=2026-02-19T23:59:59Z&page=1&size=20' \
  -H 'Authorization: Bearer {token}'

Required: businessId
Optional: locationId, registerId, cashierId, status, documentNumber, openedFrom, openedTo, page, size

Get session by ID

curl -X GET '{{BASE_URL}}/cash-register-sessions/{{cashRegisterSessionId}}' \
  -H 'Authorization: Bearer {token}'

Close session

curl -X POST '{{BASE_URL}}/cash-register-sessions/{{cashRegisterSessionId}}/close' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "closingAmount": 1250.50,
    "cashDenominationBreakdown": {},
    "discrepancyReasonCode": "rounding",
    "discrepancyNotes": "Minor rounding",
    "managerApprovalUserId": "{managerUserId}",
    "closedBy": "{{userId}}"
  }'

Required: closingAmount, closedBy
Optional: cashDenominationBreakdown, discrepancyReasonCode, discrepancyNotes, managerApprovalUserId

DiscrepancyReasonCode values: rounding, counting_error, missing_change, extra_change, theft, other

Save cash count draft

curl -X POST '{{BASE_URL}}/cash-register-sessions/{{cashRegisterSessionId}}/cash-count/draft' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "cashDenominationBreakdown": {
      "100": 5,
      "50": 2,
      "20": 10
    },
    "savedBy": "{{userId}}"
  }'

Required: cashDenominationBreakdown (object), savedBy

Get session totals (X Report data)

curl -X GET '{{BASE_URL}}/cash-register-sessions/{{cashRegisterSessionId}}/totals' \
  -H 'Authorization: Bearer {token}'

Get X Report (inquiry report, JSON)

curl -X GET '{{BASE_URL}}/cash-register-sessions/{{cashRegisterSessionId}}/x-report' \
  -H 'Authorization: Bearer {token}'

Get X Report PDF

curl -X GET '{{BASE_URL}}/cash-register-sessions/{{cashRegisterSessionId}}/x-report/pdf?pageSize=A4&templateId={templateId}&locationId={{locationId}}&useLocationTemplate=true' \
  -H 'Authorization: Bearer {token}' \
  -o x-report.pdf

Optional query params: pageSize, marginTop, marginRight, marginBottom, marginLeft, printBackground, timeout, templateId, locationId, useLocationTemplate

Get closing report (JSON)

curl -X GET '{{BASE_URL}}/cash-register-sessions/{{cashRegisterSessionId}}/closing-report' \
  -H 'Authorization: Bearer {token}'

Get closing report HTML preview

curl -X GET '{{BASE_URL}}/cash-register-sessions/{{cashRegisterSessionId}}/closing-report/print?templateId={templateId}&locationId={{locationId}}&useLocationTemplate=true' \
  -H 'Authorization: Bearer {token}'

Get closing report PDF

curl -X GET '{{BASE_URL}}/cash-register-sessions/{{cashRegisterSessionId}}/closing-report/pdf?pageSize=A4' \
  -H 'Authorization: Bearer {token}' \
  -o closing-report.pdf

Get closing report PDF as base64 (content)

curl -X GET '{{BASE_URL}}/cash-register-sessions/{{cashRegisterSessionId}}/closing-report/pdf/content?pageSize=A4' \
  -H 'Authorization: Bearer {token}'

Returns JSON with filename, content (base64), mimeType, sizeBytes.

Get Z Report (daily summary, JSON)

curl -X GET '{{BASE_URL}}/cash-register-sessions/z-report?businessId={{businessId}}&locationId={{locationId}}&date=2026-02-19' \
  -H 'Authorization: Bearer {token}'

Required: businessId, locationId, date (YYYY-MM-DD)

Get Z Report PDF

curl -X GET '{{BASE_URL}}/cash-register-sessions/z-report/pdf?businessId={{businessId}}&locationId={{locationId}}&date=2026-02-19' \
  -H 'Authorization: Bearer {token}' \
  -o z-report.pdf

Optional: templateId, useLocationTemplate (true/false)

Get Z Report HTML preview

curl -X GET '{{BASE_URL}}/cash-register-sessions/z-report/print?businessId={{businessId}}&locationId={{locationId}}&date=2026-02-19' \
  -H 'Authorization: Bearer {token}'

3. Cash Movements

Create cash movement

curl -X POST '{{BASE_URL}}/cash-movements' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "businessId": "{{businessId}}",
    "locationId": "{{locationId}}",
    "sessionId": "{{cashRegisterSessionId}}",
    "registerId": "{{registerId}}",
    "type": "cash_in",
    "amount": 50.00,
    "currencyId": "{currencyId}",
    "reason": "Float top-up",
    "notes": "From manager",
    "createdBy": "{{userId}}"
  }'

Required: businessId, locationId, sessionId, registerId, type, amount, currencyId, createdBy
Optional: currencyCode, exchangeRate, reason, notes, approvedBy, safeId

Type values: cash_in, cash_out, safe_drop, tip_in, tip_out, expense

For cash_out exceeding the approval threshold, include approvedBy with manager user ID (or approve via separate endpoint).

Approve cash movement

curl -X POST '{{BASE_URL}}/cash-movements/{movementId}/approve' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "approvedBy": "{{userId}}"
  }'

Only applies to cash_out movements that require manager approval.

List cash movements

curl -X GET '{{BASE_URL}}/cash-movements?businessId={{businessId}}&locationId={{locationId}}&sessionId={{cashRegisterSessionId}}&registerId={{registerId}}' \
  -H 'Authorization: Bearer {token}'

Query params: businessId, locationId, sessionId, registerId

Get cash movement by ID

curl -X GET '{{BASE_URL}}/cash-movements/{movementId}' \
  -H 'Authorization: Bearer {token}'

Postman Setup

Environment variables

Variable	Example	Description
`baseUrl`	`http://localhost:4000`	Backend base URL
`token`	`eyJhbGc...`	Firebase ID token
`businessId`	`uuid`	Business UUID
`locationId`	`uuid`	Location UUID
`registerId`	`uuid`	Register UUID
`sessionId`	`uuid`	Cash register session UUID
`userId`	`uuid`	User UUID (cashier)
`currencyId`	`uuid`	Currency UUID
`safeId`	`uuid`	Safe UUID

Usage in Postman

URL: {{baseUrl}}/registers instead of {{BASE_URL}}/registers
Headers: Authorization: Bearer {{token}}

Obtaining a token

Sign in via the app's auth flow.
Copy the Firebase ID token from DevTools → Application → Cookies or the Authorization header.
Or use a Firebase client SDK: getIdToken() on the current user.

Module Overview​

Dependencies​

Authentication​

Base URL​

Enum Reference​

CashRegisterSessionStatus​

CashMovementType​

DiscrepancyReasonCode​

1. Registers​

Create register​

List registers​

Get register by ID​

Update register​

Activate register​

Deactivate register​

Delete register​

2. Cash Register Sessions​

Open session​

List sessions​

Search sessions​

Get session by ID​

Close session​

Save cash count draft​

Get session totals (X Report data)​

Get X Report (inquiry report, JSON)​

Get X Report PDF​

Get closing report (JSON)​

Get closing report HTML preview​

Get closing report PDF​

Get closing report PDF as base64 (content)​

Get Z Report (daily summary, JSON)​

Get Z Report PDF​

Get Z Report HTML preview​

3. Cash Movements​

Create cash movement​

Approve cash movement​

List cash movements​

Get cash movement by ID​

Postman Setup​

Environment variables​

Usage in Postman​

Obtaining a token​