{
  "openapi": "3.1.1",
  "info": {
    "title": "Madar Merchant API",
    "description": "واجهة **مدار** للتجار — ربط متجرك الإلكتروني بإنشاء الطلبات ومتابعتها (server-to-server فقط).\r\n\r\nولّد مفتاحك وأدر الـ Webhook من بوابة المتجر: [ربط API](https://wasselni.naseir.site/Merchant/ApiSettings).\r\n\r\n### المصادقة / Authentication\r\n- أرسل الترويسة `X-Api-Key: mk_live_…` مع كل طلب (ماعدا `GET /api/v1/health`).\r\n- المفتاح سرّ خادم: لا تضعه في JavaScript المتصفح أو تطبيق جوال. HTTPS إلزامي (HTTP → 400 `https_required`).\r\n\r\n### الغلاف الموحّد / Envelope\r\nكل رد: `{ success, data, error, meta, requestId }` + ترويسة `X-Request-Id` (أرسلها للدعم). الأخطاء: `error.code` ثابت إنجليزي للبرمجة، `error.message` عربي للعرض، `error.details` اختيارية. التواريخ UTC بلاحقة `Z`، المبالغ بالشيكل (ILS) بخانتين.\r\n\r\n### حدود الاستخدام / Rate limits\r\n- 120 طلب/دقيقة لكل مفتاح، و300 طلب/دقيقة لكل IP على `/api`.\r\n- `POST /api/v1/webhooks/test`: 5 طلبات/دقيقة لكل مفتاح.\r\n- 20 محاولة مصادقة فاشلة من نفس IP خلال 5 دقائق → 429 `too_many_auth_failures`.\r\n- عند التجاوز: HTTP 429 بكود `rate_limited` وترويسة `Retry-After` (بالثواني) — انتظر ثم أعد المحاولة.\r\n\r\n### منع التكرار / Idempotency\r\nأرسل `externalRef` (رقم طلبك) دائماً: إعادة الإرسال بنفس القيمة تُرجع الطلب الموجود بـ 200 و`meta.replayed=true`. المفتاح يشمل الوضع، فنفس `externalRef` يمكن استخدامه مرة في الوضع الحقيقي ومرة في التجريبي.\r\n\r\n### الوضع التجريبي / Test mode (sandbox)\r\n- مفتاح `mk_test_…` من البوابة يعمل على نفس المسارات تماماً، وكل ما تُنشئه به **طلبات تجريبية** لا تظهر في لوحة التاجر ولا للكباتن ولا في الرحلات أو المالية أو التقارير.\r\n- كل رد وكل حمولة webhook تحمل `livemode`: `true` حقيقي و`false` تجريبي. المفتاح الحقيقي لا يرى الطلبات التجريبية والعكس (404 `order_not_found`).\r\n- `GET /api/v1/me` و`/me/balance` بمفتاح تجريبي: `balance` = 0.00 و`transactions` = [].\r\n- `POST /api/v1/orders/{idOrRef}/simulate` بجسم `{ \"status\": \"processing\" | \"out_for_delivery\" | \"delivered\" | \"returned\" | \"cancelled\" }` ينقل الطلب التجريبي للأمام ويُطلق الـ webhooks — بمفتاح حقيقي 403 `test_mode_only`، وتحرّك غير صالح 409 `invalid_transition`.\r\n\r\n### أكواد الأخطاء / Error codes\r\n| code | HTTP | الرسالة |\r\n|------|------|---------|\r\n| `missing_api_key` | 401 | مفتاح API مفقود — أرسل ترويسة X-Api-Key |\r\n| `invalid_api_key` | 401 | مفتاح API غير صالح أو ملغى |\r\n| `too_many_auth_failures` | 429 | محاولات مصادقة فاشلة كثيرة — حاول لاحقاً |\r\n| `merchant_not_active` | 403 | حساب المتجر غير مفعّل أو موقوف |\r\n| `rate_limited` | 429 | تجاوزت الحد المسموح من الطلبات — حاول بعد قليل |\r\n| `https_required` | 400 | يجب استخدام HTTPS |\r\n| `invalid_json` | 400 | جسم الطلب ليس JSON صالحاً |\r\n| `validation_failed` | 400 | بيانات غير صالحة |\r\n| `payload_too_large` | 413 | حجم الطلب أكبر من المسموح |\r\n| `bulk_empty` | 400 | قائمة الطلبات فارغة |\r\n| `bulk_limit_exceeded` | 400 | الحد الأقصى 100 طلب في الدفعة |\r\n| `zone_required` | 422 | حدّد المنطقة أو أرسل الموقع |\r\n| `zone_not_found` | 422 | المنطقة غير موجودة — راجع GET /zones |\r\n| `zone_not_detected` | 422 | الموقع خارج كل مناطق التوصيل المرسومة — أرسل حقل zone صراحة |\r\n| `invalid_map_url` | 422 | تعذّر استخراج الإحداثيات من رابط الخريطة |\r\n| `invalid_phone` | 422 | رقم الجوال غير صالح — مثال: 0599123456 |\r\n| `order_not_found` | 404 | الطلب غير موجود |\r\n| `order_not_cancellable` | 409 | لا يمكن إلغاء الطلب بعد بدء رحلة الجمع |\r\n| `external_ref_conflict` | 409 | رقم الطلب الخارجي مستخدم لطلب محذوف |\r\n| `test_mode_only` | 403 | هذه العملية متاحة في الوضع التجريبي فقط |\r\n| `invalid_transition` | 409 | لا يمكن نقل الطلب إلى هذه الحالة |\r\n| `webhook_not_configured` | 422 | لم يُضبط رابط Webhook بعد |\r\n| `webhook_disabled` | 422 | الـ Webhook معطّل — فعّله من البوابة |\r\n| `not_found` | 404 | المسار غير موجود |\r\n| `method_not_allowed` | 405 | طريقة HTTP غير مسموحة لهذا المسار |\r\n| `internal_error` | 500 | خطأ داخلي — أرسل requestId للدعم |\r\n| `service_unavailable` | 503 | الخدمة غير متاحة مؤقتاً |\r\n\r\n### الـ Webhooks\r\nأحداث `order.created` و`order.status_changed` و`webhook.test` تُرسل POST JSON إلى رابطك مع الترويسات `X-Madar-Event` و`X-Madar-Event-Id` (لإزالة التكرار) و`X-Madar-Delivery` و`X-Madar-Signature: t={unix},v1={hex}`.\r\n- التحقق: `HMAC-SHA256(secret, \"{t}.{rawBody}\")` بمقارنة زمن ثابت، وارفض ما يزيد عمره عن 5 دقائق.\r\n- ردّ بـ 2xx خلال 10 ثوانٍ؛ غير ذلك يُعاد الإرسال بعد 1د، 5د، 30د، 2س، 12س ثم يُغلق.\r\n- الترتيب غير مضمون: اعتمد `occurredAt` و`data.change.previousStatus`.\r\n\r\n```json\r\n{\n  \"id\": \"9b2f0c1e-6a41-4d6e-8f0d-2c7b1e5a9d33\",\n  \"type\": \"order.status_changed\",\n  \"apiVersion\": \"v1\",\n  \"occurredAt\": \"2026-10-22T16:40:00Z\",\n  \"livemode\": true,\n  \"data\": {\n    \"order\": {\n      \"id\": \"3f6d2a7e-0b51-4c1e-9b0e-7a2d9f1c4e88\",\n      \"refNumber\": \"WP-20261022-4821\",\n      \"externalRef\": \"SHOP-10482\",\n      \"status\": \"delivered\",\n      \"merchantStatus\": \"delivered\",\n      \"merchantStatusLabel\": \"تم التسليم\",\n      \"zone\": \"غزة\",\n      \"paymentType\": \"cod\",\n      \"codAmount\": 80.00,\n      \"deliveryFee\": 5.00,\n      \"returnFee\": 3.00,\n      \"totalCollect\": 80.00,\n      \"codCollectionTarget\": \"captain\",\n      \"updatedAt\": \"2026-10-22T16:40:00Z\",\n      \"trackingUrl\": \"https://madar.ps/Track/Result?q=WP-20261022-4821\"\n    },\n    \"change\": {\n      \"previousStatus\": \"out_for_delivery\",\n      \"previousMerchantStatus\": \"out_for_delivery\",\n      \"merchantStatusChanged\": true\n    }\n  }\n}\r\n```\r\n\r\nMadar merchant API — server-to-server only. Authenticate with the `X-Api-Key` header; every response uses the envelope above and carries `X-Request-Id`.",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://wasselni.naseir.site",
      "description": "Madar"
    }
  ],
  "paths": {
    "/api/v1/health": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "حالة الخدمة / Service health",
        "description": "يفحص الاتصال بقاعدة البيانات؛ 503 service_unavailable إن فشل. لا يكشف تفاصيل البيئة.",
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfHealthDto"
                },
                "example": {
                  "success": true,
                  "data": {
                    "status": "ok",
                    "version": "v1",
                    "time": "2026-10-22T09:15:04Z"
                  },
                  "error": null,
                  "requestId": "0HN7S1Q2K3L4M:00000001"
                }
              }
            }
          },
          "503": {
            "description": "الخدمة غير متاحة / Service unavailable — `service_unavailable`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "service_unavailable": {
                    "summary": "الخدمة غير متاحة مؤقتاً",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "service_unavailable",
                        "message": "الخدمة غير متاحة مؤقتاً",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح / Bad request — `https_required`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "https_required": {
                    "summary": "يجب استخدام HTTPS",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "https_required",
                        "message": "يجب استخدام HTTPS",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "تجاوز الحد — راجع ترويسة Retry-After / Rate limited — see Retry-After — `rate_limited`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "ثوانٍ قبل إعادة المحاولة / Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "rate_limited": {
                    "summary": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "rate_limited",
                        "message": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "خطأ داخلي — أرسل requestId للدعم / Internal error — `internal_error`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "internal_error": {
                    "summary": "خطأ داخلي — أرسل requestId للدعم",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "internal_error",
                        "message": "خطأ داخلي — أرسل requestId للدعم",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/me": {
      "get": {
        "tags": [
          "Merchant"
        ],
        "summary": "بيانات التاجر صاحب المفتاح + الرصيد / Merchant profile and balance",
        "description": "أبسط endpoint لاختبار المصادقة. العملة دائماً ILS. `livemode` يوضّح وضع المفتاح المستخدم؛\r\nبمفتاح `mk_test_` يكون `livemode=false` و`balance=0.00` و`apiKey` للمفتاح التجريبي.",
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfMeDto"
                },
                "example": {
                  "success": true,
                  "data": {
                    "merchantId": "8c1e2f3a-4b5c-6d7e-8f90-a1b2c3d4e5f6",
                    "storeName": "مطبعة شهد",
                    "email": "shahd@print.ps",
                    "phone": "0599-200-100",
                    "zone": "غزة",
                    "status": "active",
                    "balance": 140.00,
                    "currency": "ILS",
                    "livemode": true,
                    "apiKey": {
                      "prefix": "mk_live_7Hq2",
                      "createdAt": "2026-10-22T08:00:00Z",
                      "lastUsedAt": "2026-10-22T09:15:04Z"
                    },
                    "webhook": {
                      "configured": true,
                      "url": "https://shop.example.ps/madar/webhook",
                      "isActive": true,
                      "events": [
                        "order.created",
                        "order.status_changed"
                      ]
                    }
                  },
                  "error": null,
                  "requestId": "0HN7S1Q2K3L4M:00000001"
                }
              }
            }
          },
          "401": {
            "description": "مفتاح API مفقود أو غير صالح / Missing or invalid API key — `missing_api_key`, `invalid_api_key`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "missing_api_key": {
                    "summary": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "missing_api_key",
                        "message": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "invalid_api_key": {
                    "summary": "مفتاح API غير صالح أو ملغى",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "invalid_api_key",
                        "message": "مفتاح API غير صالح أو ملغى",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "حساب المتجر غير مفعّل / Merchant not active — `merchant_not_active`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "merchant_not_active": {
                    "summary": "حساب المتجر غير مفعّل أو موقوف",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "merchant_not_active",
                        "message": "حساب المتجر غير مفعّل أو موقوف",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "تجاوز الحد — راجع ترويسة Retry-After / Rate limited — see Retry-After — `rate_limited`, `too_many_auth_failures`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "ثوانٍ قبل إعادة المحاولة / Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "rate_limited": {
                    "summary": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "rate_limited",
                        "message": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "too_many_auth_failures": {
                    "summary": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "too_many_auth_failures",
                        "message": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح / Bad request — `https_required`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "https_required": {
                    "summary": "يجب استخدام HTTPS",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "https_required",
                        "message": "يجب استخدام HTTPS",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "خطأ داخلي — أرسل requestId للدعم / Internal error — `internal_error`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "internal_error": {
                    "summary": "خطأ داخلي — أرسل requestId للدعم",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "internal_error",
                        "message": "خطأ داخلي — أرسل requestId للدعم",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": [ ]
          }
        ]
      }
    },
    "/api/v1/me/balance": {
      "get": {
        "tags": [
          "Merchant"
        ],
        "summary": "الرصيد وآخر الحركات / Balance and latest transactions",
        "description": "`amount` بإشارته كما هو مخزّن (الخصومات سالبة). `type`: cod_credit, delivery_fee, return_fee,\r\nwithdrawal, adjustment. `hasPendingWithdrawal` = يوجد طلب صرف قيد المراجعة.\r\nبمفتاح تجريبي (`mk_test_`): `balance=0.00` و`transactions=[]` و`hasPendingWithdrawal=false`.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "عدد الحركات 1..100 (افتراضي 20) / Number of transactions",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfBalanceDto"
                },
                "example": {
                  "success": true,
                  "data": {
                    "balance": 140.00,
                    "currency": "ILS",
                    "hasPendingWithdrawal": false,
                    "transactions": [
                      {
                        "type": "delivery_fee",
                        "amount": -5.00,
                        "description": "رسوم توصيل — WP-20261022-4821",
                        "orderRefNumber": "WP-20261022-4821",
                        "createdAt": "2026-10-22T16:40:00Z"
                      },
                      {
                        "type": "cod_credit",
                        "amount": 80.00,
                        "description": "تحصيل COD — WP-20261022-4821",
                        "orderRefNumber": "WP-20261022-4821",
                        "createdAt": "2026-10-22T16:40:00Z"
                      }
                    ]
                  },
                  "error": null,
                  "requestId": "0HN7S1Q2K3L4M:00000001"
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح / Bad request — `https_required`, `validation_failed`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "https_required": {
                    "summary": "يجب استخدام HTTPS",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "https_required",
                        "message": "يجب استخدام HTTPS",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "validation_failed": {
                    "summary": "بيانات غير صالحة",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "validation_failed",
                        "message": "بيانات غير صالحة",
                        "details": {
                          "fields": [
                            {
                              "field": "codAmount",
                              "code": "out_of_range",
                              "message": "مبلغ التحصيل مطلوب ويجب أن يكون أكبر من صفر"
                            },
                            {
                              "field": "recipientPhone",
                              "code": "required",
                              "message": "رقم الجوال مطلوب"
                            }
                          ]
                        }
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "مفتاح API مفقود أو غير صالح / Missing or invalid API key — `missing_api_key`, `invalid_api_key`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "missing_api_key": {
                    "summary": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "missing_api_key",
                        "message": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "invalid_api_key": {
                    "summary": "مفتاح API غير صالح أو ملغى",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "invalid_api_key",
                        "message": "مفتاح API غير صالح أو ملغى",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "حساب المتجر غير مفعّل / Merchant not active — `merchant_not_active`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "merchant_not_active": {
                    "summary": "حساب المتجر غير مفعّل أو موقوف",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "merchant_not_active",
                        "message": "حساب المتجر غير مفعّل أو موقوف",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "تجاوز الحد — راجع ترويسة Retry-After / Rate limited — see Retry-After — `rate_limited`, `too_many_auth_failures`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "ثوانٍ قبل إعادة المحاولة / Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "rate_limited": {
                    "summary": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "rate_limited",
                        "message": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "too_many_auth_failures": {
                    "summary": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "too_many_auth_failures",
                        "message": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "خطأ داخلي — أرسل requestId للدعم / Internal error — `internal_error`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "internal_error": {
                    "summary": "خطأ داخلي — أرسل requestId للدعم",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "internal_error",
                        "message": "خطأ داخلي — أرسل requestId للدعم",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": [ ]
          }
        ]
      }
    },
    "/api/v1/orders": {
      "post": {
        "tags": [
          "Orders"
        ],
        "summary": "إنشاء طلب / Create an order",
        "description": "المنطقة: أرسل `zone` صراحة، أو `latitude`/`longitude`، أو `mapUrl` لتُحسب من حدود المناطق.\r\nالموقع خارج كل المناطق → 422 zone_not_detected.\r\nمنع التكرار: أرسل `externalRef` (رقم طلبك) — إعادة الإرسال بنفس القيمة تُرجع الطلب الموجود\r\nبـ 200 و`meta.replayed=true` وترويسة `Idempotent-Replayed: true` بلا مقارنة المحتوى.\r\nCOD + wasselni_direct (الافتراضي): لا يُسلَّم الطلب حتى تؤكد الإدارة وصول التحويل.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/ApiCreateOrderRequest"
                  }
                ]
              },
              "example": {
                "externalRef": "SHOP-10482",
                "recipientName": "محمد علي حسن",
                "recipientPhone": "+970 599-301-001",
                "address": "حي الرمال، شارع عمر المختار، بجانب البريد",
                "latitude": 31.5235,
                "longitude": 34.4478,
                "paymentType": "cod",
                "codAmount": 80,
                "deliveryFeeTarget": "merchant",
                "codCollectionTarget": "captain",
                "notes": "الاتصال قبل التوصيل"
              }
            },
            "application/*+json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/ApiCreateOrderRequest"
                  }
                ]
              },
              "example": {
                "externalRef": "SHOP-10482",
                "recipientName": "محمد علي حسن",
                "recipientPhone": "+970 599-301-001",
                "address": "حي الرمال، شارع عمر المختار، بجانب البريد",
                "latitude": 31.5235,
                "longitude": 34.4478,
                "paymentType": "cod",
                "codAmount": 80,
                "deliveryFeeTarget": "merchant",
                "codCollectionTarget": "captain",
                "notes": "الاتصال قبل التوصيل"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfOrderDto"
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "3f6d2a7e-0b51-4c1e-9b0e-7a2d9f1c4e88",
                    "refNumber": "WP-20261022-4821",
                    "externalRef": "SHOP-10482",
                    "source": "api",
                    "livemode": true,
                    "status": "pending",
                    "merchantStatus": "pending",
                    "merchantStatusLabel": "انتظار",
                    "recipientName": "محمد علي حسن",
                    "recipientPhone": "0599301001",
                    "address": "حي الرمال، شارع عمر المختار، بجانب البريد",
                    "zone": "غزة",
                    "latitude": 31.5235,
                    "longitude": 34.4478,
                    "paymentType": "cod",
                    "codAmount": 80.00,
                    "deliveryFeeTarget": "merchant",
                    "codCollectionTarget": "captain",
                    "deliveryFee": 5.00,
                    "returnFee": 3.00,
                    "totalCollect": 80.00,
                    "currency": "ILS",
                    "awaitingDirectTransfer": false,
                    "notes": "الاتصال قبل التوصيل",
                    "createdAt": "2026-10-22T09:15:04Z",
                    "updatedAt": "2026-10-22T09:15:04Z",
                    "trackingUrl": "https://madar.ps/Track/Result?q=WP-20261022-4821"
                  },
                  "error": null,
                  "meta": {
                    "replayed": false,
                    "warnings": [
                      "phone_normalized"
                    ]
                  },
                  "requestId": "0HN7S1Q2K3L4M:00000001"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfOrderDto"
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "3f6d2a7e-0b51-4c1e-9b0e-7a2d9f1c4e88",
                    "refNumber": "WP-20261022-4821",
                    "externalRef": "SHOP-10482",
                    "source": "api",
                    "livemode": true,
                    "status": "pending",
                    "merchantStatus": "pending",
                    "merchantStatusLabel": "انتظار",
                    "recipientName": "محمد علي حسن",
                    "recipientPhone": "0599301001",
                    "address": "حي الرمال، شارع عمر المختار، بجانب البريد",
                    "zone": "غزة",
                    "latitude": 31.5235,
                    "longitude": 34.4478,
                    "paymentType": "cod",
                    "codAmount": 80.00,
                    "deliveryFeeTarget": "merchant",
                    "codCollectionTarget": "captain",
                    "deliveryFee": 5.00,
                    "returnFee": 3.00,
                    "totalCollect": 80.00,
                    "currency": "ILS",
                    "awaitingDirectTransfer": false,
                    "notes": "الاتصال قبل التوصيل",
                    "createdAt": "2026-10-22T09:15:04Z",
                    "updatedAt": "2026-10-22T09:15:04Z",
                    "trackingUrl": "https://madar.ps/Track/Result?q=WP-20261022-4821"
                  },
                  "error": null,
                  "meta": {
                    "replayed": true,
                    "warnings": [ ]
                  },
                  "requestId": "0HN7S1Q2K3L4M:00000001"
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح / Bad request — `https_required`, `validation_failed`, `invalid_json`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "https_required": {
                    "summary": "يجب استخدام HTTPS",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "https_required",
                        "message": "يجب استخدام HTTPS",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "validation_failed": {
                    "summary": "بيانات غير صالحة",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "validation_failed",
                        "message": "بيانات غير صالحة",
                        "details": {
                          "fields": [
                            {
                              "field": "codAmount",
                              "code": "out_of_range",
                              "message": "مبلغ التحصيل مطلوب ويجب أن يكون أكبر من صفر"
                            },
                            {
                              "field": "recipientPhone",
                              "code": "required",
                              "message": "رقم الجوال مطلوب"
                            }
                          ]
                        }
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "invalid_json": {
                    "summary": "جسم الطلب ليس JSON صالحاً",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "invalid_json",
                        "message": "جسم الطلب ليس JSON صالحاً",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "مفتاح API مفقود أو غير صالح / Missing or invalid API key — `missing_api_key`, `invalid_api_key`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "missing_api_key": {
                    "summary": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "missing_api_key",
                        "message": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "invalid_api_key": {
                    "summary": "مفتاح API غير صالح أو ملغى",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "invalid_api_key",
                        "message": "مفتاح API غير صالح أو ملغى",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "حساب المتجر غير مفعّل / Merchant not active — `merchant_not_active`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "merchant_not_active": {
                    "summary": "حساب المتجر غير مفعّل أو موقوف",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "merchant_not_active",
                        "message": "حساب المتجر غير مفعّل أو موقوف",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "تعارض / Conflict — `external_ref_conflict`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "external_ref_conflict": {
                    "summary": "رقم الطلب الخارجي مستخدم لطلب محذوف",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "external_ref_conflict",
                        "message": "رقم الطلب الخارجي مستخدم لطلب محذوف",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "حجم الطلب كبير / Payload too large — `payload_too_large`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "payload_too_large": {
                    "summary": "حجم الطلب أكبر من المسموح",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "payload_too_large",
                        "message": "حجم الطلب أكبر من المسموح",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "تعذّرت المعالجة / Unprocessable — `zone_required`, `zone_not_found`, `zone_not_detected`, `invalid_map_url`, `invalid_phone`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "zone_required": {
                    "summary": "حدّد المنطقة أو أرسل الموقع",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "zone_required",
                        "message": "حدّد المنطقة أو أرسل الموقع",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "zone_not_found": {
                    "summary": "المنطقة غير موجودة — راجع GET /zones",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "zone_not_found",
                        "message": "المنطقة غير موجودة — راجع GET /zones",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "zone_not_detected": {
                    "summary": "الموقع خارج كل مناطق التوصيل المرسومة — أرسل حقل zone صراحة",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "zone_not_detected",
                        "message": "الموقع خارج كل مناطق التوصيل المرسومة — أرسل حقل zone صراحة",
                        "details": {
                          "latitude": 31.2001,
                          "longitude": 34.2003
                        }
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "invalid_map_url": {
                    "summary": "تعذّر استخراج الإحداثيات من رابط الخريطة",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "invalid_map_url",
                        "message": "تعذّر استخراج الإحداثيات من رابط الخريطة",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "invalid_phone": {
                    "summary": "رقم الجوال غير صالح — مثال: 0599123456",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "invalid_phone",
                        "message": "رقم الجوال غير صالح — مثال: 0599123456",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "تجاوز الحد — راجع ترويسة Retry-After / Rate limited — see Retry-After — `rate_limited`, `too_many_auth_failures`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "ثوانٍ قبل إعادة المحاولة / Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "rate_limited": {
                    "summary": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "rate_limited",
                        "message": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "too_many_auth_failures": {
                    "summary": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "too_many_auth_failures",
                        "message": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "خطأ داخلي — أرسل requestId للدعم / Internal error — `internal_error`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "internal_error": {
                    "summary": "خطأ داخلي — أرسل requestId للدعم",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "internal_error",
                        "message": "خطأ داخلي — أرسل requestId للدعم",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": [ ]
          }
        ]
      },
      "get": {
        "tags": [
          "Orders"
        ],
        "summary": "قائمة الطلبات / List orders",
        "description": "ترتيب ثابت createdAt تنازلياً، بدون timeline. meta: page, pageSize, total, totalPages.",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "description": "مبسّطة، عدة بفاصلة: pending, processing, out_for_delivery, delivered, returned, cancelled",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "createdAt ≥ from — تاريخ (2026-10-22) أو تاريخ+وقت UTC",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "createdAt ≤ to — التاريخ فقط يشمل اليوم كاملاً",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "externalRef",
            "in": "query",
            "description": "مطابقة تامة لرقم طلبك",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source",
            "in": "query",
            "description": "api | portal | app",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "1..100000 (افتراضي 1)",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "1..100 (افتراضي 20)",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfIReadOnlyListOfOrderDto"
                },
                "example": {
                  "success": true,
                  "data": [
                    {
                      "id": "3f6d2a7e-0b51-4c1e-9b0e-7a2d9f1c4e88",
                      "refNumber": "WP-20261022-4821",
                      "externalRef": "SHOP-10482",
                      "source": "api",
                      "livemode": true,
                      "status": "out_for_delivery",
                      "merchantStatus": "out_for_delivery",
                      "merchantStatusLabel": "في الطريق",
                      "recipientName": "محمد علي حسن",
                      "recipientPhone": "0599301001",
                      "address": "حي الرمال، شارع عمر المختار، بجانب البريد",
                      "zone": "غزة",
                      "latitude": 31.5235,
                      "longitude": 34.4478,
                      "paymentType": "cod",
                      "codAmount": 80.00,
                      "deliveryFeeTarget": "merchant",
                      "codCollectionTarget": "captain",
                      "deliveryFee": 5.00,
                      "returnFee": 3.00,
                      "totalCollect": 80.00,
                      "currency": "ILS",
                      "awaitingDirectTransfer": false,
                      "notes": "الاتصال قبل التوصيل",
                      "createdAt": "2026-10-22T09:15:04Z",
                      "updatedAt": "2026-10-22T09:15:04Z",
                      "trackingUrl": "https://madar.ps/Track/Result?q=WP-20261022-4821"
                    }
                  ],
                  "error": null,
                  "meta": {
                    "page": 1,
                    "pageSize": 20,
                    "total": 1,
                    "totalPages": 1
                  },
                  "requestId": "0HN7S1Q2K3L4M:00000001"
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح / Bad request — `https_required`, `validation_failed`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "https_required": {
                    "summary": "يجب استخدام HTTPS",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "https_required",
                        "message": "يجب استخدام HTTPS",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "validation_failed": {
                    "summary": "بيانات غير صالحة",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "validation_failed",
                        "message": "بيانات غير صالحة",
                        "details": {
                          "fields": [
                            {
                              "field": "codAmount",
                              "code": "out_of_range",
                              "message": "مبلغ التحصيل مطلوب ويجب أن يكون أكبر من صفر"
                            },
                            {
                              "field": "recipientPhone",
                              "code": "required",
                              "message": "رقم الجوال مطلوب"
                            }
                          ]
                        }
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "مفتاح API مفقود أو غير صالح / Missing or invalid API key — `missing_api_key`, `invalid_api_key`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "missing_api_key": {
                    "summary": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "missing_api_key",
                        "message": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "invalid_api_key": {
                    "summary": "مفتاح API غير صالح أو ملغى",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "invalid_api_key",
                        "message": "مفتاح API غير صالح أو ملغى",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "حساب المتجر غير مفعّل / Merchant not active — `merchant_not_active`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "merchant_not_active": {
                    "summary": "حساب المتجر غير مفعّل أو موقوف",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "merchant_not_active",
                        "message": "حساب المتجر غير مفعّل أو موقوف",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "تجاوز الحد — راجع ترويسة Retry-After / Rate limited — see Retry-After — `rate_limited`, `too_many_auth_failures`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "ثوانٍ قبل إعادة المحاولة / Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "rate_limited": {
                    "summary": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "rate_limited",
                        "message": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "too_many_auth_failures": {
                    "summary": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "too_many_auth_failures",
                        "message": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "خطأ داخلي — أرسل requestId للدعم / Internal error — `internal_error`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "internal_error": {
                    "summary": "خطأ داخلي — أرسل requestId للدعم",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "internal_error",
                        "message": "خطأ داخلي — أرسل requestId للدعم",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": [ ]
          }
        ]
      }
    },
    "/api/v1/orders/bulk": {
      "post": {
        "tags": [
          "Orders"
        ],
        "summary": "إنشاء جماعي حتى 100 طلب / Bulk create up to 100 orders",
        "description": "كل عنصر يمر بنفس تحقق POST /orders ويُحفظ مستقلاً — نجاح جزئي ممكن. الرد 200 دائماً عند صحة البنية\r\n(حتى لو فشلت كل العناصر)؛ راجع `summary.failed` و`results[].error`.\r\n`externalRef` يجعل إعادة إرسال الدفعة كاملة آمنة (الموجود يعود `replayed=true`).\r\nحد الجسم 1MB. 0 عناصر → 400 bulk_empty؛ أكثر من 100 → 400 bulk_limit_exceeded.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/BulkCreateRequest"
                  }
                ]
              },
              "example": {
                "orders": [
                  {
                    "externalRef": "SHOP-10483",
                    "recipientName": "سارة خليل",
                    "recipientPhone": "0598123456",
                    "address": "جباليا، شارع الترنس",
                    "zone": "جباليا",
                    "paymentType": "cod",
                    "codAmount": 39,
                    "deliveryFeeTarget": "customer",
                    "codCollectionTarget": "captain"
                  },
                  {
                    "externalRef": "SHOP-10482",
                    "recipientName": "محمد علي حسن",
                    "recipientPhone": "0599301001",
                    "address": "حي الرمال، غزة",
                    "zone": "غزة",
                    "paymentType": "cod",
                    "codAmount": 80
                  },
                  {
                    "externalRef": "SHOP-10484",
                    "recipientName": "أحمد سالم",
                    "recipientPhone": "0569001122",
                    "address": "رفح",
                    "latitude": 31.2001,
                    "longitude": 34.2003,
                    "paymentType": "prepaid",
                    "codAmount": 120
                  }
                ]
              }
            },
            "application/*+json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/BulkCreateRequest"
                  }
                ]
              },
              "example": {
                "orders": [
                  {
                    "externalRef": "SHOP-10483",
                    "recipientName": "سارة خليل",
                    "recipientPhone": "0598123456",
                    "address": "جباليا، شارع الترنس",
                    "zone": "جباليا",
                    "paymentType": "cod",
                    "codAmount": 39,
                    "deliveryFeeTarget": "customer",
                    "codCollectionTarget": "captain"
                  },
                  {
                    "externalRef": "SHOP-10482",
                    "recipientName": "محمد علي حسن",
                    "recipientPhone": "0599301001",
                    "address": "حي الرمال، غزة",
                    "zone": "غزة",
                    "paymentType": "cod",
                    "codAmount": 80
                  },
                  {
                    "externalRef": "SHOP-10484",
                    "recipientName": "أحمد سالم",
                    "recipientPhone": "0569001122",
                    "address": "رفح",
                    "latitude": 31.2001,
                    "longitude": 34.2003,
                    "paymentType": "prepaid",
                    "codAmount": 120
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfBulkResultDto"
                },
                "example": {
                  "success": true,
                  "data": {
                    "summary": {
                      "total": 3,
                      "created": 1,
                      "replayed": 1,
                      "failed": 1
                    },
                    "results": [
                      {
                        "index": 0,
                        "externalRef": "SHOP-10483",
                        "success": true,
                        "replayed": false,
                        "order": {
                          "id": "5a1c7e40-2b6d-4f8e-9c3a-1d2e3f4a5b6c",
                          "refNumber": "WP-20261022-5170",
                          "zone": "جباليا",
                          "deliveryFee": 6.00,
                          "totalCollect": 45.00,
                          "merchantStatus": "pending"
                        },
                        "warnings": [ ]
                      },
                      {
                        "index": 1,
                        "externalRef": "SHOP-10482",
                        "success": true,
                        "replayed": true,
                        "order": {
                          "id": "3f6d2a7e-0b51-4c1e-9b0e-7a2d9f1c4e88",
                          "refNumber": "WP-20261022-4821",
                          "zone": "غزة",
                          "deliveryFee": 5.00,
                          "totalCollect": 80.00,
                          "merchantStatus": "pending"
                        },
                        "warnings": [ ]
                      },
                      {
                        "index": 2,
                        "externalRef": "SHOP-10484",
                        "success": false,
                        "error": {
                          "code": "zone_not_detected",
                          "message": "الموقع خارج كل مناطق التوصيل المرسومة — أرسل حقل zone صراحة",
                          "details": {
                            "latitude": 31.2001,
                            "longitude": 34.2003
                          }
                        }
                      }
                    ]
                  },
                  "error": null,
                  "requestId": "0HN7S1Q2K3L4M:00000001"
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح / Bad request — `https_required`, `validation_failed`, `invalid_json`, `bulk_empty`, `bulk_limit_exceeded`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "https_required": {
                    "summary": "يجب استخدام HTTPS",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "https_required",
                        "message": "يجب استخدام HTTPS",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "validation_failed": {
                    "summary": "بيانات غير صالحة",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "validation_failed",
                        "message": "بيانات غير صالحة",
                        "details": {
                          "fields": [
                            {
                              "field": "codAmount",
                              "code": "out_of_range",
                              "message": "مبلغ التحصيل مطلوب ويجب أن يكون أكبر من صفر"
                            },
                            {
                              "field": "recipientPhone",
                              "code": "required",
                              "message": "رقم الجوال مطلوب"
                            }
                          ]
                        }
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "invalid_json": {
                    "summary": "جسم الطلب ليس JSON صالحاً",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "invalid_json",
                        "message": "جسم الطلب ليس JSON صالحاً",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "bulk_empty": {
                    "summary": "قائمة الطلبات فارغة",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "bulk_empty",
                        "message": "قائمة الطلبات فارغة",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "bulk_limit_exceeded": {
                    "summary": "الحد الأقصى 100 طلب في الدفعة",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "bulk_limit_exceeded",
                        "message": "الحد الأقصى 100 طلب في الدفعة",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "مفتاح API مفقود أو غير صالح / Missing or invalid API key — `missing_api_key`, `invalid_api_key`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "missing_api_key": {
                    "summary": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "missing_api_key",
                        "message": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "invalid_api_key": {
                    "summary": "مفتاح API غير صالح أو ملغى",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "invalid_api_key",
                        "message": "مفتاح API غير صالح أو ملغى",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "حساب المتجر غير مفعّل / Merchant not active — `merchant_not_active`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "merchant_not_active": {
                    "summary": "حساب المتجر غير مفعّل أو موقوف",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "merchant_not_active",
                        "message": "حساب المتجر غير مفعّل أو موقوف",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "حجم الطلب كبير / Payload too large — `payload_too_large`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "payload_too_large": {
                    "summary": "حجم الطلب أكبر من المسموح",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "payload_too_large",
                        "message": "حجم الطلب أكبر من المسموح",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "تجاوز الحد — راجع ترويسة Retry-After / Rate limited — see Retry-After — `rate_limited`, `too_many_auth_failures`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "ثوانٍ قبل إعادة المحاولة / Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "rate_limited": {
                    "summary": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "rate_limited",
                        "message": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "too_many_auth_failures": {
                    "summary": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "too_many_auth_failures",
                        "message": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "خطأ داخلي — أرسل requestId للدعم / Internal error — `internal_error`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "internal_error": {
                    "summary": "خطأ داخلي — أرسل requestId للدعم",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "internal_error",
                        "message": "خطأ داخلي — أرسل requestId للدعم",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": [ ]
          }
        ]
      }
    },
    "/api/v1/orders/{idOrRef}": {
      "get": {
        "tags": [
          "Orders"
        ],
        "summary": "طلب واحد بالمعرّف أو رقم المرجع / Get one order by id or refNumber",
        "description": "يتضمن timeline من سجل الحالات تصاعدياً. طلب لتاجر آخر = 404 order_not_found.",
        "parameters": [
          {
            "name": "idOrRef",
            "in": "path",
            "description": "uuid أو refNumber (WP-…)",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfOrderDto"
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "3f6d2a7e-0b51-4c1e-9b0e-7a2d9f1c4e88",
                    "refNumber": "WP-20261022-4821",
                    "externalRef": "SHOP-10482",
                    "source": "api",
                    "livemode": true,
                    "status": "at_warehouse",
                    "merchantStatus": "processing",
                    "merchantStatusLabel": "قيد التجهيز",
                    "recipientName": "محمد علي حسن",
                    "recipientPhone": "0599301001",
                    "address": "حي الرمال، شارع عمر المختار، بجانب البريد",
                    "zone": "غزة",
                    "latitude": 31.5235,
                    "longitude": 34.4478,
                    "paymentType": "cod",
                    "codAmount": 80.00,
                    "deliveryFeeTarget": "merchant",
                    "codCollectionTarget": "captain",
                    "deliveryFee": 5.00,
                    "returnFee": 3.00,
                    "totalCollect": 80.00,
                    "currency": "ILS",
                    "awaitingDirectTransfer": false,
                    "notes": "الاتصال قبل التوصيل",
                    "createdAt": "2026-10-22T09:15:04Z",
                    "updatedAt": "2026-10-22T09:15:04Z",
                    "trackingUrl": "https://madar.ps/Track/Result?q=WP-20261022-4821",
                    "timeline": [
                      {
                        "status": "pending",
                        "merchantStatus": "pending",
                        "at": "2026-10-22T09:15:04Z"
                      },
                      {
                        "status": "collecting",
                        "merchantStatus": "processing",
                        "at": "2026-10-22T11:02:40Z"
                      },
                      {
                        "status": "at_warehouse",
                        "merchantStatus": "processing",
                        "at": "2026-10-22T13:20:11Z"
                      }
                    ]
                  },
                  "error": null,
                  "requestId": "0HN7S1Q2K3L4M:00000001"
                }
              }
            }
          },
          "401": {
            "description": "مفتاح API مفقود أو غير صالح / Missing or invalid API key — `missing_api_key`, `invalid_api_key`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "missing_api_key": {
                    "summary": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "missing_api_key",
                        "message": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "invalid_api_key": {
                    "summary": "مفتاح API غير صالح أو ملغى",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "invalid_api_key",
                        "message": "مفتاح API غير صالح أو ملغى",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "حساب المتجر غير مفعّل / Merchant not active — `merchant_not_active`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "merchant_not_active": {
                    "summary": "حساب المتجر غير مفعّل أو موقوف",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "merchant_not_active",
                        "message": "حساب المتجر غير مفعّل أو موقوف",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "غير موجود / Not found — `order_not_found`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "order_not_found": {
                    "summary": "الطلب غير موجود",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "order_not_found",
                        "message": "الطلب غير موجود",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "تجاوز الحد — راجع ترويسة Retry-After / Rate limited — see Retry-After — `rate_limited`, `too_many_auth_failures`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "ثوانٍ قبل إعادة المحاولة / Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "rate_limited": {
                    "summary": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "rate_limited",
                        "message": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "too_many_auth_failures": {
                    "summary": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "too_many_auth_failures",
                        "message": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح / Bad request — `https_required`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "https_required": {
                    "summary": "يجب استخدام HTTPS",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "https_required",
                        "message": "يجب استخدام HTTPS",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "خطأ داخلي — أرسل requestId للدعم / Internal error — `internal_error`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "internal_error": {
                    "summary": "خطأ داخلي — أرسل requestId للدعم",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "internal_error",
                        "message": "خطأ داخلي — أرسل requestId للدعم",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": [ ]
          }
        ]
      }
    },
    "/api/v1/orders/{idOrRef}/cancel": {
      "post": {
        "tags": [
          "Orders"
        ],
        "summary": "إلغاء طلب / Cancel an order",
        "description": "قبل بدء رحلة الجمع فقط (pending). ملغى مسبقاً → 200 مع `meta.alreadyCancelled=true`.\r\nأي حالة أخرى → 409 order_not_cancellable مع `details.status`. طلب لتاجر آخر → 404.",
        "parameters": [
          {
            "name": "idOrRef",
            "in": "path",
            "description": "uuid أو refNumber (WP-…)",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "اختياري: `{ \"reason\": \"...\" }` (≤200)",
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/ApiCancelOrderRequest"
                  }
                ]
              },
              "example": {
                "reason": "الزبون ألغى"
              }
            },
            "text/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/ApiCancelOrderRequest"
                  }
                ]
              },
              "example": {
                "reason": "الزبون ألغى"
              }
            },
            "application/*+json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/ApiCancelOrderRequest"
                  }
                ]
              },
              "example": {
                "reason": "الزبون ألغى"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfOrderDto"
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "3f6d2a7e-0b51-4c1e-9b0e-7a2d9f1c4e88",
                    "refNumber": "WP-20261022-4821",
                    "externalRef": "SHOP-10482",
                    "source": "api",
                    "livemode": true,
                    "status": "cancelled",
                    "merchantStatus": "cancelled",
                    "merchantStatusLabel": "ملغي",
                    "recipientName": "محمد علي حسن",
                    "recipientPhone": "0599301001",
                    "address": "حي الرمال، شارع عمر المختار، بجانب البريد",
                    "zone": "غزة",
                    "latitude": 31.5235,
                    "longitude": 34.4478,
                    "paymentType": "cod",
                    "codAmount": 80.00,
                    "deliveryFeeTarget": "merchant",
                    "codCollectionTarget": "captain",
                    "deliveryFee": 5.00,
                    "returnFee": 3.00,
                    "totalCollect": 80.00,
                    "currency": "ILS",
                    "awaitingDirectTransfer": false,
                    "notes": "الاتصال قبل التوصيل",
                    "createdAt": "2026-10-22T09:15:04Z",
                    "updatedAt": "2026-10-22T09:15:04Z",
                    "trackingUrl": "https://madar.ps/Track/Result?q=WP-20261022-4821"
                  },
                  "error": null,
                  "meta": {
                    "alreadyCancelled": false
                  },
                  "requestId": "0HN7S1Q2K3L4M:00000001"
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح / Bad request — `https_required`, `validation_failed`, `invalid_json`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "https_required": {
                    "summary": "يجب استخدام HTTPS",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "https_required",
                        "message": "يجب استخدام HTTPS",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "validation_failed": {
                    "summary": "بيانات غير صالحة",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "validation_failed",
                        "message": "بيانات غير صالحة",
                        "details": {
                          "fields": [
                            {
                              "field": "codAmount",
                              "code": "out_of_range",
                              "message": "مبلغ التحصيل مطلوب ويجب أن يكون أكبر من صفر"
                            },
                            {
                              "field": "recipientPhone",
                              "code": "required",
                              "message": "رقم الجوال مطلوب"
                            }
                          ]
                        }
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "invalid_json": {
                    "summary": "جسم الطلب ليس JSON صالحاً",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "invalid_json",
                        "message": "جسم الطلب ليس JSON صالحاً",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "مفتاح API مفقود أو غير صالح / Missing or invalid API key — `missing_api_key`, `invalid_api_key`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "missing_api_key": {
                    "summary": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "missing_api_key",
                        "message": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "invalid_api_key": {
                    "summary": "مفتاح API غير صالح أو ملغى",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "invalid_api_key",
                        "message": "مفتاح API غير صالح أو ملغى",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "حساب المتجر غير مفعّل / Merchant not active — `merchant_not_active`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "merchant_not_active": {
                    "summary": "حساب المتجر غير مفعّل أو موقوف",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "merchant_not_active",
                        "message": "حساب المتجر غير مفعّل أو موقوف",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "غير موجود / Not found — `order_not_found`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "order_not_found": {
                    "summary": "الطلب غير موجود",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "order_not_found",
                        "message": "الطلب غير موجود",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "تعارض / Conflict — `order_not_cancellable`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "order_not_cancellable": {
                    "summary": "لا يمكن إلغاء الطلب بعد بدء رحلة الجمع",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "order_not_cancellable",
                        "message": "لا يمكن إلغاء الطلب بعد بدء رحلة الجمع",
                        "details": {
                          "status": "collecting"
                        }
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "تجاوز الحد — راجع ترويسة Retry-After / Rate limited — see Retry-After — `rate_limited`, `too_many_auth_failures`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "ثوانٍ قبل إعادة المحاولة / Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "rate_limited": {
                    "summary": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "rate_limited",
                        "message": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "too_many_auth_failures": {
                    "summary": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "too_many_auth_failures",
                        "message": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "حجم الطلب كبير / Payload too large — `payload_too_large`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "payload_too_large": {
                    "summary": "حجم الطلب أكبر من المسموح",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "payload_too_large",
                        "message": "حجم الطلب أكبر من المسموح",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "خطأ داخلي — أرسل requestId للدعم / Internal error — `internal_error`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "internal_error": {
                    "summary": "خطأ داخلي — أرسل requestId للدعم",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "internal_error",
                        "message": "خطأ داخلي — أرسل requestId للدعم",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": [ ]
          }
        ]
      }
    },
    "/api/v1/orders/{idOrRef}/simulate": {
      "post": {
        "tags": [
          "Orders"
        ],
        "summary": "محاكاة حالة طلب تجريبي (الوضع التجريبي فقط) / Simulate a test order status (test mode only)",
        "description": "متاح بمفتاح `mk_test_` فقط — بمفتاح حقيقي → 403 `test_mode_only`.\r\nيُسمح التحرّك للأمام فقط ومن حالة غير نهائية؛ غير ذلك (أو نفس الحالة) → 409 `invalid_transition`\r\nمع `details: { from, to }`. يُرسل `order.status_changed` إلى نفس الـ Webhook بـ `livemode: false`.\r\nبلا رحلات وبلا أي أثر مالي.",
        "parameters": [
          {
            "name": "idOrRef",
            "in": "path",
            "description": "uuid أو refNumber (WP-…) لطلب تجريبي",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "`{ \"status\": \"processing\" | \"out_for_delivery\" | \"delivered\" | \"returned\" | \"cancelled\" }`",
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/ApiSimulateStatusRequest"
                  }
                ]
              },
              "example": {
                "status": "out_for_delivery"
              }
            },
            "text/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/ApiSimulateStatusRequest"
                  }
                ]
              },
              "example": {
                "status": "out_for_delivery"
              }
            },
            "application/*+json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/ApiSimulateStatusRequest"
                  }
                ]
              },
              "example": {
                "status": "out_for_delivery"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfOrderDto"
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "3f6d2a7e-0b51-4c1e-9b0e-7a2d9f1c4e88",
                    "refNumber": "WP-20261022-4821",
                    "externalRef": "SHOP-10482",
                    "source": "api",
                    "livemode": false,
                    "status": "out_for_delivery",
                    "merchantStatus": "out_for_delivery",
                    "merchantStatusLabel": "في الطريق",
                    "recipientName": "محمد علي حسن",
                    "recipientPhone": "0599301001",
                    "address": "حي الرمال، شارع عمر المختار، بجانب البريد",
                    "zone": "غزة",
                    "latitude": 31.5235,
                    "longitude": 34.4478,
                    "paymentType": "cod",
                    "codAmount": 80.00,
                    "deliveryFeeTarget": "merchant",
                    "codCollectionTarget": "captain",
                    "deliveryFee": 5.00,
                    "returnFee": 3.00,
                    "totalCollect": 80.00,
                    "currency": "ILS",
                    "awaitingDirectTransfer": false,
                    "notes": "الاتصال قبل التوصيل",
                    "createdAt": "2026-10-22T09:15:04Z",
                    "updatedAt": "2026-10-22T09:15:04Z",
                    "trackingUrl": "https://madar.ps/Track/Result?q=WP-20261022-4821",
                    "timeline": [
                      {
                        "status": "pending",
                        "merchantStatus": "pending",
                        "at": "2026-10-22T09:15:04Z"
                      },
                      {
                        "status": "at_warehouse",
                        "merchantStatus": "processing",
                        "at": "2026-10-22T09:16:00Z"
                      },
                      {
                        "status": "out_for_delivery",
                        "merchantStatus": "out_for_delivery",
                        "at": "2026-10-22T09:17:30Z"
                      }
                    ]
                  },
                  "error": null,
                  "requestId": "0HN7S1Q2K3L4M:00000001"
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح / Bad request — `https_required`, `validation_failed`, `invalid_json`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "https_required": {
                    "summary": "يجب استخدام HTTPS",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "https_required",
                        "message": "يجب استخدام HTTPS",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "validation_failed": {
                    "summary": "بيانات غير صالحة",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "validation_failed",
                        "message": "بيانات غير صالحة",
                        "details": {
                          "fields": [
                            {
                              "field": "codAmount",
                              "code": "out_of_range",
                              "message": "مبلغ التحصيل مطلوب ويجب أن يكون أكبر من صفر"
                            },
                            {
                              "field": "recipientPhone",
                              "code": "required",
                              "message": "رقم الجوال مطلوب"
                            }
                          ]
                        }
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "invalid_json": {
                    "summary": "جسم الطلب ليس JSON صالحاً",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "invalid_json",
                        "message": "جسم الطلب ليس JSON صالحاً",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "مفتاح API مفقود أو غير صالح / Missing or invalid API key — `missing_api_key`, `invalid_api_key`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "missing_api_key": {
                    "summary": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "missing_api_key",
                        "message": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "invalid_api_key": {
                    "summary": "مفتاح API غير صالح أو ملغى",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "invalid_api_key",
                        "message": "مفتاح API غير صالح أو ملغى",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "حساب المتجر غير مفعّل / Merchant not active — `merchant_not_active`, `test_mode_only`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "merchant_not_active": {
                    "summary": "حساب المتجر غير مفعّل أو موقوف",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "merchant_not_active",
                        "message": "حساب المتجر غير مفعّل أو موقوف",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "test_mode_only": {
                    "summary": "هذه العملية متاحة في الوضع التجريبي فقط",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "test_mode_only",
                        "message": "هذه العملية متاحة في الوضع التجريبي فقط",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "غير موجود / Not found — `order_not_found`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "order_not_found": {
                    "summary": "الطلب غير موجود",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "order_not_found",
                        "message": "الطلب غير موجود",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "تعارض / Conflict — `invalid_transition`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "invalid_transition": {
                    "summary": "لا يمكن نقل الطلب إلى هذه الحالة",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "invalid_transition",
                        "message": "لا يمكن نقل الطلب إلى هذه الحالة",
                        "details": {
                          "from": "delivered",
                          "to": "out_for_delivery"
                        }
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "تجاوز الحد — راجع ترويسة Retry-After / Rate limited — see Retry-After — `rate_limited`, `too_many_auth_failures`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "ثوانٍ قبل إعادة المحاولة / Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "rate_limited": {
                    "summary": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "rate_limited",
                        "message": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "too_many_auth_failures": {
                    "summary": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "too_many_auth_failures",
                        "message": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "حجم الطلب كبير / Payload too large — `payload_too_large`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "payload_too_large": {
                    "summary": "حجم الطلب أكبر من المسموح",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "payload_too_large",
                        "message": "حجم الطلب أكبر من المسموح",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "خطأ داخلي — أرسل requestId للدعم / Internal error — `internal_error`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "internal_error": {
                    "summary": "خطأ داخلي — أرسل requestId للدعم",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "internal_error",
                        "message": "خطأ داخلي — أرسل requestId للدعم",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": [ ]
          }
        ]
      }
    },
    "/api/v1/webhooks/test": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "اختبار الـ Webhook / Send a test event",
        "description": "بلا body. يرسل حدث `webhook.test` موقّعاً إلى رابطك متزامناً (timeout 10 ثوانٍ) ويُسجَّل في سجل التسليم.\r\nيُرجع 200 حتى لو فشل التسليم (`delivered=false` مع `statusCode`/`error`). الحد: 5 طلبات في الدقيقة.",
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfWebhookTestDto"
                },
                "example": {
                  "success": true,
                  "data": {
                    "delivered": true,
                    "statusCode": 200,
                    "durationMs": 184,
                    "error": null
                  },
                  "error": null,
                  "requestId": "0HN7S1Q2K3L4M:00000001"
                }
              }
            }
          },
          "401": {
            "description": "مفتاح API مفقود أو غير صالح / Missing or invalid API key — `missing_api_key`, `invalid_api_key`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "missing_api_key": {
                    "summary": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "missing_api_key",
                        "message": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "invalid_api_key": {
                    "summary": "مفتاح API غير صالح أو ملغى",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "invalid_api_key",
                        "message": "مفتاح API غير صالح أو ملغى",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "حساب المتجر غير مفعّل / Merchant not active — `merchant_not_active`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "merchant_not_active": {
                    "summary": "حساب المتجر غير مفعّل أو موقوف",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "merchant_not_active",
                        "message": "حساب المتجر غير مفعّل أو موقوف",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "تعذّرت المعالجة / Unprocessable — `webhook_not_configured`, `webhook_disabled`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "webhook_not_configured": {
                    "summary": "لم يُضبط رابط Webhook بعد",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "webhook_not_configured",
                        "message": "لم يُضبط رابط Webhook بعد",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "webhook_disabled": {
                    "summary": "الـ Webhook معطّل — فعّله من البوابة",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "webhook_disabled",
                        "message": "الـ Webhook معطّل — فعّله من البوابة",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "تجاوز الحد — راجع ترويسة Retry-After / Rate limited — see Retry-After — `rate_limited`, `too_many_auth_failures`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "ثوانٍ قبل إعادة المحاولة / Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "rate_limited": {
                    "summary": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "rate_limited",
                        "message": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "too_many_auth_failures": {
                    "summary": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "too_many_auth_failures",
                        "message": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح / Bad request — `https_required`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "https_required": {
                    "summary": "يجب استخدام HTTPS",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "https_required",
                        "message": "يجب استخدام HTTPS",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "خطأ داخلي — أرسل requestId للدعم / Internal error — `internal_error`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "internal_error": {
                    "summary": "خطأ داخلي — أرسل requestId للدعم",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "internal_error",
                        "message": "خطأ داخلي — أرسل requestId للدعم",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": [ ]
          }
        ]
      }
    },
    "/api/v1/zones": {
      "get": {
        "tags": [
          "Zones"
        ],
        "summary": "كل مناطق التوصيل ورسومها / All delivery zones with fees",
        "description": "`name` هو القيمة التي تُرسل في حقل `zone` عند إنشاء الطلب. `hasBoundary=false` يعني أن\r\nالمنطقة لا تُكتشف من الإحداثيات — أرسل اسمها صراحة.",
        "parameters": [
          {
            "name": "includeBoundary",
            "in": "query",
            "description": "true = إرفاق حدود GeoJSON Polygon ([lng,lat]) للمناطق المرسومة",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfIReadOnlyListOfZoneDto"
                },
                "example": {
                  "success": true,
                  "data": [
                    {
                      "name": "النصيرات",
                      "deliveryFee": 7.00,
                      "returnFee": 4.00,
                      "hasBoundary": false
                    },
                    {
                      "name": "جباليا",
                      "deliveryFee": 6.00,
                      "returnFee": 3.00,
                      "hasBoundary": false
                    },
                    {
                      "name": "خانيونس",
                      "deliveryFee": 7.00,
                      "returnFee": 4.00,
                      "hasBoundary": false
                    },
                    {
                      "name": "غزة",
                      "deliveryFee": 5.00,
                      "returnFee": 3.00,
                      "hasBoundary": true,
                      "boundary": {
                        "type": "Polygon",
                        "coordinates": [
                          [
                            [
                              34.44,
                              31.54
                            ],
                            [
                              34.49,
                              31.54
                            ],
                            [
                              34.49,
                              31.49
                            ],
                            [
                              34.44,
                              31.49
                            ],
                            [
                              34.44,
                              31.54
                            ]
                          ]
                        ]
                      }
                    }
                  ],
                  "error": null,
                  "requestId": "0HN7S1Q2K3L4M:00000001"
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح / Bad request — `https_required`, `validation_failed`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "https_required": {
                    "summary": "يجب استخدام HTTPS",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "https_required",
                        "message": "يجب استخدام HTTPS",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "validation_failed": {
                    "summary": "بيانات غير صالحة",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "validation_failed",
                        "message": "بيانات غير صالحة",
                        "details": {
                          "fields": [
                            {
                              "field": "codAmount",
                              "code": "out_of_range",
                              "message": "مبلغ التحصيل مطلوب ويجب أن يكون أكبر من صفر"
                            },
                            {
                              "field": "recipientPhone",
                              "code": "required",
                              "message": "رقم الجوال مطلوب"
                            }
                          ]
                        }
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "مفتاح API مفقود أو غير صالح / Missing or invalid API key — `missing_api_key`, `invalid_api_key`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "missing_api_key": {
                    "summary": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "missing_api_key",
                        "message": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "invalid_api_key": {
                    "summary": "مفتاح API غير صالح أو ملغى",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "invalid_api_key",
                        "message": "مفتاح API غير صالح أو ملغى",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "حساب المتجر غير مفعّل / Merchant not active — `merchant_not_active`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "merchant_not_active": {
                    "summary": "حساب المتجر غير مفعّل أو موقوف",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "merchant_not_active",
                        "message": "حساب المتجر غير مفعّل أو موقوف",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "تجاوز الحد — راجع ترويسة Retry-After / Rate limited — see Retry-After — `rate_limited`, `too_many_auth_failures`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "ثوانٍ قبل إعادة المحاولة / Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "rate_limited": {
                    "summary": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "rate_limited",
                        "message": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "too_many_auth_failures": {
                    "summary": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "too_many_auth_failures",
                        "message": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "خطأ داخلي — أرسل requestId للدعم / Internal error — `internal_error`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "internal_error": {
                    "summary": "خطأ داخلي — أرسل requestId للدعم",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "internal_error",
                        "message": "خطأ داخلي — أرسل requestId للدعم",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": [ ]
          }
        ]
      }
    },
    "/api/v1/zones/detect": {
      "get": {
        "tags": [
          "Zones"
        ],
        "summary": "اكتشاف المنطقة والرسوم من الإحداثيات / Detect zone and fees from coordinates",
        "description": "نفس خوارزمية الإنشاء — لعرض الرسوم قبل إنشاء الطلب. خارج كل المناطق → 422 zone_not_detected.",
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "description": "خط العرض −90..90 / Latitude",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
              "type": [
                "number",
                "string"
              ],
              "format": "double"
            }
          },
          {
            "name": "lng",
            "in": "query",
            "description": "خط الطول −180..180 / Longitude",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
              "type": [
                "number",
                "string"
              ],
              "format": "double"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfZoneDetectDto"
                },
                "example": {
                  "success": true,
                  "data": {
                    "zone": "غزة",
                    "deliveryFee": 5.00,
                    "returnFee": 3.00
                  },
                  "error": null,
                  "requestId": "0HN7S1Q2K3L4M:00000001"
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح / Bad request — `https_required`, `validation_failed`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "https_required": {
                    "summary": "يجب استخدام HTTPS",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "https_required",
                        "message": "يجب استخدام HTTPS",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "validation_failed": {
                    "summary": "بيانات غير صالحة",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "validation_failed",
                        "message": "بيانات غير صالحة",
                        "details": {
                          "fields": [
                            {
                              "field": "codAmount",
                              "code": "out_of_range",
                              "message": "مبلغ التحصيل مطلوب ويجب أن يكون أكبر من صفر"
                            },
                            {
                              "field": "recipientPhone",
                              "code": "required",
                              "message": "رقم الجوال مطلوب"
                            }
                          ]
                        }
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "مفتاح API مفقود أو غير صالح / Missing or invalid API key — `missing_api_key`, `invalid_api_key`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "missing_api_key": {
                    "summary": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "missing_api_key",
                        "message": "مفتاح API مفقود — أرسل ترويسة X-Api-Key",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "invalid_api_key": {
                    "summary": "مفتاح API غير صالح أو ملغى",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "invalid_api_key",
                        "message": "مفتاح API غير صالح أو ملغى",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "حساب المتجر غير مفعّل / Merchant not active — `merchant_not_active`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "merchant_not_active": {
                    "summary": "حساب المتجر غير مفعّل أو موقوف",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "merchant_not_active",
                        "message": "حساب المتجر غير مفعّل أو موقوف",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "تعذّرت المعالجة / Unprocessable — `zone_not_detected`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "zone_not_detected": {
                    "summary": "الموقع خارج كل مناطق التوصيل المرسومة — أرسل حقل zone صراحة",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "zone_not_detected",
                        "message": "الموقع خارج كل مناطق التوصيل المرسومة — أرسل حقل zone صراحة",
                        "details": {
                          "latitude": 31.2001,
                          "longitude": 34.2003
                        }
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "تجاوز الحد — راجع ترويسة Retry-After / Rate limited — see Retry-After — `rate_limited`, `too_many_auth_failures`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "ثوانٍ قبل إعادة المحاولة / Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "rate_limited": {
                    "summary": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "rate_limited",
                        "message": "تجاوزت الحد المسموح من الطلبات — حاول بعد قليل",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  },
                  "too_many_auth_failures": {
                    "summary": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "too_many_auth_failures",
                        "message": "محاولات مصادقة فاشلة كثيرة — حاول لاحقاً",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "خطأ داخلي — أرسل requestId للدعم / Internal error — `internal_error`",
            "headers": {
              "X-Request-Id": {
                "description": "معرّف الطلب للدعم (= requestId) / Request id for support",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorEnvelope"
                },
                "examples": {
                  "internal_error": {
                    "summary": "خطأ داخلي — أرسل requestId للدعم",
                    "value": {
                      "success": false,
                      "data": null,
                      "error": {
                        "code": "internal_error",
                        "message": "خطأ داخلي — أرسل requestId للدعم",
                        "details": null
                      },
                      "requestId": "0HN7S1Q2K3L4M:00000001"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": [ ]
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ApiCancelOrderRequest": {
        "type": "object",
        "properties": {
          "reason": {
            "examples": [
              "الزبون ألغى"
            ],
            "type": [
              "null",
              "string"
            ],
            "description": "سبب الإلغاء (≤200) — يُسجَّل في سجل الطلب / Cancellation reason (≤200)"
          }
        },
        "description": "جسم إلغاء الطلب (اختياري) / Optional cancel body"
      },
      "ApiCreateOrderRequest": {
        "type": "object",
        "properties": {
          "externalRef": {
            "examples": [
              "SHOP-10482"
            ],
            "type": [
              "null",
              "string"
            ],
            "description": "رقم الطلب في نظامك — مفتاح منع التكرار (≤64، A-Z a-z 0-9 _ - # . /). إعادة الإرسال بنفس القيمة تُرجع الطلب الموجود (200).\r\nYour order number — idempotency key."
          },
          "recipientName": {
            "examples": [
              "محمد علي حسن"
            ],
            "type": [
              "null",
              "string"
            ],
            "description": "اسم المستلم (2–100) / Recipient name"
          },
          "recipientPhone": {
            "examples": [
              "+970 599-301-001"
            ],
            "type": [
              "null",
              "string"
            ],
            "description": "جوال المستلم — يُطبَّع إلى 05XXXXXXXX (+970/972 مقبولة) / Recipient mobile"
          },
          "address": {
            "examples": [
              "حي الرمال، شارع عمر المختار، بجانب البريد"
            ],
            "type": [
              "null",
              "string"
            ],
            "description": "العنوان الوصفي (≤300) / Address text"
          },
          "zone": {
            "examples": [
              "غزة"
            ],
            "type": [
              "null",
              "string"
            ],
            "description": "اسم منطقة موجودة (مطابقة تامة)؛ إن غاب يُحسب من الموقع / Zone name, auto-detected if omitted"
          },
          "latitude": {
            "examples": [
              31.5235
            ],
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
            "type": [
              "null",
              "number",
              "string"
            ],
            "description": "خط العرض −90..90 (مع longitude معاً) / Latitude",
            "format": "double"
          },
          "longitude": {
            "examples": [
              34.4478
            ],
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
            "type": [
              "null",
              "number",
              "string"
            ],
            "description": "خط الطول −180..180 / Longitude",
            "format": "double"
          },
          "mapUrl": {
            "type": [
              "null",
              "string"
            ],
            "description": "رابط واتساب/جوجل ماب (≤500) — يُحلَّل إن غابت الإحداثيات / Map link"
          },
          "paymentType": {
            "examples": [
              "cod"
            ],
            "type": [
              "null",
              "string"
            ],
            "description": "cod | prepaid — نوع التحصيل / Payment type"
          },
          "codAmount": {
            "examples": [
              80
            ],
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "null",
              "number",
              "string"
            ],
            "description": "0.01–99999. COD: قيمة الطلب التي تُحصَّل؛ Prepaid: قيمة إشارية لا تدخل الحسابات.\r\nOrder value (indicative for prepaid).",
            "format": "double"
          },
          "deliveryFeeTarget": {
            "examples": [
              "merchant"
            ],
            "type": [
              "null",
              "string"
            ],
            "description": "merchant (افتراضي) | customer — من يدفع رسوم التوصيل / Who pays delivery fee"
          },
          "codCollectionTarget": {
            "examples": [
              "captain"
            ],
            "type": [
              "null",
              "string"
            ],
            "description": "wasselni_direct (افتراضي) | captain | merchant_pre_collected — من يستلم مبلغ COD (COD فقط؛ يُتجاهل مع prepaid).\r\nwasselni_direct: لا يُسلَّم الطلب حتى تؤكد الإدارة وصول التحويل."
          },
          "notes": {
            "examples": [
              "الاتصال قبل التوصيل"
            ],
            "type": [
              "null",
              "string"
            ],
            "description": "ملاحظات للكابتن (≤500) / Notes"
          }
        },
        "description": "إنشاء طلب عبر الـ API (§6.1) / Create an order via the API.\r\nكل الحقول nullable عمداً — التحقق يتم في ApiCreateOrderValidator\r\nليُرجع validation_failed بأكواد حقول دقيقة."
      },
      "ApiEnvelopeOfBalanceDto": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "هل نجح الطلب / Whether the request succeeded"
          },
          "data": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "البيانات (null عند الفشل) / Payload (null on failure)",
                "$ref": "#/components/schemas/BalanceDto"
              }
            ]
          },
          "error": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "تفاصيل الخطأ (null عند النجاح) / Error details (null on success)",
                "$ref": "#/components/schemas/ApiError"
              }
            ]
          },
          "meta": {
            "description": "معلومات إضافية اختيارية (ترقيم، تحذيرات...) / Optional metadata"
          },
          "requestId": {
            "type": "string",
            "description": "معرّف الطلب للدعم (= ترويسة X-Request-Id) / Request id for support"
          }
        },
        "description": "الغلاف الموحّد لكل ردود الـ API (D8): success / data / error / meta / requestId.\r\nUnified response envelope for every API response."
      },
      "ApiEnvelopeOfBulkResultDto": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "هل نجح الطلب / Whether the request succeeded"
          },
          "data": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "البيانات (null عند الفشل) / Payload (null on failure)",
                "$ref": "#/components/schemas/BulkResultDto"
              }
            ]
          },
          "error": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "تفاصيل الخطأ (null عند النجاح) / Error details (null on success)",
                "$ref": "#/components/schemas/ApiError"
              }
            ]
          },
          "meta": {
            "description": "معلومات إضافية اختيارية (ترقيم، تحذيرات...) / Optional metadata"
          },
          "requestId": {
            "type": "string",
            "description": "معرّف الطلب للدعم (= ترويسة X-Request-Id) / Request id for support"
          }
        },
        "description": "الغلاف الموحّد لكل ردود الـ API (D8): success / data / error / meta / requestId.\r\nUnified response envelope for every API response."
      },
      "ApiEnvelopeOfHealthDto": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "هل نجح الطلب / Whether the request succeeded"
          },
          "data": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "البيانات (null عند الفشل) / Payload (null on failure)",
                "$ref": "#/components/schemas/HealthDto"
              }
            ]
          },
          "error": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "تفاصيل الخطأ (null عند النجاح) / Error details (null on success)",
                "$ref": "#/components/schemas/ApiError"
              }
            ]
          },
          "meta": {
            "description": "معلومات إضافية اختيارية (ترقيم، تحذيرات...) / Optional metadata"
          },
          "requestId": {
            "type": "string",
            "description": "معرّف الطلب للدعم (= ترويسة X-Request-Id) / Request id for support"
          }
        },
        "description": "الغلاف الموحّد لكل ردود الـ API (D8): success / data / error / meta / requestId.\r\nUnified response envelope for every API response."
      },
      "ApiEnvelopeOfIReadOnlyListOfOrderDto": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "هل نجح الطلب / Whether the request succeeded"
          },
          "data": {
            "type": [
              "null",
              "array"
            ],
            "items": {
              "$ref": "#/components/schemas/OrderDto"
            },
            "description": "البيانات (null عند الفشل) / Payload (null on failure)"
          },
          "error": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "تفاصيل الخطأ (null عند النجاح) / Error details (null on success)",
                "$ref": "#/components/schemas/ApiError"
              }
            ]
          },
          "meta": {
            "description": "معلومات إضافية اختيارية (ترقيم، تحذيرات...) / Optional metadata"
          },
          "requestId": {
            "type": "string",
            "description": "معرّف الطلب للدعم (= ترويسة X-Request-Id) / Request id for support"
          }
        },
        "description": "الغلاف الموحّد لكل ردود الـ API (D8): success / data / error / meta / requestId.\r\nUnified response envelope for every API response."
      },
      "ApiEnvelopeOfIReadOnlyListOfZoneDto": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "هل نجح الطلب / Whether the request succeeded"
          },
          "data": {
            "type": [
              "null",
              "array"
            ],
            "items": {
              "$ref": "#/components/schemas/ZoneDto"
            },
            "description": "البيانات (null عند الفشل) / Payload (null on failure)"
          },
          "error": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "تفاصيل الخطأ (null عند النجاح) / Error details (null on success)",
                "$ref": "#/components/schemas/ApiError"
              }
            ]
          },
          "meta": {
            "description": "معلومات إضافية اختيارية (ترقيم، تحذيرات...) / Optional metadata"
          },
          "requestId": {
            "type": "string",
            "description": "معرّف الطلب للدعم (= ترويسة X-Request-Id) / Request id for support"
          }
        },
        "description": "الغلاف الموحّد لكل ردود الـ API (D8): success / data / error / meta / requestId.\r\nUnified response envelope for every API response."
      },
      "ApiEnvelopeOfMeDto": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "هل نجح الطلب / Whether the request succeeded"
          },
          "data": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "البيانات (null عند الفشل) / Payload (null on failure)",
                "$ref": "#/components/schemas/MeDto"
              }
            ]
          },
          "error": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "تفاصيل الخطأ (null عند النجاح) / Error details (null on success)",
                "$ref": "#/components/schemas/ApiError"
              }
            ]
          },
          "meta": {
            "description": "معلومات إضافية اختيارية (ترقيم، تحذيرات...) / Optional metadata"
          },
          "requestId": {
            "type": "string",
            "description": "معرّف الطلب للدعم (= ترويسة X-Request-Id) / Request id for support"
          }
        },
        "description": "الغلاف الموحّد لكل ردود الـ API (D8): success / data / error / meta / requestId.\r\nUnified response envelope for every API response."
      },
      "ApiEnvelopeOfObject": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "هل نجح الطلب / Whether the request succeeded"
          },
          "data": {
            "description": "البيانات (null عند الفشل) / Payload (null on failure)"
          },
          "error": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "تفاصيل الخطأ (null عند النجاح) / Error details (null on success)",
                "$ref": "#/components/schemas/ApiError"
              }
            ]
          },
          "meta": {
            "description": "معلومات إضافية اختيارية (ترقيم، تحذيرات...) / Optional metadata"
          },
          "requestId": {
            "type": "string",
            "description": "معرّف الطلب للدعم (= ترويسة X-Request-Id) / Request id for support"
          }
        },
        "description": "الغلاف الموحّد لكل ردود الـ API (D8): success / data / error / meta / requestId.\r\nUnified response envelope for every API response."
      },
      "ApiEnvelopeOfOrderDto": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "هل نجح الطلب / Whether the request succeeded"
          },
          "data": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "البيانات (null عند الفشل) / Payload (null on failure)",
                "$ref": "#/components/schemas/OrderDto"
              }
            ]
          },
          "error": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "تفاصيل الخطأ (null عند النجاح) / Error details (null on success)",
                "$ref": "#/components/schemas/ApiError"
              }
            ]
          },
          "meta": {
            "description": "معلومات إضافية اختيارية (ترقيم، تحذيرات...) / Optional metadata"
          },
          "requestId": {
            "type": "string",
            "description": "معرّف الطلب للدعم (= ترويسة X-Request-Id) / Request id for support"
          }
        },
        "description": "الغلاف الموحّد لكل ردود الـ API (D8): success / data / error / meta / requestId.\r\nUnified response envelope for every API response."
      },
      "ApiEnvelopeOfWebhookTestDto": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "هل نجح الطلب / Whether the request succeeded"
          },
          "data": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "البيانات (null عند الفشل) / Payload (null on failure)",
                "$ref": "#/components/schemas/WebhookTestDto"
              }
            ]
          },
          "error": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "تفاصيل الخطأ (null عند النجاح) / Error details (null on success)",
                "$ref": "#/components/schemas/ApiError"
              }
            ]
          },
          "meta": {
            "description": "معلومات إضافية اختيارية (ترقيم، تحذيرات...) / Optional metadata"
          },
          "requestId": {
            "type": "string",
            "description": "معرّف الطلب للدعم (= ترويسة X-Request-Id) / Request id for support"
          }
        },
        "description": "الغلاف الموحّد لكل ردود الـ API (D8): success / data / error / meta / requestId.\r\nUnified response envelope for every API response."
      },
      "ApiEnvelopeOfZoneDetectDto": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "هل نجح الطلب / Whether the request succeeded"
          },
          "data": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "البيانات (null عند الفشل) / Payload (null on failure)",
                "$ref": "#/components/schemas/ZoneDetectDto"
              }
            ]
          },
          "error": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "تفاصيل الخطأ (null عند النجاح) / Error details (null on success)",
                "$ref": "#/components/schemas/ApiError"
              }
            ]
          },
          "meta": {
            "description": "معلومات إضافية اختيارية (ترقيم، تحذيرات...) / Optional metadata"
          },
          "requestId": {
            "type": "string",
            "description": "معرّف الطلب للدعم (= ترويسة X-Request-Id) / Request id for support"
          }
        },
        "description": "الغلاف الموحّد لكل ردود الـ API (D8): success / data / error / meta / requestId.\r\nUnified response envelope for every API response."
      },
      "ApiError": {
        "required": [
          "code",
          "message"
        ],
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "كود الخطأ الثابت (§12.1) / Stable error code"
          },
          "message": {
            "type": "string",
            "description": "رسالة عربية للعرض / Arabic display message"
          },
          "details": {
            "description": "تفاصيل إضافية أو null / Optional details"
          }
        },
        "description": "خطأ API: code ثابت إنجليزي للبرمجة + message عربي للعرض + details اختيارية."
      },
      "ApiErrorEnvelope": {
        "required": [
          "success",
          "data",
          "error",
          "requestId"
        ],
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "دائماً false / Always false"
          },
          "data": {
            "type": "null",
            "description": "دائماً null / Always null"
          },
          "error": {
            "required": [
              "code",
              "message"
            ],
            "type": "object",
            "properties": {
              "code": {
                "enum": [
                  "missing_api_key",
                  "invalid_api_key",
                  "too_many_auth_failures",
                  "merchant_not_active",
                  "rate_limited",
                  "https_required",
                  "invalid_json",
                  "validation_failed",
                  "payload_too_large",
                  "bulk_empty",
                  "bulk_limit_exceeded",
                  "zone_required",
                  "zone_not_found",
                  "zone_not_detected",
                  "invalid_map_url",
                  "invalid_phone",
                  "order_not_found",
                  "order_not_cancellable",
                  "external_ref_conflict",
                  "test_mode_only",
                  "invalid_transition",
                  "webhook_not_configured",
                  "webhook_disabled",
                  "not_found",
                  "method_not_allowed",
                  "internal_error",
                  "service_unavailable"
                ],
                "type": "string",
                "description": "كود ثابت (§12.1) / Stable error code"
              },
              "message": {
                "type": "string",
                "description": "رسالة عربية للعرض / Arabic display message"
              },
              "details": {
                "type": [
                  "null",
                  "object"
                ],
                "description": "تفاصيل اختيارية — validation_failed: { fields: [{ field, code, message }] } / Optional details"
              }
            }
          },
          "requestId": {
            "type": "string",
            "description": "معرّف الطلب للدعم (= X-Request-Id) / Request id"
          }
        },
        "description": "غلاف رد الخطأ / Error response envelope"
      },
      "ApiSimulateStatusRequest": {
        "type": "object",
        "properties": {
          "status": {
            "examples": [
              "out_for_delivery"
            ],
            "type": [
              "null",
              "string"
            ],
            "description": "الحالة المطلوبة: processing | out_for_delivery | delivered | returned | cancelled.\r\nTarget status — forward moves only, from a non-final status."
          }
        },
        "description": "جسم محاكاة حالة طلب تجريبي (N-37 — الوضع التجريبي فقط) / Simulate a test order status change."
      },
      "BalanceDto": {
        "required": [
          "balance",
          "currency",
          "hasPendingWithdrawal",
          "transactions"
        ],
        "type": "object",
        "properties": {
          "balance": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "description": "الرصيد الحالي / Current balance",
            "format": "double"
          },
          "currency": {
            "type": "string",
            "description": "دائماً ILS / Always ILS"
          },
          "hasPendingWithdrawal": {
            "type": "boolean",
            "description": "يوجد طلب صرف قيد المراجعة / A withdrawal request is pending"
          },
          "transactions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TransactionDto"
            },
            "description": "آخر الحركات تنازلياً / Latest transactions, newest first"
          }
        },
        "description": "الرصيد وآخر الحركات (§6.8) / Balance and latest transactions"
      },
      "BulkCreateRequest": {
        "type": "object",
        "properties": {
          "orders": {
            "type": [
              "null",
              "array"
            ],
            "items": {
              "$ref": "#/components/schemas/ApiCreateOrderRequest"
            },
            "description": "الطلبات (1..100) / Orders (1..100)"
          }
        },
        "description": "إنشاء جماعي (§6.2) — 1..100 طلب، كل عنصر بنفس تحقق POST /orders ويُحفظ مستقلاً.\r\nBulk create — 1..100 orders, each validated and saved independently."
      },
      "BulkItemResultDto": {
        "type": "object",
        "properties": {
          "index": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "description": "موضع العنصر في orders[] (يبدأ من 0) / Zero-based index in orders[]",
            "format": "int32"
          },
          "externalRef": {
            "type": [
              "null",
              "string"
            ],
            "description": "externalRef كما أُرسل / externalRef as sent"
          },
          "success": {
            "type": "boolean",
            "description": "نجح العنصر (أُنشئ أو replay) / Item succeeded (created or replayed)"
          },
          "replayed": {
            "type": [
              "null",
              "boolean"
            ],
            "description": "true = طلب موجود مسبقاً بنفس externalRef (عند النجاح فقط) / Existing order returned"
          },
          "order": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "الطلب مختصراً (عند النجاح) / Short order summary (on success)",
                "$ref": "#/components/schemas/BulkOrderSummaryDto"
              }
            ]
          },
          "warnings": {
            "type": [
              "null",
              "array"
            ],
            "items": {
              "type": "string"
            },
            "description": "تحذيرات غير قاتلة (عند النجاح) / Non-fatal warnings (on success)"
          },
          "error": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "الخطأ (عند الفشل) — نفس أكواد POST /orders / Error (on failure)",
                "$ref": "#/components/schemas/ApiError"
              }
            ]
          }
        },
        "description": "نتيجة عنصر واحد / Single item result"
      },
      "BulkOrderSummaryDto": {
        "required": [
          "id",
          "refNumber",
          "zone",
          "deliveryFee",
          "totalCollect",
          "merchantStatus"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "معرّف الطلب / Order id",
            "format": "uuid"
          },
          "refNumber": {
            "type": "string",
            "description": "رقم المرجع / Reference number"
          },
          "zone": {
            "type": "string",
            "description": "منطقة التوصيل / Delivery zone"
          },
          "deliveryFee": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "description": "رسوم التوصيل / Delivery fee",
            "format": "double"
          },
          "totalCollect": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "description": "ما يجمعه الكابتن / Amount collected by the captain",
            "format": "double"
          },
          "merchantStatus": {
            "type": "string",
            "description": "الحالة المبسطة / Simplified status"
          },
          "livemode": {
            "type": "boolean",
            "description": "true = حقيقي (mk_live_) — false = تجريبي (mk_test_) / Live or test",
            "default": true
          }
        },
        "description": "الطلب مختصراً في نتائج bulk / Short order in bulk results"
      },
      "BulkResultDto": {
        "required": [
          "summary",
          "results"
        ],
        "type": "object",
        "properties": {
          "summary": {
            "description": "الملخص — المرجع لمعرفة الفاشل / Summary (use failed to detect failures)",
            "$ref": "#/components/schemas/BulkSummaryDto"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BulkItemResultDto"
            },
            "description": "نتيجة لكل عنصر بترتيب الإرسال / One result per item, in request order"
          }
        },
        "description": "نتيجة الإنشاء الجماعي / Bulk create result"
      },
      "BulkSummaryDto": {
        "required": [
          "total",
          "created",
          "replayed",
          "failed"
        ],
        "type": "object",
        "properties": {
          "total": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "description": "عدد العناصر المرسلة / Items sent",
            "format": "int32"
          },
          "created": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "description": "طلبات جديدة / Newly created",
            "format": "int32"
          },
          "replayed": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "description": "موجودة مسبقاً بنفس externalRef / Existing (replayed)",
            "format": "int32"
          },
          "failed": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "description": "عناصر فشلت — راجع results[].error / Failed items",
            "format": "int32"
          }
        },
        "description": "ملخص الدفعة / Batch summary"
      },
      "HealthDto": {
        "required": [
          "status",
          "version",
          "time"
        ],
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "ok"
          },
          "version": {
            "type": "string",
            "description": "إصدار الـ API / API version (v1)"
          },
          "time": {
            "type": "string",
            "description": "وقت الخادم UTC / Server time (UTC)",
            "format": "date-time"
          }
        },
        "description": "حالة الخدمة / Service health"
      },
      "JsonElement": { },
      "MeApiKeyDto": {
        "required": [
          "prefix",
          "createdAt",
          "lastUsedAt"
        ],
        "type": "object",
        "properties": {
          "prefix": {
            "type": "string",
            "description": "أول 12 حرفاً / First 12 characters"
          },
          "createdAt": {
            "type": "string",
            "description": "تاريخ الإنشاء UTC",
            "format": "date-time"
          },
          "lastUsedAt": {
            "type": [
              "null",
              "string"
            ],
            "description": "آخر استخدام UTC (يُحدَّث كل 5 دقائق كحد أقصى)",
            "format": "date-time"
          }
        },
        "description": "بيانات عرض المفتاح / Key display info"
      },
      "MeDto": {
        "required": [
          "merchantId",
          "storeName",
          "email",
          "phone",
          "zone",
          "status",
          "balance",
          "currency",
          "apiKey"
        ],
        "type": "object",
        "properties": {
          "merchantId": {
            "type": "string",
            "description": "معرّف التاجر / Merchant id",
            "format": "uuid"
          },
          "storeName": {
            "type": "string",
            "description": "اسم المتجر / Store name"
          },
          "email": {
            "type": [
              "null",
              "string"
            ],
            "description": "البريد / Email"
          },
          "phone": {
            "type": [
              "null",
              "string"
            ],
            "description": "الهاتف / Phone"
          },
          "zone": {
            "type": "string",
            "description": "منطقة المتجر / Store zone"
          },
          "status": {
            "type": "string",
            "description": "active | pending | suspended"
          },
          "balance": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "description": "الرصيد الحالي / Current balance",
            "format": "double"
          },
          "currency": {
            "type": "string",
            "description": "العملة دائماً ILS / Always ILS"
          },
          "apiKey": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "المفتاح المستخدم (بدون السر) / Key in use (no secret)",
                "$ref": "#/components/schemas/MeApiKeyDto"
              }
            ]
          },
          "webhook": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "حالة الـ Webhook (دائماً موجود، configured=false إن لم يُضبط) / Webhook status",
                "$ref": "#/components/schemas/MeWebhookDto"
              }
            ]
          },
          "livemode": {
            "type": "boolean",
            "description": "true = مفتاح حقيقي (mk_live_) — false = مفتاح تجريبي (mk_test_) فيكون `balance` دائماً 0.00 / Live or test key",
            "default": true
          }
        },
        "description": "ملف التاجر صاحب المفتاح / Profile of the merchant owning the API key"
      },
      "MeWebhookDto": {
        "required": [
          "configured",
          "url",
          "isActive",
          "events"
        ],
        "type": "object",
        "properties": {
          "configured": {
            "type": "boolean",
            "description": "هل ضُبط رابط / Whether a URL is configured"
          },
          "url": {
            "type": [
              "null",
              "string"
            ],
            "description": "الرابط أو null / URL or null"
          },
          "isActive": {
            "type": "boolean",
            "description": "نشط (false إن لم يُضبط أو عُطّل) / Active"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "order.created, order.status_changed"
          }
        },
        "description": "حالة الـ Webhook (بدون السر) / Webhook status (no secret)"
      },
      "OrderDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "معرّف الطلب / Order id",
            "format": "uuid"
          },
          "refNumber": {
            "type": "string",
            "description": "رقم المرجع (WP-yyyyMMdd-NNNN) / Reference number"
          },
          "externalRef": {
            "type": [
              "null",
              "string"
            ],
            "description": "رقم الطلب في نظامك / Your order number"
          },
          "source": {
            "type": "string",
            "description": "api | portal | app"
          },
          "livemode": {
            "type": "boolean",
            "description": "true = طلب حقيقي (مفتاح mk_live_) — false = طلب تجريبي (mk_test_) / Live or test order"
          },
          "status": {
            "type": "string",
            "description": "الحالة الداخلية: pending, assigned, collecting, at_warehouse, out_for_delivery, delivered, returned, cancelled, settled"
          },
          "merchantStatus": {
            "type": "string",
            "description": "الحالة المبسطة: pending, processing, out_for_delivery, delivered, returned, cancelled"
          },
          "merchantStatusLabel": {
            "type": "string",
            "description": "التسمية العربية للحالة المبسطة / Arabic label"
          },
          "recipientName": {
            "type": "string",
            "description": "اسم المستلم / Recipient name"
          },
          "recipientPhone": {
            "type": "string",
            "description": "جوال المستلم بعد التطبيع / Recipient mobile (normalized)"
          },
          "address": {
            "type": "string",
            "description": "العنوان الوصفي / Address text"
          },
          "zone": {
            "type": "string",
            "description": "منطقة التوصيل / Delivery zone"
          },
          "latitude": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
            "type": [
              "null",
              "number",
              "string"
            ],
            "description": "خط العرض أو null / Latitude or null",
            "format": "double"
          },
          "longitude": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
            "type": [
              "null",
              "number",
              "string"
            ],
            "description": "خط الطول أو null / Longitude or null",
            "format": "double"
          },
          "paymentType": {
            "type": "string",
            "description": "cod | prepaid"
          },
          "codAmount": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "description": "قيمة الطلب (إشارية مع prepaid) / Order value (indicative for prepaid)",
            "format": "double"
          },
          "deliveryFeeTarget": {
            "type": "string",
            "description": "merchant | customer"
          },
          "codCollectionTarget": {
            "type": "string",
            "description": "wasselni_direct | captain | merchant_pre_collected"
          },
          "deliveryFee": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "description": "رسوم التوصيل المثبتة لحظة الإنشاء / Delivery fee (fixed at creation)",
            "format": "double"
          },
          "returnFee": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "description": "رسوم الإرجاع / Return fee",
            "format": "double"
          },
          "totalCollect": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "description": "ما يجمعه الكابتن من الزبون / Amount the captain collects from the customer",
            "format": "double"
          },
          "currency": {
            "type": "string",
            "description": "دائماً ILS"
          },
          "awaitingDirectTransfer": {
            "type": "boolean",
            "description": "COD + wasselni_direct ولم يُؤكَّد التحويل بعد — لا يُسلَّم قبل التأكيد"
          },
          "notes": {
            "type": [
              "null",
              "string"
            ],
            "description": "ملاحظات للكابتن / Notes"
          },
          "createdAt": {
            "type": "string",
            "description": "وقت الإنشاء UTC / Created at (UTC)",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "description": "آخر تحديث UTC / Last update (UTC)",
            "format": "date-time"
          },
          "trackingUrl": {
            "type": "string",
            "description": "رابط صفحة التتبع العامة / Public tracking page"
          },
          "timeline": {
            "type": [
              "null",
              "array"
            ],
            "items": {
              "$ref": "#/components/schemas/OrderTimelineEntryDto"
            },
            "description": "سجل الحالات تصاعدياً — في GET فقط / Status timeline (GET only)"
          }
        },
        "description": "طلب كما يراه التاجر عبر الـ API (§6.1) / Order as returned by the API"
      },
      "OrderTimelineEntryDto": {
        "required": [
          "status",
          "merchantStatus",
          "at"
        ],
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "الحالة الداخلية / Internal status"
          },
          "merchantStatus": {
            "type": "string",
            "description": "الحالة المبسطة / Simplified status"
          },
          "at": {
            "type": "string",
            "description": "وقت التغيير UTC / Changed at (UTC)",
            "format": "date-time"
          }
        },
        "description": "عنصر في سجل الحالات (بلا note/changedBy — D31) / Status timeline entry"
      },
      "TransactionDto": {
        "required": [
          "type",
          "amount",
          "description",
          "orderRefNumber",
          "createdAt"
        ],
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "cod_credit | delivery_fee | return_fee | withdrawal | adjustment"
          },
          "amount": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "description": "المبلغ بإشارته كما هو مخزّن (الخصومات سالبة) / Signed amount (debits negative)",
            "format": "double"
          },
          "description": {
            "type": "string",
            "description": "الوصف / Description"
          },
          "orderRefNumber": {
            "type": [
              "null",
              "string"
            ],
            "description": "رقم مرجع الطلب المرتبط أو null / Related order refNumber or null"
          },
          "createdAt": {
            "type": "string",
            "description": "UTC",
            "format": "date-time"
          }
        },
        "description": "حركة مالية / Balance transaction"
      },
      "WebhookTestDto": {
        "required": [
          "delivered",
          "statusCode",
          "durationMs",
          "error"
        ],
        "type": "object",
        "properties": {
          "delivered": {
            "type": "boolean",
            "description": "true = ردّ المستقبِل بـ 2xx / receiver answered 2xx"
          },
          "statusCode": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "null",
              "integer",
              "string"
            ],
            "description": "HTTP status الرد أو null (فشل اتصال/timeout) / Receiver status code",
            "format": "int32"
          },
          "durationMs": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "description": "المدة بالمللي ثانية / Duration",
            "format": "int32"
          },
          "error": {
            "type": [
              "null",
              "string"
            ],
            "description": "سبب الفشل (مقتطع، بلا ترويسات) أو null / Failure reason"
          }
        },
        "description": "نتيجة اختبار الـ Webhook / Webhook test result"
      },
      "ZoneDetectDto": {
        "required": [
          "zone",
          "deliveryFee",
          "returnFee"
        ],
        "type": "object",
        "properties": {
          "zone": {
            "type": "string",
            "description": "اسم المنطقة / Zone name"
          },
          "deliveryFee": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "description": "رسوم التوصيل / Delivery fee",
            "format": "double"
          },
          "returnFee": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "description": "رسوم الإرجاع / Return fee",
            "format": "double"
          }
        },
        "description": "نتيجة اكتشاف المنطقة من الإحداثيات / Zone detected from coordinates"
      },
      "ZoneDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "اسم المنطقة — يُرسل كما هو في حقل zone / Zone name (use as-is in the zone field)"
          },
          "deliveryFee": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "description": "رسوم التوصيل / Delivery fee",
            "format": "double"
          },
          "returnFee": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "description": "رسوم الإرجاع / Return fee",
            "format": "double"
          },
          "hasBoundary": {
            "type": "boolean",
            "description": "هل للمنطقة حدود مرسومة صالحة (يُكتشف بها الموقع) / Has a valid drawn boundary"
          },
          "boundary": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "description": "GeoJSON Polygon بترتيب [lng,lat] — عند includeBoundary=true فقط / Only with includeBoundary=true",
                "$ref": "#/components/schemas/JsonElement"
              }
            ]
          }
        },
        "description": "منطقة توصيل ورسومها (§6.6) / Delivery zone and fees"
      }
    },
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "description": "مفتاح API بصيغة mk_live_… (أو mk_test_… للوضع التجريبي) — لا تضعه في كود المتصفح / API key (mk_live_… or mk_test_…) — never in browser code",
        "name": "X-Api-Key",
        "in": "header"
      }
    }
  },
  "tags": [
    {
      "name": "System"
    },
    {
      "name": "Merchant"
    },
    {
      "name": "Orders"
    },
    {
      "name": "Webhooks"
    },
    {
      "name": "Zones"
    }
  ]
}