مطوّرو ليتس بيتزاv1.0.0

الأدلة

نحن نتصل بنظامك (الموصّلات)

بدل أن يسأل نظامك عن الطلبات، نرسلها نحن إليه: الموصّل القياسي standard_push يرسل رسالة واحدة ثابتة الشكل لكل طلب. يعمل عندما تكون settings.orders.delivery تساوي connector وsettings.orders.connector تساوي standard_push.

سير العمل#

  1. ليتس بيتزا ← عنوانكرسالة موقّعة لطلب جديدPOST <your URL> · order.created
  2. عنوانكيتحقق من التوقيع ويحفظ الطلب مرة واحدة
  3. عنوانك ← ليتس بيتزا2xx مع رقمك: هذا هو التأكيد{ externalOrderNo, externalReceiptNo }
  4. عنوانك ← نقطة البيع والمطبخيوجّه الطلب إلى الفرع
  5. عنوانك ← ليتس بيتزاالحالاتPOST /partner/v1/orders/{id}/status

الطلب الذي يصلك#

HTTP
POST /your/orders/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: LetsPizza-Connector/1
X-LP-Event: order.created
X-LP-Event-Id: 1042.order.created
Idempotency-Key: 1042.order.created          (the message id, the same on every retry)
X-LP-Timestamp: 1793350800
X-LP-Signature: v1=<64 hex characters>

التوقيع هو توقيع إشعارات Webhook نفسه، بسرّ الموصّل الذي يظهر لك مرة واحدة عند إعداده: التحقق من التوقيع ومتجه الاختبار. امنع التكرار على Idempotency-Key: الرسالة نفسها قد تصلك أكثر من مرة.

PartnerPushMessage
{
  "version": 1,
  "id": "1042.order.created",
  "type": "order.created",
  "occurredAt": "2026-11-19T19:35:02+03:00",
  "partnerId": "ptn_01JD5ZB2",
  "data": {
    "order": {
      "order": {
        "id": "7f3a2c10-5b8e-4d21-9c47-1a2b3c4d5e01",
        "number": "261119-0041",
        "status": "placed",
        "channel": "app",
        "branchId": "28",
        "fulfilment": "delivery",
        "paymentMethod": "cash_on_delivery",
        "catalogVersion": "taker-2026-10-06.5d01b76bc1",
        "lines": [
          {
            "lineIndex": 0,
            "line": {
              "productId": "649",
              "qty": 2,
              "selections": [
                {
                  "groupId": "1362",
                  "optionId": "11836",
                  "qty": 1
                }
              ],
              "source": {
                "experience": "classic"
              }
            },
            "unitPrice": 4200,
            "lineTotal": 8400,
            "snapshot": {
              "names": {
                "ar": "مارقريتا",
                "en": "Margherita Pizza"
              },
              "options": [
                {
                  "groupId": "1362",
                  "optionId": "11836",
                  "names": {
                    "ar": "صلصة طماطم",
                    "en": "Tomato Sauce"
                  },
                  "qty": 1,
                  "price": 0
                }
              ]
            }
          },
          {
            "lineIndex": 1,
            "line": {
              "productId": "740",
              "qty": 2,
              "selections": [],
              "source": {
                "experience": "classic"
              }
            },
            "unitPrice": 600,
            "lineTotal": 1200,
            "snapshot": {
              "names": {
                "ar": "كولا",
                "en": "Coca Cola Can"
              },
              "options": []
            }
          }
        ],
        "subtotal": 9600,
        "discounts": [],
        "discountTotal": 0,
        "deliveryFee": 1800,
        "total": 11400,
        "vat": {
          "rateBps": 1500,
          "amount": 1487,
          "includesDeliveryFee": true
        },
        "cutlery": false,
        "ifUnavailable": "call",
        "delivery": {
          "address": "حي المعذر الشمالي، شارع الأمير سلطان، عمارة 14",
          "details": "الدور الثاني، شقة 5، بجوار الصيدلية",
          "location": {
            "lat": 24.6921,
            "lng": 46.6853
          },
          "contactName": "عبدالله",
          "contactPhone": "+966500000000"
        },
        "createdAt": "2026-11-19T19:30:12+03:00",
        "history": [
          {
            "from": null,
            "to": "placed",
            "at": "2026-11-19T19:30:12+03:00",
            "actor": "customer"
          }
        ]
      },
      "state": "awaiting_ack",
      "ackDueAt": "2026-11-19T19:30:12+03:00",
      "ackedAt": null,
      "externalOrderNo": null,
      "externalReceiptNo": null,
      "external": {
        "branchCode": "string",
        "lines": [
          {
            "lineIndex": 0,
            "code": "string",
            "variant": "string",
            "unit": "string",
            "options": [
              {
                "groupId": "string",
                "optionId": "string",
                "code": "string",
                "variant": "string"
              }
            ]
          }
        ],
        "tenderCode": "string",
        "unmapped": [
          {
            "kind": "branch",
            "ourId": "string"
          }
        ]
      },
      "updatedAt": "2026-11-19T19:30:12+03:00"
    }
  }
}

data.order هو عنصر الطلبات نفسه في سحب الطلبات (PartnerOrder): الطلب، وحالته لديك، وموعد التأكيد.

ردّك#

ردّكما نفعله
2xxتأكيد الاستلام. إن حمل الرد externalOrderNo وexternalReceiptNo نحفظهما ونعرضهما لموظفي الفرع.
408 · 429 · 5xx · انقطاعنعيد المحاولة بتباعد متزايد حتى 8 محاولات، ثم يُعلَّم الإرسال «فاشلاً» ليعيده شخص من لوحة التحكم.
أي 4xx آخررفض من نظامك: لا نعيده، ويظهر للفريق مرفوضاً.
2xx · PartnerPushAnswer
{
  "externalOrderNo": "WEB-ORD-000123",
  "externalReceiptNo": "R-000981"
}

قواعد العنوان والإرسال#

  • يُرسل الطلب من مهمة في الخلفية، فلا ينتظر العميل نظامك أبداً، ولا يتوقف الطلب من الموقع إذا تعطل.
  • أجب خلال مهلة الموصّل (10 ثوانٍ افتراضياً) وأكمل العمل بعد الرد.
  • في الإنتاج يجب أن يكون العنوان https وعاماً، كقواعد عناوين Webhook.
  • بعد الرد ما زلت تبلغ الحالات عبر الواجهة كالمعتاد.

الطلبات المستخدمة#