Marketplace API Documentation

curl "https://api.resto.isoft4is.net/api/partner/v1/catalog/branches" \
  -H "Authorization: ApiKey <KEY_ID>.<API_SECRET>"

[
  { "id": "<BRANCH_ID>", "name": "Downtown", "isActive": true, "externalLocationId": null }
]

Authorization: ApiKey <KEY_ID>.<API_SECRET>

curl "https://api.resto.isoft4is.net/api/partner/v1/catalog/branches" \
  -H "Authorization: ApiKey <KEY_ID>.<API_SECRET>"

[
  {
    "id": "<BRANCH_ID>",
    "name": "Downtown",
    "isActive": true,
    "externalLocationId": "STORE-4821"
  }
]

{
  "categories": [
    {
      "id": "<CATEGORY_ID>",
      "name": "Burgers",
      "products": [
        {
          "id": "<PRODUCT_ID>",
          "sku": "BRG-001",
          "name": "Classic Cheeseburger",
          "imageUrl": "https://cdn.example.com/products/classic-cheeseburger.jpg",
          "taxCategory": { "rate": 15.0, "isInclusive": true },
          "availability": 0,
          "startingPrice": 8.50,
          "variants": [
            { "id": "<VARIANT_ID>", "sku": "BRG-001-REG", "name": "Regular", "price": 8.50, "compareAtPrice": null, "isDefault": true, "availability": 0 },
            { "id": "<VARIANT_ID_2>", "sku": "BRG-001-LRG", "name": "Large", "price": 10.50, "compareAtPrice": null, "isDefault": false, "availability": 0 }
          ]
        }
      ]
    }
  ],
  "resolvedLanguage": null
}

{
  "id": "<PRODUCT_ID>",
  "sku": "BRG-001",
  "name": "Classic Cheeseburger",
  "imageUrl": "https://cdn.example.com/products/classic-cheeseburger.jpg",
  "taxCategory": { "rate": 15.0, "isInclusive": true },
  "availability": 0,
  "resolvedLanguage": null,
  "variants": [
    {
      "id": "<VARIANT_ID>",
      "sku": "BRG-001-REG",
      "name": "Regular",
      "price": 8.50,
      "compareAtPrice": null,
      "isDefault": true,
      "availability": 0,
      "modifierGroups": [
        {
          "id": "<MODIFIER_GROUP_ID>",
          "name": "Extras",
          "minSelections": 0,
          "maxSelections": 3,
          "isRequired": false,
          "sortOrder": 0,
          "options": [
            {
              "id": "<MODIFIER_OPTION_ID>",
              "name": "Extra Cheese",
              "price": 0.75,
              "isDefault": false,
              "availability": 0,
              "childGroups": []
            }
          ]
        }
      ]
    }
  ]
}

curl "https://api.resto.isoft4is.net/api/partner/v1/catalog/branches/<BRANCH_ID>/products?language=ar" \
  -H "Authorization: ApiKey <KEY_ID>.<API_SECRET>"

curl -X POST "https://api.resto.isoft4is.net/api/partner/v1/orders" \
  -H "Authorization: ApiKey <KEY_ID>.<API_SECRET>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <IDEMPOTENCY_KEY>" \
  -d '{
    "branchId": "<BRANCH_ID>",
    "orderMode": 2,
    "customerName": "Jane Doe",
    "customerPhone": "+15550009999",
    "paymentMethod": 1,
    "lines": [
      { "productId": "<PRODUCT_ID>", "variantId": "<VARIANT_ID>", "quantity": 1, "modifierSelections": [] }
    ],
    "externalOrderId": "your-own-order-id-123"
  }'

curl -X POST "https://api.resto.isoft4is.net/api/partner/v1/orders" \
  -H "Authorization: ApiKey <KEY_ID>.<API_SECRET>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <IDEMPOTENCY_KEY>" \
  -d '{
    "branchId": "<BRANCH_ID>",
    "orderMode": 1,
    "customerName": "Jane Doe",
    "customerPhone": "+15550009999",
    "paymentMethod": 2,
    "lines": [
      { "productId": "<PRODUCT_ID>", "variantId": "<VARIANT_ID>", "quantity": 1, "modifierSelections": [] }
    ],
    "externalOrderId": "your-own-order-id-124",
    "deliveryZoneId": "<DELIVERY_ZONE_ID>",
    "deliveryAddress": {
      "addressLine": "42 Example Rd",
      "latitude": 31.930,
      "longitude": 35.925
    },
    "expectedTotal": 13.00
  }'

