Integration Requirements

To enable smooth and reliable synchronization between Mozrest and the Reservation Management System (RMS), the RMS must support:

A webhook endpoint to receive POS order events from Mozrest.
An endpoint to list venue tables, which Mozrest will use to match POS tables to RMS reservations.

1. Webhook Endpoint for POS Orders

The RMS must expose an HTTPS endpoint to receive pos_order notifications from Mozrest.

Method: POST
Content-Type: application/json
Authentication: Bearer token

1.1 Webhook Header

Authorization: Bearer {api_key}
Content-Type: application/json

1.2 Webhook Payload

Mozrest will send the following payload structure when an order is created, updated, or voided.

Example:

{
  "type": "create",
  "venueId": "your-venue-id",
  "bookingId": "your-booking-id",
  "checkNumber": "98766",
  "partySize": 2,
  "date": 1719599400,
  "status": "OPEN",
  "tables": [
    "28c3ce8b-8c10-4a64-8099-f0dffcc549a8"
  ],
  "openedAt": 1535548784,
  "updatedAt": 1535548784,
  "closedAt": null,
  "voidedAt": null,
  "commercials": {
    "totalAmount": 150.00,
    "tax": 12.00,
    "tip": 20.00,
    "discount": 10.00,
    "prepayment": 0,
    "paymentType": "credit_card"
  },
  "items": [
    {
      "id": 1,
      "name": "Steak",
      "price": 40.00,
      "quantity": 2
    },
    {
      "id": 2,
      "name": "Wine",
      "price": 70.00,
      "quantity": 1
    }
  ]
}

1.3 Field Descriptions

Field	Type	Description
`type`	string	Event type: `create`, `update`, or `void`
`venueId`	string	Unique ID of the venue in the RMS
`bookingId`	string	Unique ID of the booking in the RMS (it might will be `null` on creation)
`checkNumber`	string	Unique identifier of the check/order in the POS
`partySize`	integer	Number of guests on the check
`date`	integer	POS timestamp for the order (UNIX)
`status`	string	Order status: `OPEN`, `CLOSE`, or `VOID`
`tables[]`	array	List of table IDs associated with the order
`openedAt`	integer	POS timestamp when the order was opened
`updatedAt`	integer	POS timestamp when the order was last updated
`closedAt`	integer	POS timestamp when the order was closed (nullable)
`voidedAt`	integer	POS timestamp when the order was voided (nullable)
`commercials.totalAmount`	number	Final amount after tax, tip, discount, etc.
`commercials.tax`	number	Tax value
`commercials.tip`	number	Tip or gratuity
`commercials.discount`	number	Applied discounts
`commercials.prepayment`	number	Amount already prepaid
`commercials.paymentType`	string	Payment method used (`credit_card`, `cash`, `check`, `others`)
`items[]`	array	List of items ordered
`items[].id`	integer	Internal item ID in the POS
`items[].name`	string	Name of the item
`items[].price`	number	Price per unit
`items[].quantity`	integer	Quantity ordered

ℹ️ Webhook retries will be managed with exponential backoff if the endpoint fails to respond.

2. Table Listing Endpoint

Mozrest requires an endpoint from the RMS to retrieve the list of venue tables. This is used during onboarding and for table-matching with POS systems.

Method: GET
Path: /venue/{venueId}/tables
Authentication: Bearer token

2.1 Response Example

[
  {
    "id": "28c3ce8b-8c10-4a64-8099-f0dffcc549a8",
    "name": "001"
  },
  {
    "id": "00f8c6da-3967-4e56-98b9-5ee063b05292",
    "name": "002"
  }
]

2.2 Field Descriptions

Field	Type	Description
`id`	string	Unique table identifier
`name`	string	Human-readable table label

3. Booking & Order Synchronization

Mozrest provides mechanisms for the RMS to keep bookings and POS orders in sync in real time.

3.1 Opening an Order on the POS

To open a POS order (or link an existing open one), the RMS must send a full booking payload to Mozrest.

Webhook Payload Example (from RMS to Mozrest):

{
    "bookingId": "60e890aca5f07b6ee5b950b1",
    "venueId": "60e890aca5f07b6ee5b950b1",
    "partySize": 4,
    "status": "seated",
    "tables": ["28c3ce8b-8c10-4a64-8099-f0dffcc549a8"],
    "date": 1639578600,
    "prepayment": 50.00,
    "contact": {
        "firstname": "John",
        "lastname": "Doe",
        "locale": "en"
    },
    "notes": "I am allergic to peanuts",
    "checks": [
        "ca5f07b6e",
        "5f07b6233"
    ]
}

Effect:

Mozrest will either:

Open a new order in the POS, or
Link the reservation to an existing open order on that table.

3.2 Updating an Existing POS Order

If any information about the reservation changes (e.g. tables, party size), the RMS must re-send the updated payload with the same bookingId.

Mozrest will forward those changes to the POS system.

🧠 Considerations

The RMS is responsible for matching orders to reservations using the bookingId and associated checkNumbers.
Reservations not created via Mozrest must also be sent using the webhook.
The system supports multi-check reservations.