{
  "info": {
    "name": "واجهة Corbit الموحّدة للرسائل (API)",
    "description": "واجهة واحدة للرسائل النصية وواتساب للأعمال ومنصة SMPP الأساسية: إرسال فردي وجماعي، الاستعلام عن الرصيد، أسماء المرسلين، ومتابعة حالة التسليم.\n\n## المصادقة\n\nأرسل توكن الـ API الخاص بك في الترويسة `Authorization` مع كل طلب:\n\n```\nAuthorization: Bearer YOUR_API_TOKEN\n```\n\n- **نقاط SMS والبوابة** — استخدم توكن الـ API الذي أنشأته من حسابك في Corbit SMS (sms.corbit.sa).\n- **نقاط واتساب** — استخدم مفتاح واتساب API الخاص بك (`sk_live_…`) كتوكن Bearer.\n- **نقاط المنصة الأساسية** — مرّر `ApiKey` و`ClientId` كمعاملات في الرابط (أو في جسم JSON حيث يظهر ذلك).\n\nالطلبات التي لا تحمل بيانات دخول صالحة تُرفض برمز HTTP 401 في نقاط SMS وواتساب والبوابة، أما نقاط Core فتردّ برمز HTTP 200 مع `ErrorCode` غير صفري (مثل `7` لبيانات دخول غير صالحة).\n\n## حدود الاستخدام\n\nيمكن لكل توكن إرسال حتى **1000 طلب كل 60 ثانية** على نقاط SMS والبوابة (`/api/v1/*` و`/gateway/v1/*`) مجتمعة. تحمل ردود هذه النقاط الترويستين `X-RateLimit-Limit` و`X-RateLimit-Remaining`.\n\nعند تجاوز الحد يرد الـ API برمز **HTTP 429** والكود `RATE_LIMIT` مع الترويسة `Retry-After` (عدد الثواني حتى تتمكن من إعادة المحاولة).\n\nأما نقاط واتساب وCore فتخضع لحدود منصّتيهما.\n\n## منع التكرار\n\nلحمايتك من الفوترة المزدوجة تُقبل الرسالة النصية المتطابقة المرسلة عبر `/api/v1/send` أو `/api/v1/send-bulk` — نفس الحساب ونفس المستلم(ين) ونفس النص — مرة واحدة فقط خلال 3600 ثانية. يُرفض التكرار برمز **HTTP 409** والكود `DUPLICATE` ولا يُرسل شيء. يحمل الرد الترويسة `X-Dedup-Window` (مدة النافذة بالثواني).\n\nإذا كنت تحتاج فعلًا لإعادة إرسال النص نفسه — مثل إعادة إرسال رمز التحقق — أضف الترويسة `X-Allow-Duplicate: true` لذلك الطلب.\n\n## إعادة المحاولة الآمنة (Idempotency-Key)\n\nفي طلبات POST إلى نقاط SMS والبوابة يمكنك إرسال `Idempotency-Key: <نص فريد حتى 255 حرفًا>`. إذا أُعيد الطلب بنفس المفتاح يُرجع الـ API الرد الأصلي (مع الترويسة `Idempotent-Replayed: true`) بدل الإرسال مرة أخرى.\n\nاستخدام المفتاح نفسه مع محتوى مختلف يُرجع **422** والكود `IDEMPOTENCY_KEY_REUSED`، وإعادة المحاولة أثناء معالجة الطلب الأول تُرجع **409** والكود `IDEMPOTENCY_IN_PROGRESS`.\n\n## حماية الرصيد\n\nعند نفاد رصيدك تُرفض طلبات إرسال الرسائل النصية برمز **HTTP 402** والكود `INSUFFICIENT_BALANCE` ولا تُرسل أي رسالة. اشحن حسابك ثم أعد المحاولة. يمكنك معرفة رصيدك في أي وقت عبر نقاط الرصيد.\n\n## الأخطاء\n\nتُعاد الأخطاء بصيغة JSON، مثل `{ \"status\": \"Error\", \"message\": \"…\", \"code\": \"DUPLICATE\" }`. استخدم رمز HTTP والحقل `code` للتعامل معها في تطبيقك.\n\nالأخطاء التي تصدر من خدمة الرسائل نفسها — مثل `422` عند استخدام اسم مرسِل غير معتمد — تُعاد كما هي مع رسالتها الخاصة.\n\nونقاط واتساب تُعيد `{ \"success\": false, \"errors\": { … } }`، ونقاط Core تُعيد HTTP 200 مع `ErrorCode` غير صفري — تحقّق دائمًا من `ErrorCode` هناك.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "الرسائل النصية (SMS)",
      "description": "إرسال الرسائل النصية الفردية والجماعية، والاستعلام عن الرصيد، وأسماء المرسلين، ومتابعة حالة التسليم.",
      "item": [
        {
          "name": "إرسال رسالة نصية (فردي)",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{token}}"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/send",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "send"
              ]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"senderName\": \"Mobile.SA\",\n  \"number\": \"966XXXXXXXXX\",\n  \"messageBody\": \"Your code is 4821\",\n  \"sendAtOption\": \"NOW\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "description": "يرسل رسالة نصية واحدة. يحتوي الرد على معرّف الرسالة `id` الذي يُستخدم مع نقطتي الحالة والتقرير.\n\n| Field | In | Type | Required | Description |\n|---|---|---|---|---|\n| `Idempotency-Key` | header | string | no | اختياري. إعادة المحاولة بنفس المفتاح تُرجع الرد الأول (الترويسة `Idempotent-Replayed: true`) بدل الإرسال مرة أخرى. |\n| `X-Allow-Duplicate` | header | string | no | اختياري. اضبطه على `true` لإعادة إرسال رسالة مطابقة عمدًا (يتجاوز منع التكرار لهذا الطلب فقط). |\n| `senderName` | body | string | yes | اسم المرسِل المعتمد على حسابك (راجع نقطة أسماء المرسلين). |\n| `number` | body | string | yes | رقم جوال المستلم بالصيغة الدولية، أرقام فقط (من 8 إلى 15 رقمًا)، مثال `966XXXXXXXXX`. |\n| `messageBody` | body | string | yes | نص الرسالة، حتى 1600 حرفًا. |\n| `sendAtOption` | body | string | no | توقيت الإرسال. القيمة `NOW` ترسل فورًا. |"
          },
          "response": [
            {
              "name": "تم القبول",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Success\",\n  \"message\": null,\n  \"data\": {\n    \"message\": {\n      \"id\": \"8493f201-ebcc-4415-8450-18d8d8714f33\",\n      \"status\": \"pending\"\n    }\n  }\n}"
            },
            {
              "name": "طلب غير صالح",
              "code": 400,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Error\",\n  \"message\": \"Invalid destination number: 12 (expected 8-15 digits, international format).\",\n  \"code\": \"VALIDATION\"\n}"
            },
            {
              "name": "الرصيد منتهٍ",
              "code": 402,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Error\",\n  \"message\": \"Insufficient balance (0). Please top up to continue sending.\",\n  \"code\": \"INSUFFICIENT_BALANCE\"\n}"
            },
            {
              "name": "رسالة مكرّرة",
              "code": 409,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Error\",\n  \"message\": \"Duplicate request blocked: same client, destination, and message within the dedup window.\",\n  \"code\": \"DUPLICATE\"\n}"
            },
            {
              "name": "تجاوز حد الطلبات",
              "code": 429,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Error\",\n  \"message\": \"Rate limit exceeded\",\n  \"code\": \"RATE_LIMIT\"\n}"
            }
          ]
        },
        {
          "name": "إرسال رسائل نصية (جماعي)",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{token}}"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/send-bulk",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "send-bulk"
              ]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"senderName\": \"Mobile.SA\",\n  \"numbers\": [\n    \"966XXXXXXXXX\",\n    \"966XXXXXXXXX\"\n  ],\n  \"messageBody\": \"Corbit bulk\",\n  \"sendAtOption\": \"Now\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "description": "يرسل النص نفسه إلى عدة مستلمين في طلب واحد.\n\n| Field | In | Type | Required | Description |\n|---|---|---|---|---|\n| `Idempotency-Key` | header | string | no | اختياري. إعادة المحاولة بنفس المفتاح تُرجع الرد الأول بدل الإرسال مرة أخرى. |\n| `X-Allow-Duplicate` | header | string | no | اختياري. اضبطه على `true` لإعادة إرسال رسالة مطابقة عمدًا. |\n| `senderName` | body | string | yes | اسم المرسِل المعتمد على حسابك. |\n| `numbers` | body | array | yes | أرقام المستلمين بالصيغة الدولية. إذا كان أي رقم غير صالح يُرفض الطلب كاملًا ولا تُرسل أي رسالة. |\n| `messageBody` | body | string | yes | نص الرسالة، حتى 1600 حرفًا. |\n| `sendAtOption` | body | string | no | توقيت الإرسال. استخدم القيمة `Now` للإرسال فورًا. |"
          },
          "response": [
            {
              "name": "تم القبول",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Success\",\n  \"message\": null,\n  \"data\": {\n    \"message\": {\n      \"id\": \"2cb5acc1-fc5a-495e-a610-1f789dec53ff\",\n      \"status\": \"pending\"\n    }\n  }\n}"
            },
            {
              "name": "طلب غير صالح",
              "code": 400,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Error\",\n  \"message\": \"Invalid destination number: 12 (expected 8-15 digits, international format).\",\n  \"code\": \"VALIDATION\"\n}"
            },
            {
              "name": "الرصيد منتهٍ",
              "code": 402,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Error\",\n  \"message\": \"Insufficient balance (0). Please top up to continue sending.\",\n  \"code\": \"INSUFFICIENT_BALANCE\"\n}"
            },
            {
              "name": "رسالة مكرّرة",
              "code": 409,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Error\",\n  \"message\": \"Duplicate request blocked: same client, destination, and message within the dedup window.\",\n  \"code\": \"DUPLICATE\"\n}"
            },
            {
              "name": "تجاوز حد الطلبات",
              "code": 429,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Error\",\n  \"message\": \"Rate limit exceeded\",\n  \"code\": \"RATE_LIMIT\"\n}"
            }
          ]
        },
        {
          "name": "رصيد الحساب",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/get-balance",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "get-balance"
              ]
            },
            "description": "يعرض رصيدك المتبقي."
          },
          "response": [
            {
              "name": "ناجح",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Success\",\n  \"message\": null,\n  \"data\": {\n    \"balance\": 183\n  }\n}"
            }
          ]
        },
        {
          "name": "أسماء المرسلين المعتمدة",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/sendernames",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "sendernames"
              ]
            },
            "description": "يعرض أسماء المرسلين المسجّلة على حسابك وحالة اعتماد كل منها."
          },
          "response": [
            {
              "name": "ناجح",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Success\",\n  \"message\": \"Sender names retrieved successfully\",\n  \"data\": [\n    {\n      \"name\": \"Mobile.SA\",\n      \"status\": \"approved\"\n    }\n  ],\n  \"pagination\": {\n    \"total\": 1,\n    \"per_page\": 15,\n    \"current_page\": 1\n  }\n}"
            }
          ]
        },
        {
          "name": "حالة تسليم الرسالة",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/message-status/:id",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "message-status",
                ":id"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": "",
                  "description": "معرّف الرسالة الذي أعادته نقاط الإرسال."
                }
              ]
            },
            "description": "يعرض الحالة الحالية لرسالة قُبلت عبر نقاط الإرسال.\n\n| Field | In | Type | Required | Description |\n|---|---|---|---|---|\n| `id` | path | string | yes | معرّف الرسالة الذي أعادته نقاط الإرسال. |"
          },
          "response": [
            {
              "name": "ناجح",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Success\",\n  \"message\": null,\n  \"data\": {\n    \"status\": \"sent\"\n  }\n}"
            }
          ]
        },
        {
          "name": "تقرير تسليم الرسالة (DLR)",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/message-report/:id",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "api",
                "v1",
                "message-report",
                ":id"
              ],
              "variable": [
                {
                  "key": "id",
                  "value": "",
                  "description": "معرّف الرسالة الذي أعادته نقاط الإرسال."
                }
              ]
            },
            "description": "يعرض تقرير التسليم التفصيلي لكل وجهة.\n\n| Field | In | Type | Required | Description |\n|---|---|---|---|---|\n| `id` | path | string | yes | معرّف الرسالة الذي أعادته نقاط الإرسال. |"
          },
          "response": [
            {
              "name": "ناجح",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"jobId\": \"moe-XYno7kqZeK0jN8YlMg\",\n  \"msgs\": [\n    {\n      \"destAddress\": \"966XXXXXXXXX\",\n      \"status\": \"unknown\",\n      \"accepted\": false\n    }\n  ]\n}"
            }
          ]
        }
      ]
    },
    {
      "name": "واتساب للأعمال",
      "description": "إرسال رسائل واتساب وقراءة جهات الاتصال والمحادثات. للمصادقة استخدم مفتاح واتساب API الخاص بك.",
      "item": [
        {
          "name": "إرسال رسالة واتساب",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{token}}"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{base_url}}/wa/api/v1/messages",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "wa",
                "api",
                "v1",
                "messages"
              ]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"to\": \"966XXXXXXXXX\",\n  \"text\": \"Hello from Corbit\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "description": "يرسل رسالة نصية عبر واتساب.\n\n| Field | In | Type | Required | Description |\n|---|---|---|---|---|\n| `to` | body | string | yes | رقم المستلم بالصيغة الدولية. |\n| `text` | body | string | yes | نص الرسالة. |"
          },
          "response": [
            {
              "name": "تم القبول",
              "code": 202,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"success\": true,\n  \"message\": \"Message accepted\",\n  \"data\": {\n    \"message_id\": \"01a069b6-224d-71b7-8d97-721a8baec292\",\n    \"conversation_id\": \"01a06995-a665-70b5-a5f3-65cfba790a11\",\n    \"type\": \"text\",\n    \"status\": \"sent\"\n  }\n}"
            }
          ]
        },
        {
          "name": "قائمة جهات الاتصال",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/wa/api/v1/contacts?limit=&page=",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "wa",
                "api",
                "v1",
                "contacts"
              ],
              "query": [
                {
                  "key": "limit",
                  "value": "",
                  "description": "عدد النتائج في الصفحة."
                },
                {
                  "key": "page",
                  "value": "",
                  "description": "رقم الصفحة."
                }
              ]
            },
            "description": "يعرض جهات اتصال واتساب الخاصة بك (مقسّمة إلى صفحات).\n\n| Field | In | Type | Required | Description |\n|---|---|---|---|---|\n| `limit` | query | integer | no | عدد النتائج في الصفحة. |\n| `page` | query | integer | no | رقم الصفحة. |"
          },
          "response": [
            {
              "name": "ناجح",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"success\": true,\n  \"message\": \"OK\",\n  \"data\": {\n    \"data\": [\n      {\n        \"id\": \"01a0699e-…\",\n        \"name\": \"966XXXXXXXXX\",\n        \"country\": \"SA\",\n        \"status\": \"active\"\n      }\n    ],\n    \"meta\": {\n      \"current_page\": 1,\n      \"per_page\": 2,\n      \"total\": 3208\n    }\n  }\n}"
            }
          ]
        },
        {
          "name": "قائمة المحادثات",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/wa/api/v1/conversations?status=&limit=",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "wa",
                "api",
                "v1",
                "conversations"
              ],
              "query": [
                {
                  "key": "status",
                  "value": "",
                  "description": "تصفية حسب حالة المحادثة."
                },
                {
                  "key": "limit",
                  "value": "",
                  "description": "عدد النتائج في الصفحة."
                }
              ]
            },
            "description": "يعرض محادثات واتساب الخاصة بك (مقسّمة إلى صفحات).\n\n| Field | In | Type | Required | Description |\n|---|---|---|---|---|\n| `status` | query | string | no | تصفية حسب حالة المحادثة. |\n| `limit` | query | integer | no | عدد النتائج في الصفحة. |"
          },
          "response": [
            {
              "name": "ناجح",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"success\": true,\n  \"message\": \"OK\",\n  \"data\": {\n    \"data\": [\n      {\n        \"id\": \"01a06995-…\",\n        \"status\": \"open\",\n        \"channel\": \"whatsapp\",\n        \"priority\": \"medium\",\n        \"unread_count\": 0\n      }\n    ],\n    \"meta\": {\n      \"current_page\": 1,\n      \"per_page\": 1,\n      \"total\": 50\n    }\n  }\n}"
            }
          ]
        }
      ]
    },
    {
      "name": "خدمات البوابة",
      "description": "قوالب الرسائل مع حقول الدمج، والإرسال الجماعي المخصّص، ومعلومات الاستخدام. تتم المصادقة بتوكن SMS الخاص بك.",
      "item": [
        {
          "name": "قائمة قوالب الرسائل",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/gateway/v1/templates",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "gateway",
                "v1",
                "templates"
              ]
            },
            "description": "يعرض قوالب الرسائل المحفوظة لديك."
          },
          "response": [
            {
              "name": "ناجح",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Success\",\n  \"data\": [\n    {\n      \"name\": \"otp\",\n      \"text\": \"Hello {{name}}, your code is {{code}}\",\n      \"updatedAt\": \"2026-09-18T10:00:00.000Z\"\n    }\n  ]\n}"
            }
          ]
        },
        {
          "name": "إنشاء قالب أو استبداله",
          "request": {
            "method": "PUT",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{token}}"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{base_url}}/gateway/v1/templates/:name",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "gateway",
                "v1",
                "templates",
                ":name"
              ],
              "variable": [
                {
                  "key": "name",
                  "value": "",
                  "description": "اسم القالب: من 1 إلى 64 حرفًا أو رقمًا أو `_` أو `.` أو `-`."
                }
              ]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"text\": \"Hello {{name}}, your code is {{code|0000}}\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "description": "يحفظ قالبًا. استخدم `{{field}}` أو `{{field|default}}` لحقول الدمج.\n\n| Field | In | Type | Required | Description |\n|---|---|---|---|---|\n| `name` | path | string | yes | اسم القالب: من 1 إلى 64 حرفًا أو رقمًا أو `_` أو `.` أو `-`. |\n| `text` | body | string | yes | نص القالب مع حقول الدمج `{{field}}`، حتى 1600 حرفًا. |"
          },
          "response": [
            {
              "name": "تم الحفظ — وتم اكتشاف حقول الدمج",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Success\",\n  \"data\": {\n    \"name\": \"otp\",\n    \"text\": \"Hello {{name}}, your code is {{code|0000}}\",\n    \"fields\": [\n      \"name\",\n      \"code\"\n    ]\n  }\n}"
            }
          ]
        },
        {
          "name": "قراءة قالب",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/gateway/v1/templates/:name",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "gateway",
                "v1",
                "templates",
                ":name"
              ],
              "variable": [
                {
                  "key": "name",
                  "value": "",
                  "description": "اسم القالب."
                }
              ]
            },
            "description": "يعرض قالبًا محفوظًا.\n\n| Field | In | Type | Required | Description |\n|---|---|---|---|---|\n| `name` | path | string | yes | اسم القالب. |"
          },
          "response": [
            {
              "name": "ناجح",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Success\",\n  \"data\": {\n    \"name\": \"otp\",\n    \"text\": \"Hello {{name}}\"\n  }\n}"
            }
          ]
        },
        {
          "name": "حذف قالب",
          "request": {
            "method": "DELETE",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/gateway/v1/templates/:name",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "gateway",
                "v1",
                "templates",
                ":name"
              ],
              "variable": [
                {
                  "key": "name",
                  "value": "",
                  "description": "اسم القالب."
                }
              ]
            },
            "description": "يحذف قالبًا محفوظًا.\n\n| Field | In | Type | Required | Description |\n|---|---|---|---|---|\n| `name` | path | string | yes | اسم القالب. |"
          },
          "response": [
            {
              "name": "تم الحذف",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Success\",\n  \"data\": {\n    \"name\": \"otp\",\n    \"deleted\": true\n  }\n}"
            }
          ]
        },
        {
          "name": "إرسال جماعي مخصّص (حقول دمج)",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{token}}"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": {
              "raw": "{{base_url}}/gateway/v1/send-template",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "gateway",
                "v1",
                "send-template"
              ]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"senderName\": \"Corbit\",\n  \"template\": \"otp\",\n  \"vars\": {\n    \"code\": \"0000\"\n  },\n  \"recipients\": [\n    {\n      \"number\": \"966XXXXXXXXX\",\n      \"vars\": {\n        \"name\": \"Ali\",\n        \"code\": \"4821\"\n      }\n    },\n    \"966XXXXXXXXX\"\n  ]\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "description": "يرسل قالبًا محفوظًا (`template`) أو نصًّا مباشرًا `text` مع العناصر `{{field}}` / `{{field|default}}`. قيم `vars` الخاصة بكل مستلم تتقدّم على `vars` المشتركة. المستلمون الذين يتطابق نصهم بعد الدمج يُجمَّعون في إرسال جماعي واحد. إذا كان أي مستلم غير صالح يُرفض الطلب كاملًا ولا تُرسل أي رسالة.\n\n| Field | In | Type | Required | Description |\n|---|---|---|---|---|\n| `Idempotency-Key` | header | string | no | اختياري. إعادة المحاولة بنفس المفتاح تُرجع الرد الأول بدل الإرسال مرة أخرى. |\n| `senderName` | body | string | yes | اسم المرسِل المعتمد على حسابك. |\n| `template` | body | string | no | اسم قالب محفوظ (أو أرسل `text` بدلًا منه). |\n| `vars` | body | object | no | قيم الدمج المشتركة بين كل المستلمين. |\n| `recipients` | body | array | yes | أرقام، أو كائنات `{ number, vars }` لقيم خاصة بكل مستلم. حتى 1000 مستلم في الطلب. |"
          },
          "response": [
            {
              "name": "تم القبول (الحالة \"Partial\" إذا فشلت بعض المجموعات)",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Success\",\n  \"message\": null,\n  \"data\": {\n    \"recipients\": 2,\n    \"groups\": 2,\n    \"accepted\": 2,\n    \"rejected\": 0,\n    \"messages\": [\n      {\n        \"numbers\": 1,\n        \"id\": \"8493f201-…\",\n        \"ok\": true\n      }\n    ]\n  }\n}"
            },
            {
              "name": "الرصيد منتهٍ",
              "code": 402,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Error\",\n  \"message\": \"Insufficient balance (0). Please top up to continue sending.\",\n  \"code\": \"INSUFFICIENT_BALANCE\"\n}"
            },
            {
              "name": "اسم المرسِل غير معتمد",
              "code": 403,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Error\",\n  \"message\": \"Sender 'X' is not registered/approved for your account.\",\n  \"code\": \"SENDER_NOT_ALLOWED\"\n}"
            },
            {
              "name": "مستلمون غير صالحين / حقول ناقصة",
              "code": 422,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Error\",\n  \"code\": \"VALIDATION\",\n  \"message\": \"1 recipient(s) are invalid; nothing was sent.\",\n  \"errors\": [\n    {\n      \"index\": 1,\n      \"number\": \"966XXXXXXXXX\",\n      \"error\": \"missing fields: name\"\n    }\n  ]\n}"
            }
          ]
        },
        {
          "name": "حد الاستخدام وآخر رصيد معروف",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/gateway/v1/usage",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "gateway",
                "v1",
                "usage"
              ]
            },
            "description": "يعرض حد الطلبات الخاص بك وآخر رصيد معروف."
          },
          "response": [
            {
              "name": "ناجح",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Success\",\n  \"data\": {\n    \"rateLimit\": {\n      \"limit\": 1000,\n      \"windowSec\": 60\n    },\n    \"balance\": {\n      \"value\": 183,\n      \"asOf\": \"2026-09-18T10:00:00.000Z\"\n    }\n  }\n}"
            }
          ]
        },
        {
          "name": "أرشيف الرسائل المرسلة",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{token}}"
              }
            ],
            "url": {
              "raw": "{{base_url}}/gateway/v1/messages?limit=&cursor=&from=&to=&number=&sender=&status=",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "gateway",
                "v1",
                "messages"
              ],
              "query": [
                {
                  "key": "limit",
                  "value": "",
                  "description": "حجم الصفحة، من 1 إلى 200 (الافتراضي 50)."
                },
                {
                  "key": "cursor",
                  "value": "",
                  "description": "قيمة nextCursor من الصفحة السابقة، للمتابعة."
                },
                {
                  "key": "from",
                  "value": "",
                  "description": "أقدم تاريخ يُدرَج: `2026-09-01` أو تاريخ ووقت ISO أو ثوانٍ epoch."
                },
                {
                  "key": "to",
                  "value": "",
                  "description": "أحدث تاريخ يُدرَج (التاريخ وحده يشمل اليوم كاملًا)."
                },
                {
                  "key": "number",
                  "value": "",
                  "description": "رقم الوجهة، أو جزء منه."
                },
                {
                  "key": "sender",
                  "value": "",
                  "description": "اسم المرسِل."
                },
                {
                  "key": "status",
                  "value": "",
                  "description": "القيمة `1` تُرجع أيضًا حالة تسليم كل رسالة."
                }
              ]
            },
            "description": "جميع المعاملات اختيارية. يعرض الرسائل المرسلة من حسابك، الأحدث أولًا: الوجهة، اسم المرسِل، طول الرسالة، ومعرّف/معرّفات الرسالة — بدون نص الرسالة نفسه. يمكن التصفية بالتاريخ أو رقم الوجهة أو اسم المرسِل، وإضافة `status=1` لجلب حالة تسليم كل رسالة (`delivered` و`failed` و`pending`...). الحالة النهائية تُحفظ فتُقرأ مرة واحدة. للتصفّح استخدم `cursor` (قيمة `nextCursor` من الصفحة السابقة)؛ وقد تعود صفحة مصفّاة بأقل من `limit` — تابع `nextCursor` حتى يصبح `null`.\n\n| Field | In | Type | Required | Description |\n|---|---|---|---|---|\n| `limit` | query | integer | no | حجم الصفحة، من 1 إلى 200 (الافتراضي 50). |\n| `cursor` | query | string | no | قيمة nextCursor من الصفحة السابقة، للمتابعة. |\n| `from` | query | string | no | أقدم تاريخ يُدرَج: `2026-09-01` أو تاريخ ووقت ISO أو ثوانٍ epoch. |\n| `to` | query | string | no | أحدث تاريخ يُدرَج (التاريخ وحده يشمل اليوم كاملًا). |\n| `number` | query | string | no | رقم الوجهة، أو جزء منه. |\n| `sender` | query | string | no | اسم المرسِل. |\n| `status` | query | string | no | القيمة `1` تُرجع أيضًا حالة تسليم كل رسالة. |"
          },
          "response": [
            {
              "name": "OK — newest first",
              "code": 200,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Success\",\n  \"data\": {\n    \"messages\": [\n      {\n        \"ts\": \"2026-09-24T10:38:17.000Z\",\n        \"ok\": true,\n        \"destCount\": 1,\n        \"length\": 14,\n        \"to\": [\n          \"201008834539\"\n        ],\n        \"sender\": \"School1\",\n        \"id\": [\n          \"30be7f80-e587-46ac-a5b3-0f89d21c03dd\"\n        ],\n        \"status\": \"delivered\"\n      }\n    ],\n    \"nextCursor\": null\n  }\n}"
            },
            {
              "name": "Invalid date",
              "code": 400,
              "_postman_previewlanguage": "json",
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"status\": \"Error\",\n  \"message\": \"\\\"tomorrow\\\" is not a valid date: use 2026-09-24, an ISO date-time, or epoch seconds.\",\n  \"code\": \"VALIDATION\"\n}"
            }
          ]
        }
      ]
    }
  ],
  "variable": [
    {
      "key": "base_url",
      "value": "https://api.corbit.sa"
    },
    {
      "key": "token",
      "value": ""
    }
  ]
}