{
  "orderId": "<ORDER_ID>",
  "orderNumber": "ORD-20260101-123456789",
  "status": 1,
  "paymentStatus": 1,
  "currencyCode": "USD",
  "subtotal": 10.00,
  "discountTotal": 0,
  "taxTotal": 1.50,
  "deliveryFee": 3.00,
  "serviceFee": 0,
  "grandTotal": 14.50,
  "externalOrderId": "your-own-order-id-124"
}

{
  "status": 409,
  "title": "Conflict",
  "detail": "An order with this externalOrderId already exists for your installation.",
  "code": "tenancy.partner_api.external_order_id_conflict"
}

curl "https://api.resto.isoft4is.net/api/partner/v1/orders/<ORDER_ID>" \
  -H "Authorization: ApiKey <KEY_ID>.<API_SECRET>"

{
  "orderId": "<ORDER_ID>",
  "orderNumber": "ORD-20260101-123456789",
  "status": 1,
  "orderMode": 2,
  "tableNumber": null,
  "customerName": "Jane Doe",
  "customerPhone": "+15550009999",
  "grandTotal": 11.50,
  "currencyCode": "USD",
  "items": [
    { "productName": "Classic Cheeseburger", "variantName": "Regular", "quantity": 1, "lineTotal": 8.50, "modifiers": [] }
  ],
  "deliveryAddress": null,
  "branch": { "name": "Downtown", "address": "1 Main St", "latitude": 31.93, "longitude": 35.92, "externalLocationId": "STORE-4821" },

  "paymentStatus": 1,
  "externalOrderId": "your-own-order-id-123",
  "subtotal": 10.00,
  "discountTotal": 0,
  "taxTotal": 1.50,
  "deliveryFee": 0,
  "serviceFee": 0
}

{
  "orderId": "<ORDER_ID>",
  "orderNumber": "ORD-20260101-123456789",
  "status": 2,
  "orderMode": 1,
  "tableNumber": null,
  "customerName": "Jane Doe",
  "customerPhone": "+15550009999",
  "grandTotal": 14.50,
  "currencyCode": "USD",
  "items": [
    { "productName": "Classic Cheeseburger", "variantName": "Regular", "quantity": 1, "lineTotal": 8.50, "modifiers": [] }
  ],
  "deliveryAddress": { "label": null, "addressLine": "42 Example Rd", "latitude": 31.93, "longitude": 35.925, "instructions": null },
  "branch": { "name": "Downtown", "address": "1 Main St", "latitude": 31.93, "longitude": 35.92, "externalLocationId": "STORE-4821" },

  "paymentStatus": null,
  "externalOrderId": null,
  "subtotal": null,
  "discountTotal": null,
  "taxTotal": null,
  "deliveryFee": null,
  "serviceFee": null
}

curl -X POST "https://api.resto.isoft4is.net/api/partner/v1/orders/<ORDER_ID>/cancel" \
  -H "Authorization: ApiKey <KEY_ID>.<API_SECRET>" \
  -H "Idempotency-Key: <IDEMPOTENCY_KEY>"

{
  "orderId": "<ORDER_ID>",
  "orderNumber": "ORD-20260101-123456789",
  "status": 8,
  "externalOrderId": "your-own-order-id-123"
}

{
  "status": 409,
  "title": "Conflict",
  "detail": "Order '<ORDER_ID>' can no longer be cancelled by its source; its status is 'Accepted'.",
  "code": "tenancy.partner_api.order_not_cancellable",
  "status_detail": { "status": "Accepted" }
}

curl -X POST "https://api.resto.isoft4is.net/api/partner/v1/deliveries/<ORDER_ID>/accept" \
  -H "Authorization: ApiKey <KEY_ID>.<API_SECRET>" \
  -H "Idempotency-Key: <IDEMPOTENCY_KEY>"

