Integration Guide: Sales & Catalog Synchronization

1. Authenticate

Exchange the credentials supplied for the integration for an access token. The login payload is form-encoded, not JSON. Tokens remain valid for 24 hours, or 14 days when rememberMe=true.

rememberMe=false
username=integration@example.com
password=YOUR_SECURE_PASSWORD
grant_type=password

{
  "access_token": "eyJhbGciOiJIUzI1...",
  "token_type": "Bearer",
  "status": 201,
  "code": "token_created",
  "message": "You have successfully logged in.",
  "data": {
    "user": {
      "restaurants": [
        {
          "restaurantId": 2337
        }
      ]
    }
  }
}

Send Authorization: Bearer <access_token> with the order and menu-listing requests below.

2. Extract sales by update time

Use GET /v1/orders for both the initial backfill and recurring synchronization. For incremental jobs, ticketStartDate and ticketEndDate filterlastUpdateDate; startDate and endDate instead filter the original transaction date.

{
  "status": 200,
  "code": "omnichannel_orders_succeed",
  "data": {
    "count": 1,
    "omnichannelOrders": [
      {
        "reportOrderId": 317030553,
        "omnichannelOrderId": "51544449",
        "restaurantId": 2337,
        "status": "PAID",
        "startDate": "2026-08-05T13:58:30.000Z",
        "lastUpdateDate": "2026-08-05T14:02:10.000Z",
        "totalPriceDiscountedWithTaxIncluded": 2790,
        "items": []
      }
    ]
  }
}

3. Make the incremental job recoverable

1. Define a closed extraction window and replay a configurable overlap before the last successful watermark to capture late corrections.
2. Read pages with a fixed limit, beginning at offset=0. Set the next offset to the current offset plus the requested limit, then stop when that next offset is greater than or equal to data.count. Do not advance by omnichannelOrders.length: the count and offset apply to source reporting rows before response de-duplication.
3. Upsert each order by reportOrderId and each line by the composite key reportOrderId + itemId.
4. Advance the watermark only after every page, transformation, and target write has succeeded. A failed run must be replayed from the previous successful watermark.

4. Map sales and catalog data

The following mapping is intentionally neutral so it can be applied to a data warehouse, ERP, or product-information system. Keep the API values in their source units until a single, explicit conversion step at the target boundary.

5. Refresh the product catalog

First list the menus accessible to the configured restaurant or brand. Select the menu using your integration configuration (for example a known menu ID and channel), then retrieve its full catalog snapshot.

{
  "status": 200,
  "code": "menu_succeed",
  "message": "You can access these menus.",
  "data": [
    {
      "menuId": 28115,
      "name": "Main Menu",
      "restaurantId": 2337,
      "isActive": true,
      "channels": [
        {
          "channelId": 5
        }
      ]
    }
  ]
}

{
  "status": 200,
  "code": "menu_hash_map_succeed",
  "message": "You can access these menus.",
  "data": {
    "layout": [
      {
        "categoryId": 437731,
        "products": [
          {
            "productId": 5973839
          }
        ]
      }
    ],
    "categories": {
      "437731": {
        "categoryId": 437731,
        "name": "Best sellers"
      }
    },
    "products": {
      "5973839": {
        "productId": 5973839,
        "name": "Menu Duo",
        "price": 2490,
        "vat": 1000,
        "sku": {
          "value": "C24"
        }
      }
    },
    "steps": {
      "2381448": {
        "stepId": 2381448,
        "name": "Choose your pizza"
      }
    }
  }
}

The catalog payload structures are layout, categories, products, and steps. Metadata such as menuId, name, or image may also be present. Categories, products, and steps are hash maps keyed by their IDs; use layout to reconstruct the hierarchy.