POS Session API

The POS Session API provides endpoints for managing POS (Point of Sale) sessions within a store. Sessions represent active work periods for POS profiles (cashiers).

All POS Session API endpoints require authentication and a valid x-store-id header to identify the store context.

Overview

Each session:

Belongs to one POS profile
Belongs to one store
Has an opening cash amount
Can only have one active (open) session per profile at a time
Sessions can be created, checked, and retrieved via these endpoints

Endpoint Details

Base URL: /pos-session
Content-Type: application/json

Required Headers

Authorization: Bearer <token>
x-store-id: <store_id>

All routes require a valid x-store-id header. A profile can only have one active (open) session at a time.

Entity: POS Session

Field	Type	Description
`id`	`string`	Unique session ID
`openingCash`	`number`	Opening cash amount
`posProfileId`	`string`	Associated POS profile identifier
`storeId`	`string`	Associated store identifier
`posClosingId`	`string \| null`	Associated closing session ID (null if not closed)
`createdAt`	`Date`	Creation timestamp
`updatedAt`	`Date`	Last update timestamp

Create POS Session

POST /pos-session/create-session Starts a new POS session for a specific profile. A profile can only have one active (open) session at a time. Requires Authentication: Bearer token in Authorization header

Required Headers

Key	Value	Required	Description
`x-store-id`	`string`	Yes	The store ID where the session is opened

Request Body

{
  "profileId": "pos_profile_id_here",
  "openningCash": 15000,
  "password": "profile_password"
}

Field	Type	Required	Description
`profileId`	string	Yes	POS profile ID
`openningCash`	number	Yes	Opening cash amount
`password`	string	Yes	Profile password for verification

Success Response

Status Code: 200 OK

{
    "message": "session has been started",
    "success": true,
    "data": [
        {
            "id": "fpj8x9d9od0yiiik2tj5a7sj",
            "posProfileId": "zty59yo3tsz0uv5tacg1i5my",
            "storeId": "y2hmpq2zomqgbycqkuyc2usy",
            "openingCash": 5000,
            "posClosingId": null,
            "createdAt": "2025-11-08T14:02:37.527Z",
            "updatedAt": "2025-11-08T14:02:37.527Z"
        }
    ],
    "hashedPassword": "$2b$10$IFYcfGRzWWbYObdKbBcdc..pKe6SBqMNPwa51AWW7Mn3PCTIHU07C"
}

Response Fields

Response Object

Field	Type	Description
`message`	string	Success message
`success`	boolean	Operation success flag
`data`	array	Array containing the created session object
`hashedPassword`	string	Hashed password (for reference)

Session Object (in data array)

Field	Type	Description
`id`	string	Unique session identifier
`posProfileId`	string	Associated POS profile identifier
`storeId`	string	Associated store identifier
`openingCash`	number	Opening cash amount
`posClosingId`	string \| null	Associated closing session ID (null if not closed)
`createdAt`	string	Creation timestamp (ISO 8601)
`updatedAt`	string	Last update timestamp (ISO 8601)

Possible Errors

Code	Message
400	Profile not found / Missing data / Session already open
401	Invalid password

Example Request

curl -X POST "https://jethings-backend.fly.dev/pos-session/create-session" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-store-id: store_id_here" \
  -d '{
    "profileId": "pos_profile_id_here",
    "openningCash": 15000,
    "password": "profile_password"
  }'

Get Session Status by Profile

GET /pos-session/session-status/:profileId Checks whether a POS profile currently has an open session. Requires Authentication: Bearer token in Authorization header

Required Headers

Key	Value	Required	Description
`x-store-id`	`string`	Yes	The store ID where the session is checked

Path Parameters

Parameter	Type	Required	Description
`profileId`	string	Yes	POS profile ID

Success Response

Status Code: 200 OK When session is open:

{
  "hasOpenSession": true,
  "session": {
    "id": "pos_opening_id",
    "openingCash": 15000,
    "posProfileId": "pos_profile_id_here",
    "storeId": "store_id_here",
    "createdAt": "2025-11-03T12:00:00.000Z"
  }
}

When no session is open:

{
  "hasOpenSession": false,
  "session": null
}

Response Fields

Response Object

Field	Type	Description
`hasOpenSession`	boolean	Whether the profile has an active session
`session`	object	Session object (null if no open session)

Possible Errors

Code	Message
400	Store ID is required

Example Request

curl -X GET "https://jethings-backend.fly.dev/pos-session/session-status/pos_profile_id_here" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-store-id: store_id_here"

Get Current Open Session

GET /pos-session/current-session/:profileId Retrieves the currently active (open) session for a given POS profile. Requires Authentication: Bearer token in Authorization header

Required Headers

Key	Value	Required	Description
`x-store-id`	`string`	Yes	The store ID where the session is located

Path Parameters

Parameter	Type	Required	Description
`profileId`	string	Yes	POS profile ID

