# Integration Requirements

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

1. A **webhook endpoint** to receive POS order events from Mozrest.
2. 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


```http
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:


```json
{
  "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


```json
[
  {
    "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):


```json
{
    "bookingId": "60e890aca5f07b6ee5b950b1",
    "venueId": "60e890aca5f07b6ee5b950b1",
    "partySize": 4,
    "status": "seated",
    "tables": ["28c3ce8b-8c10-4a64-8099-f0dffcc549a8"],
    "date": 1639578600,
    "prepayment": 50.00,
    "contact": {
        "firstname": "John",
        "lastname": "Doe",
        "email": "john.doe@mail.com",
        "telephone": "34646223399",
        "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 `checkNumber`s.
- Reservations not created via Mozrest must also be sent using the webhook.
- The system supports **multi-check reservations**.