POS Service
Overview
The POS Service is used to push point-of-sale transaction data from PMS to external systems. This page provides the actual structure used for the integration.
Request Specification
API Specification
- HTTP Method:
POST - Secure URL Path:
{{external_base_url}}/api/pos
Request Headers
x-api-key:{{api_key}}Authorization token assigned to the connecting system. The API key is provided by GuestPro.Content-Type:application/jsonExplicitly defines the payload structure.
Payload Construction and Schema Definition
Primary Request Body
The root object contains structured data for the transaction header, details, and payments.
| Field | Type | Required | Description |
|---|---|---|---|
header | object | Yes | Metadata and summary details of the transaction. |
detail | array | Yes | List of line items in the transaction. |
payment | array | Yes | List of payments made for the transaction. |
Header Object (header)
| Field | Type | Description | Example |
|---|---|---|---|
id | string | Unique identifier for the transaction. | a4aa4cf0-32f9-11f1-a0cd-d58d1e81a220 |
invoice_no | string | Human-readable invoice number. | 1629 |
transaction_date | string | Date of the transaction (YYYY-MM-DD). | 2025-09-10 |
customer_id | string | Unique identifier for the customer. | 36810de0-5e42-11ec-b15c-773ef578a258 |
reservation_folio_id | string | null | ID of the reservation folio if applicable. | null |
payment_mode | string | Mode of payment. | PAY_IN_POS |
payment_due_date | string | null | Due date for the payment. | null |
payment_by | string | Payment done by (e.g., NONE, COMPANY). | NONE |
agent_id | string | Identifier for the agent handling the transaction. | e0baa5e0-27c2-11ef-8d1c-1f67fd3f7ed5 |
ar_status | string | Account Receivables status. | NONE |
ar_total_paid | number | Total paid towards Account Receivables. | 0 |
total_transaction | number | Total transaction amount. | 133000 |
total_taxes | number | Total tax amount. | 11704.545454545452 |
total_service | number | Total service amount. | 10754.13223140496 |
total_payment | number | Total final amount paid. | 133000 |
total_consigment | number | Total consignment amount. | 573600 |
show_tax_service | string | Flag indicating if tax and service should be shown (e.g., "1"). | "1" |
created_time | string | Time the transaction was created (HH:mm). | 11:18 |
tags | array | Array of string tags associated with the transaction. | [] |
tx_product | object | Extensive details describing the environment of the POS transaction including POS info, sales type, agent, etc. | {...} |
customer | object | Detailed object regarding the target customer, carrying personal and contact information. | {...} |
tx_product Object
| Field | Type | Description | Example |
|---|---|---|---|
id | string | Unique identifier for the tx_product. | a4aa4cf0-32f9-11f1-a0cd-d58d1e81a220 |
transaction_date | string | Date of the transaction. | 2025-09-10 |
company_id | string | Identifier for the company. | 757beb40-3669-11ea-9b7a-a3422e769033 |
created_at | string | Timestamp when the transaction product was created. | 2026-04-08 11:18:41 |
created_by | string | User who created the transaction. | yoga |
updated_at | string | Timestamp when the transaction product was last updated. | 2026-04-08 11:24:58 |
updated_by | string | User who last updated the transaction. | yoga |
deleted_at | string | null | Timestamp when the transaction product was deleted. | null |
deleted_by | string | null | User who deleted the transaction. | null |
invoice_id | string | Associated invoice ID. | a4aa4cf0-32f9-11f1-a0cd-d58d1e81a220 |
pos_id | string | Associated POS identifier. | 2c45e240-3678-11ea-a448-ad984dc06ea3 |
bookeepingrate | number | Bookkeeping exchange rate. | 1 |
remark | string | null | General remarks for the transaction product. | null |
table_no | string | null | Table number if applicable. | null |
is_completed | number | Completion flah (1 for completed). | 1 |
remark_void | string | null | Remarks related to voiding the transaction. | null |
agent_id | string | Agent identifier associated with this transaction. | e0baa5e0-27c2-11ef-8d1c-1f67fd3f7ed5 |
sales_type_id | string | Sales type identifier. | ed7dcd40-1b76-11ec-b355-8365980ed46c |
card_fee | number | Absolute card fee applied. | 0 |
card_fee_pct | number | Percentage of card fee applied. | 0 |
table_map_id | string | null | ID mapping to the table layout. | null |
pax | number | Number of people/pax for the transaction. | 1 |
pos_type | string | Type of the POS. | STANDAR |
shift_id | string | null | Shift identifier. | null |
reference_code | string | null | Associated reference code. | null |
reference_id | string | null | Associated reference ID. | null |
reference_desc | string | null | Reference description. | null |
employee_id | string | null | ID of the employee handling the transaction. | null |
serving_period_id | string | null | ID referring to the serving period. | null |
rounding | number | Amount of rounding applied. | 0 |
rounding_account_id | string | Account ID linked to the rounding. | 75980790-3669-11ea-af8f-f3ca4110793b |
pos | object | Details about the specific point of sale. | {...} |
agent | object | Details about the agent linked to the transaction. | {...} |
sales_type | object | Details about the type of sale and its configuration. | {...} |
tx_product.pos Object
| Field | Type | Description | Example |
|---|---|---|---|
id | string | Unique identifier for the POS. | 2c45e240-3678-11ea-a448-ad984dc06ea3 |
name | string | Name of the POS outlet. | Restaurant |
company_id | string | Company ID owning the POS. | 757beb40-3669-11ea-9b7a-a3422e769033 |
use_table | number | Flag if the POS uses table management (1=yes). | 1 |
description | string | null | POS description. | null |
type | string | Specific mode or type of the POS. | TABLE_MANAGEMENT |
use_employ | number | Flag if the POS uses employees/staff (0=no). | 0 |
show_tax_service | string | Flag controlling visibility of tax and service. | "1" |
use_shift | number | Flag if the POS uses shift management (0=no). | 0 |
rounding | number | Base rounding configuration for the POS. | 0 |
tx_product.agent Object
| Field | Type | Description | Example |
|---|---|---|---|
id | string | Unique agent identifier. | e0baa5e0-27c2-11ef-8d1c-1f67fd3f7ed5 |
name | string | Name of the agent. | House Use |
source_id | string | Source linking identifier. | S_HU |
payment_status | string | Status of payment processing for the agent. | NORMAL |
commission | number | Absolute commission amount. | 0 |
address | string | null | Agent's address. | null |
phone | string | null | Agent's phone number. | null |
email | string | null | Agent's email address. | null |
website | string | null | Agent's website. | null |
company_id | string | Company identifier for the agent. | 757beb40-3669-11ea-9b7a-a3422e769033 |
color | string | Display color code for the agent. | #FFFFFF |
commission_type | string | Strategy used for commission (PERCENT or AMOUNT). | PERCENT |
use_product_commission | number | Flag if agent uses product level commissions (1=yes). | 1 |
product_commission_type | string | Source classification for the product commission. | POS |
sales_type_id | string | null | Specific sales type ID linked to the agent. | null |
is_active | number | Flag if agent is active. | 1 |
tx_product.sales_type Object
| Field | Type | Description | Example |
|---|---|---|---|
id | string | Sales type unique identifier. | ed7dcd40-1b76-11ec-b355-8365980ed46c |
name | string | Name of the sales type. | Member |
company_id | string | Company identifier. | 757beb40-3669-11ea-9b7a-a3422e769033 |
type | string | Categorization format (e.g., AMOUNT). | AMOUNT |
type_value | number | Base value linked to the type calculation. | 0 |
operator | string | Mathematical operator intended for calculation. | - |
system_calculation | string | Describes how calculation evaluates. | MANUAL |
impacted | string | Targets field impacted by this sales type calculation. | DISCOUNT |
taxes_id | string | null | Target tax ID linked. | null |
position | string | null | Visual ordering/position. | null |
no_use_pax | number | Flag defining if pax must not be applied. | 0 |
impacted_commission | string | Evaluation mechanism parameter for commissions. | NET |
customer Object
| Field | Type | Description | Example |
|---|---|---|---|
id | string | Unique customer identifier. | 36810de0-5e42-11ec-b15c-773ef578a258 |
name | string | Customer's full name. | aditya |
address | string | null | Customer's address. | null |
country | string | Customer's country of residence. | Andorra |
province_id | string | null | Province/State identifier. | null |
city_id | string | null | City identifier. | null |
email | string | null | Contact email address. | null |
date_of_birth | string | null | Date of birth. | null |
phone | string | null | Phone number. | null |
notes | string | null | Additional notes relating to customer. | null |
company_id | string | Company the customer is linked to. | 757beb40-3669-11ea-9b7a-a3422e769033 |
identity_no | string | null | ID document number (KTP, Passport, etc). | null |
identity_image | string | null | URI/link to stored ID image. | null |
nationality | string | Nationality. | Afghanistan |
deposit_account_id | string | ID linked to the customer's active deposit account. | 2.1.01.02 |
residence | string | null | Main place of residency information. | null |
prefix_name | string | Prefix for addressing customer (e.g., Mr, Ms). | Mr |
last_name | string | Customer's surname. | putra Bagus |
identity_type | string | null | Type of the ID document provided. | null |
postcode | string | null | Area postal code. | null |
town | string | null | Town name. | null |
profile_picture | string | null | URI/link to profile picture. | null |
is_active | number | Flag if customer is active in PMS (1=active). | 1 |
Detail Object (detail)
| Field | Type | Description | Example |
|---|---|---|---|
id | string | Unique identifier for the item line. | a4b36380-32f9-11f1-b45e-53827812d3fa |
description | string | Description of the product/service. | Jus Strawberry |
name | string | Name of the product/service. | Jus Strawberry |
remark | string | null | Additional notes or remarks for the item. | null |
qty | number | Quantity sold. | 1 |
price | number | Unit price before taxes and service. | 41322.31404958677 |
taxes | number | Tax amount for this item. | 4545.454545454545 |
service | number | Service amount for this item. | 4132.231404958678 |
discount_pct | number | Discount percentage applied. | 0 |
discount | number | Discount amount applied. | 0 |
notes | string | Additional structural notes for the item. | "" |
created_at | string | The datetime when this detail was created. | 2026-04-08 11:18:41 |
index_position | number | The relative index order position. | 0 |
cost | string | The internal cost to the property for the item. | "0" |
is_product_detail_package | number | Indicator if this serves as part of a detailed package product (1 for true, 0 for false). | 0 |
tx_product_package_id | string | Reference ID of parent package if applicable. | "" |
detail | array | Recursive nested detail list. Usually populated if is_product_detail_package is related to packages. | [] |
Payment Object (payment)
| Field | Type | Description | Example |
|---|---|---|---|
id | string | Unique identifier for the payment. | 8506c480-32fa-11f1-b522-73ef3ba7dd48 |
payment_method_name | string | Name of the payment method. | Cash |
total_paid | number | Amount paid. | 133000 |
change | number | Change amount returned. | 0 |
Expected System Responses
Successful Execution
The external system must respond with an HTTP 200 OK or 201 Created.
{
"status": "success",
"message": "POS transaction has been successfully ingested."
}
Failure Execution
When the external system provides a response other than success codes (200, 201), the external system delivers the following error response structure.
{
"status": "error",
"message": "<<error_detail>>"
}
Full Request Body
{
"header": {
"id": "a4aa4cf0-32f9-11f1-a0cd-d58d1e81a220",
"invoice_no": "1629",
"transaction_date": "2025-09-10",
"customer_id": "36810de0-5e42-11ec-b15c-773ef578a258",
"reservation_folio_id": null,
"payment_mode": "PAY_IN_POS",
"payment_due_date": null,
"payment_by": "NONE",
"agent_id": "e0baa5e0-27c2-11ef-8d1c-1f67fd3f7ed5",
"ar_status": "NONE",
"ar_total_paid": 0,
"total_transaction": 133000,
"total_taxes": 11704.545454545452,
"total_service": 10754.13223140496,
"total_payment": 133000,
"total_consigment": 573600,
"show_tax_service": "1",
"created_time": "11:18",
"tags": [],
"tx_product": {
"id": "a4aa4cf0-32f9-11f1-a0cd-d58d1e81a220",
"transaction_date": "2025-09-10",
"company_id": "757beb40-3669-11ea-9b7a-a3422e769033",
"created_at": "2026-04-08 11:18:41",
"created_by": "yoga",
"updated_at": "2026-04-08 11:24:58",
"updated_by": "yoga",
"deleted_at": null,
"deleted_by": null,
"invoice_id": "a4aa4cf0-32f9-11f1-a0cd-d58d1e81a220",
"pos_id": "2c45e240-3678-11ea-a448-ad984dc06ea3",
"bookeepingrate": 1,
"remark": null,
"table_no": null,
"is_completed": 1,
"remark_void": null,
"agent_id": "e0baa5e0-27c2-11ef-8d1c-1f67fd3f7ed5",
"sales_type_id": "ed7dcd40-1b76-11ec-b355-8365980ed46c",
"card_fee": 0,
"card_fee_pct": 0,
"table_map_id": null,
"pax": 1,
"pos_type": "STANDAR",
"shift_id": null,
"reference_code": null,
"reference_id": null,
"reference_desc": null,
"employee_id": null,
"serving_period_id": null,
"rounding": 0,
"rounding_account_id": "75980790-3669-11ea-af8f-f3ca4110793b",
"pos": {
"id": "2c45e240-3678-11ea-a448-ad984dc06ea3",
"name": "Restaurant",
"company_id": "757beb40-3669-11ea-9b7a-a3422e769033",
"use_table": 1,
"description": null,
"type": "TABLE_MANAGEMENT",
"use_employ": 0,
"show_tax_service": "1",
"use_shift": 0,
"rounding": 0
},
"agent": {
"id": "e0baa5e0-27c2-11ef-8d1c-1f67fd3f7ed5",
"name": "House Use",
"source_id": "S_HU",
"payment_status": "NORMAL",
"commission": 0,
"address": null,
"phone": null,
"email": null,
"website": null,
"company_id": "757beb40-3669-11ea-9b7a-a3422e769033",
"color": "#FFFFFF",
"commission_type": "PERCENT",
"use_product_commission": 1,
"product_commission_type": "POS",
"sales_type_id": null,
"is_active": 1
},
"sales_type": {
"id": "ed7dcd40-1b76-11ec-b355-8365980ed46c",
"name": "Member",
"company_id": "757beb40-3669-11ea-9b7a-a3422e769033",
"type": "AMOUNT",
"type_value": 0,
"operator": "-",
"system_calculation": "MANUAL",
"impacted": "DISCOUNT",
"taxes_id": null,
"position": null,
"no_use_pax": 0,
"impacted_commission": "NET"
}
},
"customer": {
"id": "36810de0-5e42-11ec-b15c-773ef578a258",
"name": "aditya",
"address": null,
"country": "Andorra",
"province_id": null,
"city_id": null,
"email": null,
"date_of_birth": null,
"phone": null,
"notes": null,
"company_id": "757beb40-3669-11ea-9b7a-a3422e769033",
"identity_no": null,
"identity_image": null,
"nationality": "Afghanistan",
"deposit_account_id": "2.1.01.02",
"residence": null,
"prefix_name": "Mr",
"last_name": "putra Bagus",
"identity_type": null,
"postcode": null,
"town": null,
"profile_picture": null,
"is_active": 1
}
},
"detail": [
{
"description": "Jus Strawberry",
"name": "Jus Strawberry",
"remark": null,
"qty": 1,
"price": 41322.31404958677,
"taxes": 4545.454545454545,
"service": 4132.231404958678,
"discount_pct": 0,
"discount": 0,
"notes": "",
"created_at": "2026-04-08 11:18:41",
"index_position": 0,
"cost": "0",
"is_product_detail_package": 0,
"tx_product_package_id": "",
"id": "a4b36380-32f9-11f1-b45e-53827812d3fa",
"detail": []
},
{
"description": "Nasi Goreng",
"name": "Nasi Goreng",
"remark": null,
"qty": 1,
"price": 17500,
"taxes": 1250,
"service": 1250,
"discount_pct": 10,
"discount": 2000,
"notes": "",
"created_at": "2026-04-08 11:18:41",
"index_position": 0,
"cost": "3000",
"is_product_detail_package": 0,
"tx_product_package_id": "",
"id": "a4c6c960-32f9-11f1-a51d-197f834fecb9",
"detail": []
},
{
"description": "Ayam Crispy / Extra Pedas",
"name": "Ayam Crispy",
"remark": "Extra Pedas",
"qty": 1,
"price": 24793.388429752064,
"taxes": 2727.272727272727,
"service": 2479.3388429752067,
"discount_pct": 0,
"discount": 0,
"notes": "",
"created_at": "2026-04-08 11:18:41",
"index_position": 0,
"cost": "570600",
"is_product_detail_package": 0,
"tx_product_package_id": "",
"id": "a4d9c070-32f9-11f1-9741-c7cc86638e82",
"detail": []
},
{
"description": "paket option",
"name": "paket option",
"remark": null,
"qty": 1,
"price": 28925.61983471074,
"taxes": 3181.818181818181,
"service": 2892.561983471074,
"discount_pct": 0,
"discount": 0,
"notes": "",
"created_at": "2026-04-08 11:18:41",
"index_position": 0,
"cost": "",
"is_product_detail_package": 0,
"tx_product_package_id": "",
"id": "719fc350-32fa-11f1-a3a2-c766157e3cd2",
"detail": [
{
"description": "2 minuman",
"name": "2 minuman",
"remark": null,
"qty": 2,
"price": 28925.61983471074,
"taxes": 6363.636363636362,
"service": 5785.123966942148,
"discount_pct": 0,
"discount": 0,
"notes": "",
"created_at": "2026-04-08 11:18:41",
"index_position": 0,
"cost": "",
"is_product_detail_package": 0,
"tx_product_package_id": "719fc350-32fa-11f1-a3a2-c766157e3cd2",
"id": "71a722a0-32fa-11f1-a112-f74cc393473e",
"detail": [
{
"description": "coca cola",
"name": "coca cola",
"remark": null,
"qty": 2,
"price": 14462.80991735537,
"taxes": 3181.818181818181,
"service": 2892.561983471074,
"discount_pct": 0,
"discount": 0,
"notes": "",
"created_at": "2026-04-08 11:18:41",
"index_position": 0,
"cost": "0",
"is_product_detail_package": 1,
"tx_product_package_id": "71a722a0-32fa-11f1-a112-f74cc393473e",
"id": "71ad97a0-32fa-11f1-9fda-8d515ef28bdc"
}
]
}
]
}
],
"payment": [
{
"payment_method_name": "Cash",
"total_paid": 133000,
"change": 0,
"id": "8506c480-32fa-11f1-b522-73ef3ba7dd48"
}
]
}