{"openapi":"3.1.0","info":{"title":"Comvo API","version":"2.1.8","description":"باستخدام Comvo API يمكنك إنشاء دعوات استبيان مخصصة لكل شخص، وإرسال الاستبيانات تلقائيًا بناءً على أحداث المعاملات، وقراءة الردود والمقاييس، ومزامنة الهيكل التنظيمي، واستقبال الأحداث عبر webhook.\n\n## البدء السريع\n\n1. أنشئ مفتاحًا في اللوحة من شاشة **Ayarlar › API Anahtarları** (الإعدادات › مفاتيح API). أجرِ التجارب الأولى باستخدام مفتاح `sk_test_`: الدعوات والردود التي تُنشأ بمفتاح الاختبار تُحفظ منفصلة عن البيانات الفعلية ولا تدخل في التقارير.\n2. تحقق من المفتاح:\n\n```bash\ncurl https://my.comvo.com.tr/api/me \\\n  -H \"Authorization: Bearer sk_test_...\"\n```\n\n3. احصل على رابط استبيان مخصص لمعاملة (طلب شراء، سجل خدمة):\n\n```bash\ncurl -X POST https://my.comvo.com.tr/api/invitations \\\n  -H \"Authorization: Bearer sk_test_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: siparis-98123\" \\\n  -d '{\n    \"survey\": \"srv_...\",\n    \"org_unit\": \"IST-034\",\n    \"transaction_ref\": \"98123\",\n    \"contact\": { \"external_id\": \"C-5521\", \"name\": \"Ayşe Yılmaz\", \"email\": \"ayse@example.com\" }\n  }'\n# 201 { \"id\": \"inv_...\", \"url\": \"https://my.comvo.com.tr/s/...\", ... }\n```\n\nالحقل `url` في الرد هو رابط الاستخدام الواحد الذي يُرسل إلى الشخص، ولا يُعاد إلا في هذا الرد. يجب أن يكون كل حقل في السياق (الوحدة، رقم المعاملة، رقم العميل، بيانات الاتصال، الحقول المخصصة) مذكورًا في إشعار الخصوصية الساري للعلامة التجارية؛ وإلا يُرفض الطلب بالخطأ `privacy_notice_not_covering`.\n\n## المصادقة\n\nأرسل الترويسة `Authorization: Bearer sk_live_...` مع كل طلب. لا يستطيع المفتاح استخدام إلا النطاقات (scopes) التي اختيرت عند إنشائه؛ والمفتاح المقيد بوحدة لا يرى إلا تلك الوحدة والوحدات التابعة لها. مفاتيح الاختبار (`sk_test_`) لا تصل إلى البيانات الفعلية.\n\n## أمان التكرار (Idempotency)\n\nأرسل الترويسة `Idempotency-Key` في طلبات الكتابة. الطلب نفسه الذي يصل بالمفتاح نفسه خلال 24 ساعة لا يُعالج مرة أخرى؛ ويُعاد الرد الأول مع الترويسة `Idempotent-Replayed: true`. إذا وصل المفتاح نفسه بمحتوى مختلف، يُعاد 422.\n\n## ترقيم الصفحات\n\nالقوائم تعتمد على المؤشر. أرسل قيمة `next_cursor` من الرد في المعامل `?cursor=`؛ وعندما تكون قيمة `has_more` هي `false` تكون القائمة قد انتهت. الحد الأقصى لـ `limit` هو 100.\n\n## حد المعدل\n\nيمكن لكل مفتاح إرسال 600 طلب في الدقيقة، و30 طلبًا في نقاط النهاية المجمعة. راقب الترويسات `RateLimit-Limit` و`RateLimit-Remaining` و`RateLimit-Reset`؛ وعند تلقي الرد 429 انتظر المدة المحددة في `Retry-After`.\n\n## الوقت والمعرفات والبيانات الشخصية\n\nالأوقات بتنسيق ISO 8601 وبتوقيت UTC. المعرفات ذات بادئات: `srv_` (استبيان)، `inv_` (دعوة)، `rsp_` (رد)، `org_` (وحدة). لا يظهر الاسم والبريد الإلكتروني والهاتف في الردود إلا مع النطاق `responses:pii`؛ وإذا اختار الشخص البقاء مجهول الهوية فلا تظهر أبدًا.\n\n## Webhook\n\nلاستقبال الأحداث، أضف عنوانًا في اللوحة من شاشة **Ayarlar › Webhook'lar** (الإعدادات › Webhook) أو عبر نقطة النهاية `/webhook-endpoints`. يُوقَّع كل طلب بهذه الترويسة:\n\n```\nWebhook-Signature: t=<الوقت>,v1=<HMAC-SHA256(المفتاح السري, \"الوقت.المحتوى\")>\n```\n\nفي اللوحة، يحتوي تبويب **Teknik Rehber** (الدليل التقني) لكل webhook على شيفرة تحقق بلغات PHP وNode.js وPython مع حمولة نموذجية. استجب للطلب برمز 2xx خلال 10 ثوانٍ؛ وإلا تُعاد المحاولة وفق سياسة الأخطاء الخاصة بالـ webhook.\n\n## رموز الأخطاء\n\nالأخطاء بتنسيق [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `application/problem+json`. حدد سلوكك بناءً على الحقل `code`؛ أما الحقل `detail` فهو موجه للبشر.\n\n```json\n{ \"type\": \"https://my.comvo.com.tr/developers#errors-validation_failed\", \"title\": \"Doğrulama hatası\", \"status\": 422,\n  \"code\": \"validation_failed\", \"detail\": \"...\", \"errors\": { \"survey\": [\"Anket bulunamadı.\"] } }\n```\n\n| الرمز | الحالة | المعنى وما يجب فعله |\n| --- | --- | --- |\n| `unauthenticated` | 401 | ترويسة Authorization مفقودة أو تنسيقها خاطئ. |\n| `invalid_key` | 401 | المفتاح غير موجود أو أُلغي أو انتهت صلاحيته. أنشئ مفتاحًا جديدًا من اللوحة. |\n| `insufficient_scope` | 403 | لا يملك المفتاح النطاق اللازم لهذه العملية (مذكور في الحقل required_scope). أنشئ المفتاح بالنطاق الجديد. |\n| `outside_scope` | 403 | المفتاح المقيد بوحدة لا يمكنه الوصول إلى هذا السجل أو إلى عملية على مستوى المستأجر بالكامل. |\n| `forbidden` | 403 | العملية غير مسموح بها. |\n| `not_found` | 404 | السجل غير موجود أو خارج نطاق وصول المفتاح (الوحدة، الوضع الفعلي/الاختبار). |\n| `method_not_allowed` | 405 | هذا العنوان لا يدعم طريقة HTTP هذه. |\n| `invitation_completed` | 409 | لا يمكن إلغاء دعوة تم الرد عليها. |\n| `idempotency_in_progress` | 409 | الطلب الأول بنفس Idempotency-Key ما زال قيد المعالجة؛ أعد المحاولة بعد قليل. |\n| `invalid_idempotency_key` | 400 | Idempotency-Key فارغ أو أطول من 255 حرفًا. |\n| `idempotency_mismatch` | 422 | استُخدم Idempotency-Key نفسه مع محتوى مختلف. |\n| `validation_failed` | 422 | توجد أخطاء في البيانات المرسلة؛ التفاصيل لكل حقل في errors. |\n| `survey_not_live` | 422 | الاستبيان غير منشور؛ لا يمكن فتح دعوة. |\n| `unknown_context_field` | 422 | حقل في السياق غير معرّف في اللوحة ضمن KVKK ve Veri > Alanlar (KVKK والبيانات > الحقول؛ KVKK هو قانون حماية البيانات الشخصية في تركيا رقم 6698) (fields). |\n| `privacy_notice_not_covering` | 422 | الحقول غير مذكورة في إشعار الخصوصية الساري للعلامة التجارية (fields). أضفها إلى الإشعار ثم انشره. |\n| `invalid_assignee` | 422 | العضو المراد إسناده غير موجود أو لا يملك صلاحية إدارة هذا الرد. |\n| `invalid_level` | 422 | اسم المستوى غير موجود، أو لا يوجد مستوى معرّف تحت الوحدة الأم. |\n| `range_too_long` | 422 | نطاق المقاييس 366 يومًا كحد أقصى. |\n| `rate_limited` | 429 | تم تجاوز حد المعدل؛ انتظر المدة المحددة في Retry-After. |\n| `server_error` | 500 | خطأ غير متوقع. يمكنك إعادة المحاولة بأمان باستخدام Idempotency-Key. |"},"servers":[{"url":"https://my.comvo.com.tr/api"}],"tags":[{"name":"الهوية"},{"name":"الاستبيانات"},{"name":"الأحداث"},{"name":"الدعوات"},{"name":"جهات الاتصال"},{"name":"الردود"},{"name":"المؤسسة"},{"name":"المقاييس"},{"name":"Webhook"}],"paths":{"/me":{"get":{"tags":["الهوية"],"summary":"معلومات المفتاح","security":[{"bearer":[]}],"x-scope":"","description":"لتجربة التكامل: هل المفتاح صالح وما النطاقات المتاحة له.","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"getMe"}},"/surveys":{"get":{"tags":["الاستبيانات"],"summary":"عرض قائمة الاستبيانات","security":[{"bearer":[]}],"x-scope":"surveys:read","description":"\n\nالنطاق: `surveys:read`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurveyList"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"listSurveys","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}]}},"/surveys/{id}":{"get":{"tags":["الاستبيانات"],"summary":"الاستبيان وأسئلته","security":[{"bearer":[]}],"x-scope":"surveys:read","description":"\n\nالنطاق: `surveys:read`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Survey"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"getSurvey","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"srv_..."}]}},"/events":{"post":{"tags":["الأحداث"],"summary":"إرسال حدث","security":[{"bearer":[]}],"x-scope":"events:write","description":"أرسل أحداث المعاملات (تم تسليم الطلب، أُغلق سجل الخدمة، انتهت المكالمة). لكل مشغّل نشط مرتبط بهذا النوع في اللوحة يُتحقق مما يلي: هل الاستبيان منشور، هل ألغى الشخص اشتراكه، حد التكرار، والقناة (بحسب بريد الشخص الإلكتروني أو هاتفه)؛ وإذا استوفيت الشروط تُفتح دعوة وتُجدول رسالة مؤجلة. استخدم `Idempotency-Key` لتجنب إرسال الحدث نفسه مرتين.\n\nالنطاق: `events:write`","responses":{"202":{"description":"تم الاستلام؛ يُعاد أي مشغّل سيرسل استبيانًا ومتى وعبر أي قناة، أو سبب تخطيه","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"400":{"$ref":"#/components/responses/E400"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"createEvent","parameters":[{"$ref":"#/components/parameters/idempotency"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventInput"}}}}}},"/events/batch":{"post":{"tags":["الأحداث"],"summary":"أحداث مجمعة (500 كحد أقصى)","security":[{"bearer":[]}],"x-scope":"events:write","description":"\n\nالنطاق: `events:write`","responses":{"202":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventBatchResult"}}}},"400":{"$ref":"#/components/responses/E400"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"createEventBatch","parameters":[{"$ref":"#/components/parameters/idempotency"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["events"],"properties":{"events":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/EventInput"}}}}}}}}},"/events/{id}":{"get":{"tags":["الأحداث"],"summary":"نتيجة الحدث","security":[{"bearer":[]}],"x-scope":"events:write","description":"\n\nالنطاق: `events:write`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"getEvent","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"evt_..."}]}},"/contacts/{external_id}":{"get":{"tags":["جهات الاتصال"],"summary":"جهة الاتصال","security":[{"bearer":[]}],"x-scope":"contacts:write","description":"\n\nالنطاق: `contacts:write`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"getContact","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"رقم العميل لديكم"}]},"put":{"tags":["جهات الاتصال"],"summary":"إنشاء جهة اتصال أو تحديثها","security":[{"bearer":[]}],"x-scope":"contacts:write","description":"مع `opted_out: true` تُستبعد جهة الاتصال من رسائل الاستبيان (للمزامنة مع نظام إدارة الموافقات لديكم).\n\nالنطاق: `contacts:write`","responses":{"200":{"description":"تم التحديث","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"201":{"description":"تم الإنشاء","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"putContact","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"رقم العميل لديكم"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactInput"}}}}},"delete":{"tags":["جهات الاتصال"],"summary":"KVKK: حذف جهة الاتصال","security":[{"bearer":[]}],"x-scope":"contacts:write","description":"يُحذف سجل جهة الاتصال وبيانات الاتصال؛ وتُفصل ردودها عنها وتصبح مجهولة الهوية (تبقى في الإحصاءات)، وتُحذف حقول السياق الشخصية وإجابات التواصل، وتُلغى الرسائل المعلقة. لا يمكن التراجع عن ذلك.\n\nالنطاق: `contacts:write`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactErasure"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"eraseContact","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"رقم العميل لديكم"}]}},"/contacts/{external_id}/export":{"get":{"tags":["جهات الاتصال"],"summary":"KVKK: تصدير بيانات جهة الاتصال","security":[{"bearer":[]}],"x-scope":"contacts:write","description":"لطلب حق الوصول: جهة الاتصال والدعوات والرسائل والردود.\n\nالنطاق: `contacts:write`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactExport"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"exportContact","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"رقم العميل لديكم"}]}},"/invitations":{"post":{"tags":["الدعوات"],"summary":"إنشاء دعوة","security":[{"bearer":[]}],"x-scope":"invitations:write","description":"رابط مخصص للاستخدام مرة واحدة. يجب أن يكون كل حقل في السياق مذكورًا في إشعار الخصوصية الساري؛ وإلا `privacy_notice_not_covering` (422).\n\nالنطاق: `invitations:write`","responses":{"201":{"description":"تم الإنشاء؛ `url` هو الرابط الذي يُرسل إلى الشخص","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"}}}},"400":{"$ref":"#/components/responses/E400"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"createInvitation","parameters":[{"$ref":"#/components/parameters/idempotency"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationInput"}}}}}},"/invitations/batch":{"post":{"tags":["الدعوات"],"summary":"دعوات مجمعة (1000 كحد أقصى)","security":[{"bearer":[]}],"x-scope":"invitations:write","description":"البند الخاطئ لا يوقف البنود الأخرى؛ تُعاد النتائج بترتيب البنود.\n\nالنطاق: `invitations:write`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResult"}}}},"400":{"$ref":"#/components/responses/E400"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"createInvitationBatch","parameters":[{"$ref":"#/components/parameters/idempotency"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["invitations"],"properties":{"invitations":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/InvitationInput"}}}}}}}}},"/invitations/{id}":{"get":{"tags":["الدعوات"],"summary":"حالة الدعوة","security":[{"bearer":[]}],"x-scope":"invitations:write","description":"\n\nالنطاق: `invitations:write`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"getInvitation","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"inv_..."}]}},"/invitations/{id}/cancel":{"post":{"tags":["الدعوات"],"summary":"إلغاء الدعوة","security":[{"bearer":[]}],"x-scope":"invitations:write","description":"\n\nالنطاق: `invitations:write`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"}}}},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"cancelInvitation","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"inv_..."},{"$ref":"#/components/parameters/idempotency"}]}},"/responses":{"get":{"tags":["الردود"],"summary":"عرض قائمة الردود","security":[{"bearer":[]}],"x-scope":"responses:read","description":"الردود المكتملة فقط، بحسب وضع المفتاح (فعلي/اختبار) وتقييد الوحدة. البيانات الشخصية فقط مع النطاق `responses:pii`.\n\nالنطاق: `responses:read`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseList"}}}},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"listResponses","parameters":[{"name":"survey","in":"query","required":false,"schema":{"type":"string"},"description":"معرّف الاستبيان"},{"name":"org_unit","in":"query","required":false,"schema":{"type":"string"},"description":"رمز الوحدة أو معرّفها (بما في ذلك الشجرة الفرعية)"},{"name":"touchpoint","in":"query","required":false,"schema":{"type":"string"},"description":"مفتاح نقطة الاتصال"},{"name":"transaction_ref","in":"query","required":false,"schema":{"type":"string"},"description":"رقم المعاملة (طلب شراء، إيصال)"},{"name":"case_status","in":"query","required":false,"schema":{"enum":["new","in_progress","resolved"]},"description":"وضع الحالة"},{"name":"priority","in":"query","required":false,"schema":{"enum":["normal","high","critical"]},"description":"الأولوية"},{"name":"completed_since","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"المكتملة بعد هذا الوقت"},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"المتغيرة بعد هذا الوقت (للمزامنة)"},{"name":"order","in":"query","required":false,"schema":{"enum":["asc","desc"]},"description":"الترتيب (الافتراضي desc)"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}]}},"/responses/{id}":{"get":{"tags":["الردود"],"summary":"الرد","security":[{"bearer":[]}],"x-scope":"responses:read","description":"\n\nالنطاق: `responses:read`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"getResponse","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"rsp_..."}]},"patch":{"tags":["الردود"],"summary":"تغيير وضع الحالة أو الأولوية أو المسؤول","security":[{"bearer":[]}],"x-scope":"responses:write","description":"يُسجَّل التغيير في سجل الحالة باسم \"API: اسم المفتاح\"، ويُرسل حدث case.* إلى الـ webhook المشتركة.\n\nالنطاق: `responses:write`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"updateResponse","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"rsp_..."},{"$ref":"#/components/parameters/idempotency"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseUpdate"}}}}}},"/responses/{id}/notes":{"post":{"tags":["الردود"],"summary":"إضافة ملاحظة إلى الحالة","security":[{"bearer":[]}],"x-scope":"responses:write","description":"\n\nالنطاق: `responses:write`","responses":{"201":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Note"}}}},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"createNote","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"rsp_..."},{"$ref":"#/components/parameters/idempotency"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","maxLength":5000}}}}}}}},"/org-units":{"get":{"tags":["المؤسسة"],"summary":"عرض قائمة الوحدات","security":[{"bearer":[]}],"x-scope":"org:read","description":"\n\nالنطاق: `org:read`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgUnitList"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"listOrgUnits","parameters":[{"name":"updated_since","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"المتغيرة بعد هذا الوقت"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}]}},"/org-units/{code}":{"get":{"tags":["المؤسسة"],"summary":"الوحدة","security":[{"bearer":[]}],"x-scope":"org:read","description":"\n\nالنطاق: `org:read`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgUnit"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"getOrgUnit","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"},"description":"رمز الوحدة أو معرّفها"}]},"put":{"tags":["المؤسسة"],"summary":"إنشاء وحدة أو تحديثها برمزها","security":[{"bearer":[]}],"x-scope":"org:write","description":"\n\nالنطاق: `org:write`","responses":{"200":{"description":"تم التحديث","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgUnit"}}}},"201":{"description":"تم الإنشاء","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgUnit"}}}},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"putOrgUnit","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"},"description":"رمز الوحدة في النظام الخارجي (حروف، أرقام، . _ -)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgUnitInput"}}}}}},"/people/{code}":{"put":{"tags":["المؤسسة"],"summary":"إنشاء موظف أو تحديثه برمزه","security":[{"bearer":[]}],"x-scope":"org:write","description":"\n\nالنطاق: `org:write`","responses":{"200":{"description":"تم التحديث","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Person"}}}},"201":{"description":"تم الإنشاء","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Person"}}}},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"putPerson","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"},"description":"رمز الموظف"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"org_unit":{"type":"string"},"email":{"type":"string","format":"email"},"is_active":{"type":"boolean"}}}}}}}},"/touchpoints":{"get":{"tags":["المؤسسة"],"summary":"عرض قائمة نقاط الاتصال","security":[{"bearer":[]}],"x-scope":"org:read","description":"\n\nالنطاق: `org:read`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TouchpointList"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"listTouchpoints","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}]}},"/touchpoints/{key}":{"put":{"tags":["المؤسسة"],"summary":"إنشاء نقطة اتصال أو تحديثها بمفتاحها","security":[{"bearer":[]}],"x-scope":"org:write","description":"\n\nالنطاق: `org:write`","responses":{"200":{"description":"تم التحديث","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Touchpoint"}}}},"201":{"description":"تم الإنشاء","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Touchpoint"}}}},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"putTouchpoint","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"},"description":"المفتاح (حروف صغيرة، أرقام، _)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"is_active":{"type":"boolean"}}}}}}}},"/metrics":{"get":{"tags":["المقاييس"],"summary":"CSAT وNPS وCES والتفصيل","security":[{"bearer":[]}],"x-scope":"reports:read","description":"الحساب نفسه المستخدم في تقارير اللوحة: الردود الفعلية المكتملة غير المشبوهة؛ والأيام بحسب المنطقة الزمنية للمستأجر.\n\nالنطاق: `reports:read`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Metrics"}}}},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"getMetrics","parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"group_by","in":"query","required":false,"schema":{"enum":["org_unit","touchpoint","person","channel","survey","day"]},"description":"التفصيل"},{"name":"level","in":"query","required":false,"schema":{"type":"string"},"description":"اسم المستوى لـ group_by=org_unit (مثل: المنطقة)"},{"name":"survey","in":"query","required":false,"schema":{"type":"string"},"description":"معرّف الاستبيان"},{"name":"org_unit","in":"query","required":false,"schema":{"type":"string"},"description":"رمز الوحدة (الشجرة الفرعية)"},{"name":"touchpoint","in":"query","required":false,"schema":{"type":"string"},"description":"معرّف نقطة الاتصال"},{"name":"channel","in":"query","required":false,"schema":{"type":"string"},"description":"qr, email, sms, link"}]}},"/webhook-endpoints":{"get":{"tags":["Webhook"],"summary":"عرض قائمة Webhook","security":[{"bearer":[]}],"x-scope":"webhooks:manage","description":"\n\nالنطاق: `webhooks:manage`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointList"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"listWebhookEndpoints","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}]},"post":{"tags":["Webhook"],"summary":"إنشاء Webhook","security":[{"bearer":[]}],"x-scope":"webhooks:manage","description":"\n\nالنطاق: `webhooks:manage`","responses":{"201":{"description":"تم الإنشاء؛ `secret` في هذا الرد فقط","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"createWebhookEndpoint","parameters":[{"$ref":"#/components/parameters/idempotency"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointInput"}}}}}},"/webhook-endpoints/{id}":{"get":{"tags":["Webhook"],"summary":"Webhook","security":[{"bearer":[]}],"x-scope":"webhooks:manage","description":"\n\nالنطاق: `webhooks:manage`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"getWebhookEndpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"whk_..."}]},"patch":{"tags":["Webhook"],"summary":"تحديث Webhook","security":[{"bearer":[]}],"x-scope":"webhooks:manage","description":"\n\nالنطاق: `webhooks:manage`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"updateWebhookEndpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"whk_..."},{"$ref":"#/components/parameters/idempotency"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointInput"}}}}},"delete":{"tags":["Webhook"],"summary":"حذف Webhook","security":[{"bearer":[]}],"x-scope":"webhooks:manage","description":"\n\nالنطاق: `webhooks:manage`","responses":{"204":{"description":"تم الحذف"},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"deleteWebhookEndpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"whk_..."}]}},"/webhook-deliveries":{"get":{"tags":["Webhook"],"summary":"سجلات الإرسال","security":[{"bearer":[]}],"x-scope":"webhooks:manage","description":"\n\nالنطاق: `webhooks:manage`","responses":{"200":{"description":"ناجح","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryList"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"listWebhookDeliveries","parameters":[{"name":"endpoint","in":"query","required":false,"schema":{"type":"string"},"description":"whk_..."},{"name":"status","in":"query","required":false,"schema":{"enum":["pending","sending","retrying","succeeded","failed"]},"description":"الحالة"},{"name":"event","in":"query","required":false,"schema":{"type":"string"},"description":"الحدث"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}]}},"/webhook-deliveries/{id}/redeliver":{"post":{"tags":["Webhook"],"summary":"إعادة الإرسال","security":[{"bearer":[]}],"x-scope":"webhooks:manage","description":"\n\nالنطاق: `webhooks:manage`","responses":{"202":{"description":"أُضيف إلى قائمة الانتظار","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"redeliverWebhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"whd_..."},{"$ref":"#/components/parameters/idempotency"}]}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"sk_live_... / sk_test_..."}},"parameters":{"limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"cursor":{"name":"cursor","in":"query","schema":{"type":"string"},"description":"قيمة next_cursor من الصفحة السابقة"},"idempotency":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"يمنع معالجة الطلب نفسه مرتين (24 ساعة)"}},"responses":{"E400":{"description":"طلب غير صالح","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"E401":{"description":"تعذرت المصادقة","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"E403":{"description":"نطاق غير كافٍ أو خارج نطاق الوصول","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"E404":{"description":"غير موجود (أو خارج نطاق المفتاح)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"E409":{"description":"تعارض","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"E422":{"description":"خطأ في التحقق أو في قاعدة عمل","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"E429":{"description":"تم تجاوز حد المعدل","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"Problem":{"type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string","description":"رمز خطأ قابل للقراءة آليًا"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"fields":{"type":"array","items":{"type":"string"}},"required_scope":{"type":"string"}}},"Me":{"type":"object","required":["object","id","name","tenant","scopes","org_unit","livemode","expires_at"],"additionalProperties":false,"properties":{"object":{"const":"api_key"},"id":{"type":"string","pattern":"^key_[0-9a-z]{26}$","examples":["key_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"name":{"type":"string"},"tenant":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","pattern":"^ten_[0-9a-z]{26}$","examples":["ten_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"name":{"type":"string"}}},"scopes":{"type":"array","items":{"enum":["surveys:read","invitations:write","events:write","contacts:write","responses:read","responses:pii","responses:write","org:read","org:write","reports:read","webhooks:manage"]}},"org_unit":{"type":["string","null"]},"livemode":{"type":"boolean"},"expires_at":{"type":["string","null"],"format":"date-time"}}},"Survey":{"type":"object","required":["object","id","name","status","live","version","locales","touchpoint","created_at","updated_at"],"additionalProperties":false,"properties":{"object":{"const":"survey"},"id":{"type":"string","pattern":"^srv_[0-9a-z]{26}$","examples":["srv_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"name":{"type":"string"},"status":{"enum":["draft","active","paused","archived"]},"live":{"type":"boolean"},"version":{"type":["integer","null"]},"locales":{"type":"array","items":{"type":"string"}},"touchpoint":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"questions":{"type":"array","items":{"type":"object","required":["key","type","title","metric","required","options"],"properties":{"key":{"type":"string"},"type":{"type":"string"},"title":{"type":"string"},"metric":{"type":["string","null"]},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"object","required":["key","label"],"properties":{"key":{"type":"string"},"label":{"type":"string"}}}}}}}}},"InvitationInput":{"type":"object","required":["survey"],"additionalProperties":false,"properties":{"survey":{"type":"string","description":"معرّف الاستبيان (srv_...)"},"org_unit":{"type":"string","description":"رمز الوحدة (مثل IST-034) أو معرّفها"},"person":{"type":"string","description":"رمز الموظف"},"touchpoint":{"type":"string","description":"مفتاح نقطة الاتصال؛ وإن لم يُحدد فمفتاح الاستبيان"},"transaction_ref":{"type":"string","maxLength":128,"description":"رقم الطلب أو الإيصال أو سجل الخدمة"},"contact":{"type":"object","additionalProperties":false,"properties":{"external_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"locale":{"enum":["tr","en","ar","ru","de"]}}},"context":{"type":"object","description":"حقول السياق المعرّفة في اللوحة؛ يجب أن تكون مذكورة في إشعار الخصوصية","additionalProperties":{"type":["string","number","boolean"]}},"max_uses":{"type":"integer","minimum":1,"maximum":100,"default":1},"expires_at":{"type":"string","format":"date-time","description":"الافتراضي 30 يومًا"}}},"Invitation":{"type":"object","required":["object","id","survey","status","url","channel","org_unit","person","touchpoint","contact","transaction_ref","context","max_uses","uses","expires_at","livemode","created_at"],"additionalProperties":false,"properties":{"object":{"const":"invitation"},"id":{"type":"string","pattern":"^inv_[0-9a-z]{26}$","examples":["inv_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"survey":{"type":"string","pattern":"^srv_[0-9a-z]{26}$","examples":["srv_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"status":{"enum":["pending","sent","started","responded","cancelled","expired"]},"url":{"type":["string","null"],"format":"uri","description":"رابط مخصص للشخص. لا يُملأ إلا في رد الإنشاء؛ والنظام لا يحتفظ بالرمز المميز."},"channel":{"type":"string"},"org_unit":{"type":["string","null"]},"person":{"type":["string","null"]},"touchpoint":{"type":["string","null"]},"contact":{"type":["object","null"],"required":["id","external_id"],"properties":{"id":{"type":"string","pattern":"^con_[0-9a-z]{26}$","examples":["con_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"external_id":{"type":["string","null"]}}},"transaction_ref":{"type":["string","null"]},"context":{"type":"object"},"max_uses":{"type":"integer"},"uses":{"type":"integer"},"expires_at":{"type":["string","null"],"format":"date-time"},"livemode":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"BatchResult":{"type":"object","required":["object","created","failed","results"],"properties":{"object":{"const":"batch_result"},"created":{"type":"integer"},"failed":{"type":"integer"},"results":{"type":"array","items":{"type":"object","required":["index","ok"],"properties":{"index":{"type":"integer"},"ok":{"type":"boolean"},"invitation":{"$ref":"#/components/schemas/Invitation"},"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}}}}}},"Response":{"type":"object","required":["object","id","survey","unit","touchpoint","person","channel","locale","completed_at","transaction_ref","scores","case","anonymous","contact","answers","panel_url"],"additionalProperties":false,"properties":{"object":{"const":"response"},"id":{"type":"string","pattern":"^rsp_[0-9a-z]{26}$","examples":["rsp_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"survey":{"type":"object","required":["id","name","version"],"properties":{"id":{"type":"string","pattern":"^srv_[0-9a-z]{26}$","examples":["srv_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"name":{"type":"string"},"version":{"type":"integer"}}},"unit":{"type":["object","null"],"required":["id","name","code","level"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^org_[0-9a-z]{26}$","examples":["org_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"name":{"type":"string"},"code":{"type":["string","null"]},"level":{"type":["string","null"]}}},"touchpoint":{"type":["object","null"],"required":["id","name"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^tch_[0-9a-z]{26}$","examples":["tch_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"name":{"type":"string"}}},"person":{"type":["object","null"],"required":["id","name"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^per_[0-9a-z]{26}$","examples":["per_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"name":{"type":"string"}}},"channel":{"type":"string"},"locale":{"type":"string"},"completed_at":{"type":["string","null"],"format":"date-time"},"transaction_ref":{"type":["string","null"]},"scores":{"type":"object","required":["csat","ces","nps"],"properties":{"csat":{"type":["number","null"]},"ces":{"type":["number","null"]},"nps":{"type":["integer","null"]}}},"case":{"type":"object","required":["status","priority","flagged","assignee","due_at"],"properties":{"status":{"enum":["new","in_progress","resolved"]},"priority":{"enum":["normal","high","critical"]},"flagged":{"type":"boolean"},"assignee":{"type":["object","null"],"required":["id","name"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^mem_[0-9a-z]{26}$","examples":["mem_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"name":{"type":"string"}}},"due_at":{"type":["string","null"],"format":"date-time"},"resolution_code":{"type":["string","null"],"description":"رمز الإغلاق المختار عند الحل (في اللوحة: Vaka Ayarları (إعدادات الحالات))"},"follow_up_result":{"enum":["resolved","partly","not_resolved",null],"description":"إجابة العميل في استبيان الرضا عن الحل"}}},"anonymous":{"type":"boolean"},"contact":{"type":["object","null"],"description":"فقط مع النطاق `responses:pii` وإذا لم يكن الشخص مجهول الهوية","properties":{"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"external_id":{"type":["string","null"]}}},"answers":{"type":"array","items":{"type":"object","required":["key","type","title","metric","value","label"],"additionalProperties":false,"properties":{"key":{"type":"string"},"type":{"type":"string"},"title":{"type":"string"},"metric":{"type":["string","null"]},"value":{"description":"رقم أو مفتاح خيار أو مصفوفة مفاتيح أو نص"},"label":{"description":"تسمية الخيار (قد تكون مصفوفة) أو null"}}}},"panel_url":{"type":"string","format":"uri"}}},"ResponseUpdate":{"type":"object","additionalProperties":false,"properties":{"case_status":{"enum":["new","in_progress","resolved"]},"priority":{"enum":["normal","high","critical"]},"assignee":{"type":["string","null"],"description":"معرّف العضو (mem_...)؛ null = إزالة الإسناد"},"resolution_code":{"type":["string","null"],"description":"مفتاح رمز الإغلاق، مع case_status=resolved"}}},"Note":{"type":"object","required":["object","id","response","body","created_at"],"properties":{"object":{"const":"note"},"id":{"type":"string","pattern":"^act_[0-9a-z]{26}$","examples":["act_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"response":{"type":"string","pattern":"^rsp_[0-9a-z]{26}$","examples":["rsp_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"body":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"OrgUnit":{"type":"object","required":["object","id","code","name","level","depth","parent","city","address","is_active","updated_at"],"additionalProperties":false,"properties":{"object":{"const":"org_unit"},"id":{"type":"string","pattern":"^org_[0-9a-z]{26}$","examples":["org_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"code":{"type":["string","null"]},"name":{"type":"string"},"level":{"type":["string","null"]},"depth":{"type":["integer","null"]},"parent":{"type":["string","null"]},"city":{"type":["string","null"]},"address":{"type":["string","null"]},"is_active":{"type":"boolean"},"updated_at":{"type":"string","format":"date-time"}}},"OrgUnitInput":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string"},"parent":{"type":["string","null"],"description":"رمز الوحدة الأم؛ إذا تغير تُنقل الوحدة"},"level":{"type":"string","description":"اسم المستوى؛ إذا لم يُحدد فالمستوى الذي يلي مستوى الوحدة الأم"},"city":{"type":"string"},"address":{"type":"string"},"review_url":{"type":"string","format":"uri"},"is_active":{"type":"boolean"}}},"Person":{"type":"object","required":["object","id","code","name","org_unit","is_active"],"additionalProperties":false,"properties":{"object":{"const":"person"},"id":{"type":"string","pattern":"^per_[0-9a-z]{26}$","examples":["per_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"code":{"type":["string","null"]},"name":{"type":"string"},"org_unit":{"type":["string","null"]},"is_active":{"type":"boolean"}}},"Touchpoint":{"type":"object","required":["object","id","key","name","description","is_active"],"additionalProperties":false,"properties":{"object":{"const":"touchpoint"},"id":{"type":"string","pattern":"^tch_[0-9a-z]{26}$","examples":["tch_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"is_active":{"type":"boolean"}}},"MetricSet":{"type":"object","required":["count","csat","satisfied","ces","nps","promoters","detractors","nps_count","critical"],"properties":{"count":{"type":"integer"},"csat":{"type":["number","null"]},"satisfied":{"type":["number","null"],"description":"نسبة CSAT >= 4"},"ces":{"type":["number","null"]},"nps":{"type":["integer","null"]},"promoters":{"type":["number","null"]},"detractors":{"type":["number","null"]},"nps_count":{"type":"integer"},"critical":{"type":"integer"},"review_offered":{"type":"integer","description":"عُرضت عليهم دعوة تقييم Google"},"review_clicked":{"type":"integer","description":"نقروا على الدعوة"}}},"Metrics":{"type":"object","required":["object","range","summary","previous"],"properties":{"object":{"const":"metrics"},"range":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"summary":{"$ref":"#/components/schemas/MetricSet"},"previous":{"$ref":"#/components/schemas/MetricSet","description":"الفترة السابقة بالطول نفسه"},"groups":{"type":"array","items":{"type":"object","required":["key","name","count","csat"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"count":{"type":"integer"},"csat":{"type":["number","null"]},"satisfied":{"type":["number","null"]},"nps":{"type":["integer","null"]},"critical":{"type":"integer"},"delta":{"type":["number","null"]}}}}}},"WebhookEndpoint":{"type":"object","required":["object","id","name","url","events","filters","include_pii","header_names","is_active","retry_every_minutes","give_up_after_minutes","notify_on_failure","notify_emails","disable_after_failures","disabled_reason","created_at"],"properties":{"object":{"const":"webhook_endpoint"},"id":{"type":"string","pattern":"^whk_[0-9a-z]{26}$","examples":["whk_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"enum":["response.completed","response.flagged","case.assigned","case.status_changed","case.resolved","case.escalated"]}},"filters":{"type":"object","properties":{"surveys":{"type":"array","items":{"type":"string"}},"unit":{"type":"string"},"min_priority":{"enum":["high","critical"]}}},"include_pii":{"type":"boolean"},"header_names":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"retry_every_minutes":{"type":"integer"},"give_up_after_minutes":{"type":"integer","description":"0 = بلا إعادة محاولة"},"notify_on_failure":{"type":"boolean"},"notify_emails":{"type":"array","items":{"type":"string"}},"disable_after_failures":{"type":["integer","null"]},"disabled_reason":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"secret":{"type":"string","description":"في رد الإنشاء فقط"}}},"WebhookEndpointInput":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"enum":["response.completed","response.flagged","case.assigned","case.status_changed","case.resolved","case.escalated"]}},"filters":{"type":"object"},"include_pii":{"type":"boolean"},"headers":{"type":"array","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"value":{"type":["string","null"]}}}},"retry_every_minutes":{"type":"integer","minimum":1,"maximum":1440,"default":5},"give_up_after_minutes":{"type":"integer","minimum":0,"maximum":10080,"default":1440},"notify_on_failure":{"type":"boolean"},"notify_emails":{"type":"array","items":{"type":"string","format":"email"}},"disable_after_failures":{"type":["integer","null"]},"is_active":{"type":"boolean"}}},"WebhookDelivery":{"type":"object","required":["object","id","endpoint","event","event_id","status","attempts","last_status_code","last_error","next_attempt_at","created_at"],"additionalProperties":false,"properties":{"object":{"const":"webhook_delivery"},"id":{"type":"string","pattern":"^whd_[0-9a-z]{26}$","examples":["whd_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"endpoint":{"type":"string","pattern":"^whk_[0-9a-z]{26}$","examples":["whk_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"event":{"type":"string"},"event_id":{"type":"string"},"status":{"enum":["pending","sending","retrying","succeeded","failed"]},"attempts":{"type":"integer"},"last_status_code":{"type":["integer","null"]},"last_error":{"type":["string","null"]},"next_attempt_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"EventInput":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"type":"string","pattern":"^[a-z0-9][a-z0-9_.]{0,63}$","description":"نوع الحدث؛ تعمل المشغّلات المرتبطة بهذا النوع في اللوحة (مثل order_delivered)"},"occurred_at":{"type":"string","format":"date-time","description":"وقت الحدث؛ يُضاف إليه التأخير. وإن لم يُحدد فالوقت الحالي."},"contact":{"type":"object","additionalProperties":false,"properties":{"external_id":{"type":"string","description":"رقم العميل لديكم (موصى به)"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string","description":"+90 5xx... أو 05xx..."},"locale":{"enum":["tr","en","ar","ru","de"]}}},"org_unit":{"type":"string"},"person":{"type":"string"},"touchpoint":{"type":"string"},"transaction_ref":{"type":"string","maxLength":128},"context":{"type":"object","additionalProperties":{"type":["string","number","boolean"]}}}},"Event":{"type":"object","required":["object","id","type","occurred_at","matched_triggers","scheduled","skipped","livemode","created_at"],"additionalProperties":false,"properties":{"object":{"const":"event"},"id":{"type":"string","pattern":"^evt_[0-9a-z]{26}$","examples":["evt_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"type":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"matched_triggers":{"type":"integer"},"scheduled":{"type":"array","items":{"type":"object","required":["trigger","survey","invitation","message","channel","send_at"],"properties":{"trigger":{"type":"string","pattern":"^trg_[0-9a-z]{26}$","examples":["trg_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"survey":{"type":"string","pattern":"^srv_[0-9a-z]{26}$","examples":["srv_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"invitation":{"type":"string","pattern":"^inv_[0-9a-z]{26}$","examples":["inv_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"message":{"type":"string","pattern":"^msg_[0-9a-z]{26}$","examples":["msg_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"channel":{"enum":["email","sms"]},"send_at":{"type":"string","format":"date-time"}}}},"skipped":{"type":"array","items":{"type":"object","required":["trigger","reason","detail"],"properties":{"trigger":{"type":"string","pattern":"^trg_[0-9a-z]{26}$","examples":["trg_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"detail":{"type":"string"},"reason":{"type":"string","description":"survey_not_live, opted_out, frequency_trigger, frequency_global, no_recipient, privacy_notice_not_covering, unknown_context_field, validation_failed"}}}},"livemode":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"EventBatchResult":{"type":"object","required":["object","created","failed","results"],"properties":{"object":{"const":"batch_result"},"created":{"type":"integer"},"failed":{"type":"integer"},"results":{"type":"array","items":{"type":"object","required":["index","ok"],"properties":{"index":{"type":"integer"},"ok":{"type":"boolean"},"event":{"$ref":"#/components/schemas/Event"},"error":{"type":"object"}}}}}},"Contact":{"type":"object","required":["object","id","external_id","name","email","phone","locale","opted_out","created_at"],"additionalProperties":false,"properties":{"object":{"const":"contact"},"id":{"type":"string","pattern":"^con_[0-9a-z]{26}$","examples":["con_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"external_id":{"type":["string","null"]},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"locale":{"type":["string","null"]},"opted_out":{"type":"boolean","description":"لا يرغب في تلقي رسائل الاستبيان"},"created_at":{"type":"string","format":"date-time"}}},"ContactInput":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"locale":{"enum":["tr","en","ar","ru","de"]},"opted_out":{"type":"boolean","description":"true: لا تُرسل رسائل استبيان إلى هذا الشخص"}}},"ContactExport":{"type":"object","required":["object","contact","invitations","messages","responses","exported_at"],"properties":{"object":{"const":"contact_export"},"contact":{"$ref":"#/components/schemas/Contact"},"invitations":{"type":"array"},"messages":{"type":"array"},"responses":{"type":"array","items":{"type":"object"}},"exported_at":{"type":"string","format":"date-time"}}},"ContactErasure":{"type":"object","required":["object","erased","responses_anonymized"],"properties":{"object":{"const":"contact_erasure"},"erased":{"const":true},"responses_anonymized":{"type":"integer"}}},"SurveyList":{"type":"object","required":["object","data","has_more","next_cursor"],"additionalProperties":false,"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Survey"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"InvitationList":{"type":"object","required":["object","data","has_more","next_cursor"],"additionalProperties":false,"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Invitation"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"ResponseList":{"type":"object","required":["object","data","has_more","next_cursor"],"additionalProperties":false,"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Response"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"OrgUnitList":{"type":"object","required":["object","data","has_more","next_cursor"],"additionalProperties":false,"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/OrgUnit"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"TouchpointList":{"type":"object","required":["object","data","has_more","next_cursor"],"additionalProperties":false,"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Touchpoint"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"WebhookEndpointList":{"type":"object","required":["object","data","has_more","next_cursor"],"additionalProperties":false,"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"WebhookDeliveryList":{"type":"object","required":["object","data","has_more","next_cursor"],"additionalProperties":false,"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}}}}}