{
  "assignmentId": "<ASSIGNMENT_ID>",
  "orderId": "<ORDER_ID>",
  "appInstallationId": "<APP_INSTALLATION_ID>",
  "status": 2,
  "assignedAtUtc": "2026-10-04T12:00:00Z",
  "respondedAtUtc": "2026-10-04T12:00:05Z",
  "driverName": null,
  "driverPhone": null,
  "etaUtc": null,
  "trackingUrl": null
}

curl -X POST "https://api.resto.isoft4is.net/api/partner/v1/deliveries/<ORDER_ID>/reject" \
  -H "Authorization: ApiKey <KEY_ID>.<API_SECRET>" \
  -H "Idempotency-Key: <IDEMPOTENCY_KEY>"

curl -X POST "https://api.resto.isoft4is.net/api/partner/v1/deliveries/<ORDER_ID>/cancel" \
  -H "Authorization: ApiKey <KEY_ID>.<API_SECRET>" \
  -H "Idempotency-Key: <IDEMPOTENCY_KEY>"

curl -X PATCH "https://api.resto.isoft4is.net/api/partner/v1/deliveries/<ORDER_ID>/driver" \
  -H "Authorization: ApiKey <KEY_ID>.<API_SECRET>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <IDEMPOTENCY_KEY>" \
  -d '{ "driverName": "Omar K.", "driverPhone": "+15550001234" }'

curl -X PATCH "https://api.resto.isoft4is.net/api/partner/v1/deliveries/<ORDER_ID>/eta" \
  -H "Authorization: ApiKey <KEY_ID>.<API_SECRET>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <IDEMPOTENCY_KEY>" \
  -d '{ "etaUtc": "2026-10-04T12:35:00Z" }'

curl -X PATCH "https://api.resto.isoft4is.net/api/partner/v1/deliveries/<ORDER_ID>/tracking" \
  -H "Authorization: ApiKey <KEY_ID>.<API_SECRET>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <IDEMPOTENCY_KEY>" \
  -d '{ "trackingUrl": "https://track.example.com/<ORDER_ID>" }'

curl -X PATCH "https://api.resto.isoft4is.net/api/partner/v1/deliveries/<ORDER_ID>/status" \
  -H "Authorization: ApiKey <KEY_ID>.<API_SECRET>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <IDEMPOTENCY_KEY>" \
  -d '{ "targetStatus": 4 }'

{
  "id": "<DELIVERY_ID>",
  "type": "orders.created",
  "version": 1,
  "occurredAt": "2026-10-04T12:00:00Z",
  "data": { "orderId": "<ORDER_ID>", "orderNumber": "ORD-20260101-123456789", "status": "Pending" }
}

HMAC-SHA256(secret, "{unixTimestamp}.{rawRequestBody}")

public static bool VerifyWebhookSignature(
    string webhookSigningSecret, string timestampHeader, byte[] rawBodyBytes, string signatureHeader)
{
    var prefix = Encoding.UTF8.GetBytes(timestampHeader + ".");
    var signedPayload = new byte[prefix.Length + rawBodyBytes.Length];
    Buffer.BlockCopy(prefix, class="docs-tok-number">0, signedPayload, class="docs-tok-number">0, prefix.Length);
    Buffer.BlockCopy(rawBodyBytes, class="docs-tok-number">0, signedPayload, prefix.Length, rawBodyBytes.Length);

    var keyBytes = Encoding.UTF8.GetBytes(webhookSigningSecret);
    var expected = Convert.ToHexString(HMACSHA256.HashData(keyBytes, signedPayload)).ToLowerInvariant();

    var expectedBytes = Encoding.UTF8.GetBytes(expected);
    var actualBytes = Encoding.UTF8.GetBytes(signatureHeader);
    return expectedBytes.Length == actualBytes.Length && CryptographicOperations.FixedTimeEquals(expectedBytes, actualBytes);
}

// IMPORTANT: rawBodyBytes must be the exact bytes read from the request body —
// never a re-serialized JSON object. Read the raw stream before any model binding.

import { createHmac, timingSafeEqual } from "node:crypto";