Success Response

Status Code: 200 OK When session exists:

{
  "success": true,
  "data": {
    "id": "pos_opening_id",
    "openingCash": 15000,
    "posProfileId": "pos_profile_id_here",
    "storeId": "store_id_here",
    "createdAt": "2025-11-03T12:00:00.000Z"
  }
}

When no session is open:

{
  "success": true,
  "data": null
}

Response Fields

Response Object

Field	Type	Description
`success`	boolean	Operation success flag
`data`	object	Session object (null if no open session)

Possible Errors

Code	Message
400	Store ID is required

Example Request

curl -X GET "https://jethings-backend.fly.dev/pos-session/current-session/pos_profile_id_here" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-store-id: store_id_here"

Get All POS Profiles with Session Status

GET /pos-session/profiles Returns all POS profiles in the store, with a flag indicating if each has an open session. Requires Authentication: Bearer token in Authorization header

Required Headers

Key	Value	Required	Description
`x-store-id`	`string`	Yes	The store ID to retrieve profiles for

Success Response

Status Code: 200 OK

[
    {
        "id": "kilocapkh37c3vj4g5pg6xqr",
        "storeId": "xft1hhwk51bsybiyi2xs9lk3",
        "name": "abdellah",
        "createdAt": "2025-11-03T15:42:55.185Z",
        "updatedAt": "2025-11-03T15:42:55.185Z",
        "openSessionId": "c3ltew83cw90z3xabifrnybm",
        "isOpened": true
    }
]

Response Fields

Profile Object

Field	Type	Description
`id`	string	Unique profile identifier
`name`	string	Profile name
`storeId`	string	Associated store identifier
`createdAt`	string	Creation timestamp (ISO 8601)
`updatedAt`	string	Last update timestamp (ISO 8601)
`openSessionId`	string	ID of the open session (if any)
`isOpened`	boolean	Whether the profile has an active session

Possible Errors

Code	Message
400	Store ID is required

Example Request

curl -X GET "https://jethings-backend.fly.dev/pos-session/profiles" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-store-id: store_id_here"

Summary

Endpoint	Method	Description
`/pos-session/create-session`	`POST`	Start a new POS session
`/pos-session/session-status/:profileId`	`GET`	Check if a profile has an open session
`/pos-session/current-session/:profileId`	`GET`	Get the active session for a profile
`/pos-session/profiles`	`GET`	List profiles with open/closed status

Security & Validation

All routes require a valid x-store-id header
Profile passwords are verified when creating sessions
Only one active session per profile is allowed at a time
Session creation requires profile password verification
Store ID validation prevents unauthorized access

Business Logic

Session Creation

A profile can only have one active (open) session at a time
Opening cash amount is required and validated
Profile password must be verified before session creation
Session is automatically associated with the store from the x-store-id header

Session Status

Status checks return whether a session is currently open
If no session is open, the session object is null
Status is checked per profile within a store context

Profile Listing

All profiles for a store are returned with their session status
The isOpened flag indicates if each profile has an active session
Profiles are returned even if they have no open sessions

Error Responses

Common Error Codes

Code	Description
400	Bad Request - Invalid input or validation
401	Unauthorized - Invalid password

Error Response Format

{
  "message": "Error description",
  "statusCode": 400
}

​POS Session API

​Overview

​Endpoint Details

​Required Headers

​Entity: POS Session

​Create POS Session

​Required Headers

​Request Body

​Success Response

​Response Fields

​Response Object

​Session Object (in data array)

​Possible Errors

​Example Request

​Get Session Status by Profile

​Required Headers

​Path Parameters

​Success Response

​Response Fields

​Response Object

​Possible Errors

​Example Request

​Get Current Open Session

​Required Headers

​Path Parameters

​Success Response

​Response Fields

​Response Object

​Possible Errors

​Example Request

​Get All POS Profiles with Session Status

​Required Headers

​Success Response

​Response Fields

​Profile Object

​Possible Errors

​Example Request

​Summary

​Security & Validation

​Business Logic

​Session Creation

​Session Status

​Profile Listing

​Error Responses

​Common Error Codes

​Error Response Format

POS Session API

Overview

Endpoint Details

Required Headers

Entity: POS Session

Create POS Session

Required Headers

Request Body

Success Response

Response Fields

Response Object

Session Object (in data array)

Possible Errors

Example Request

Get Session Status by Profile

Required Headers

Path Parameters

Success Response

Response Fields

Response Object

Possible Errors

Example Request

Get Current Open Session

Required Headers

Path Parameters

Success Response

Response Fields

Response Object

Possible Errors

Example Request

Get All POS Profiles with Session Status

Required Headers

Success Response

Response Fields

Profile Object

Possible Errors

Example Request

Summary

Security & Validation

Business Logic

Session Creation

Session Status

Profile Listing

Error Responses

Common Error Codes

Error Response Format