// IMPORTANT: use the raw request body bytes (e.g. express.raw(), never a re-serialized
// JSON.stringify(req.body)) — re-serializing can silently change byte-for-byte content.
function verifyWebhookSignature(secret: string, timestampHeader: string, rawBody: Buffer, signatureHeader: string): boolean {
  const signedPayload = Buffer.concat([Buffer.from(`${timestampHeader}.`), rawBody]);
  const expected = createHmac("sha256", secret).update(signedPayload).digest("hex");

  const expectedBuf = Buffer.from(expected, "utf8");
  const actualBuf = Buffer.from(signatureHeader, "utf8");
  return expectedBuf.length === actualBuf.length && timingSafeEqual(expectedBuf, actualBuf);
}

import hmac
import hashlib

def verify_webhook_signature(secret: str, timestamp_header: str, raw_body: bytes, signature_header: str) -> bool:
    # IMPORTANT: raw_body must be the exact request bytes (e.g. Flask's request.get_data(),
    # not json.dumps(request.json)) — re-serializing can silently change the byte content.
    signed_payload = f"{timestamp_header}.".encode("utf-8") + raw_body
    expected = hmac.new(secret.encode("utf-8"), signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

# First attempt — network times out before you see the response
curl -X POST "https://api.resto.isoft4is.net/api/partner/v1/orders" \
  -H "Authorization: ApiKey <KEY_ID>.<API_SECRET>" \
  -H "Idempotency-Key: 8f14e45f-ceea-4f3e-9f6f-example" \
  -d '{ "...": "same request body" }'

# Safe retry — SAME key, SAME body: returns the original frozen response, never a duplicate order
curl -X POST "https://api.resto.isoft4is.net/api/partner/v1/orders" \
  -H "Authorization: ApiKey <KEY_ID>.<API_SECRET>" \
  -H "Idempotency-Key: 8f14e45f-ceea-4f3e-9f6f-example" \
  -d '{ "...": "same request body" }'

{
  "status": 403,
  "title": "Forbidden",
  "detail": "Your installation does not have the required scope for this action.",
  "code": "auth.insufficient_scope"
}

async function pollOrderUntilSettled(orderId: string): Promise<void> {
  const SETTLED_STATUSES = new Set([class="docs-tok-number">6, class="docs-tok-number">7, class="docs-tok-number">8]); // Completed, Rejected, Cancelled

  while (true) {
    const response = await fetch(`https://api.resto.isoft4is.net/api/partner/v1/orders/${orderId}`, {
      headers: { Authorization: authHeader },
    });
    const order = await response.json();

    if (SETTLED_STATUSES.has(order.status)) {
      return; // done — update your own system of record
    }

    await new Promise((resolve) => setTimeout(resolve, 15_000)); // poll on your own schedule
  }
}

// 1. Receive + verify the delivery.assigned webhook (see Webhooks above)
app.post("/webhooks/iresto", async (req, res) => {
  if (!verifyWebhookSignature(secret, req.header("X-IResto-Timestamp")!, req.rawBody, req.header("X-IResto-Signature")!)) {
    return res.status(class="docs-tok-number">401).end();
  }

  const envelope = JSON.parse(req.rawBody.toString("utf8"));
  if (envelope.type === "delivery.assigned") {
    await handleDeliveryAssigned(envelope.data.orderId); // enqueue; respond 2xx fast
  }
  res.status(class="docs-tok-number">200).end();
});

// 2. Fetch full order details, then move through the lifecycle
async function handleDeliveryAssigned(orderId: string) {
  const order = await getOrder(orderId); // GET /api/partner/v1/orders/{orderId}

  await acceptDelivery(orderId); // POST /deliveries/{orderId}/accept
  await updateDriver(orderId, "Omar K.", "+15550001234"); // PATCH .../driver
  await updateEta(orderId, new Date(Date.now() + class="docs-tok-number">25 * 60_000).toISOString()); // PATCH .../eta
  await updateTracking(orderId, `https://track.example.com/${orderId}`); // PATCH .../tracking
  await updateStatus(orderId, class="docs-tok-number">4); // PATCH .../status -> InTransit
  // ... driver completes the delivery ...
  await updateStatus(orderId, class="docs-tok-number">5); // PATCH .../status -> Delivered
}