المطوّرون

مكتبك كله،
على واجهة API واحدة.

كل اللي يديره مكتبك على شركتي — الخدمات والطلبات والباقات والعملاء والفوترة — توصله من واجهة REST واحدة. اربط الـ ERP، وزامن الـ CRM، وشغّل تطبيق عميل بعلامتك عبر خادمك، أو أنشئ الطلبات مباشرة من أنظمتك. نفس المحرّك، ونفس سجل التدقيق… وكودك أنت.

ابدأ البناء مرجع الواجهة

البروتوكول: REST + JSON عبر /api/v1
المفاتيح: مفاتيح محدودة الصلاحيات وقابلة للتقييد بعناوين IP
إعادة المحاولة: إعادة محاولات آمنة دون تكرار

المحرّك نفسه الذي يستخدمه سطح المكتب

مُدقّق ككل إجراء آخر

أول طلب لك

curl https://api.shrkity.com/api/v1/orders \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-7f3a" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Require-Subject: 1" \
  -d '{
    "service_definition_id": 18
  }'

# 201 · X-Shirkty-Mode: subject
{
  "mode": "subject",
  "data": {
    "request": { "id": 1208, "status": "pending" },
    "steps": [ … ]
  }
}

طلب عميل حقيقي عبر المحرّك نفسه الذي يستخدمه تطبيق سطح المكتب، بخطواته وعدّادات SLA وسجل التدقيق.

الدليل

من مفتاح API إلى أول طلب في دقائق.

الوصول عبر API جزء من باقتَي التوسّع والمؤسسات. يُنشئ مالك المنشأة مفاتيح API من تطبيق سطح المكتب، بصلاحيات محددة لما يحتاجه تكاملك بالضبط، ويظهر المفتاح مرة واحدة فقط. ودليل BFF الأعمق منشور أيضًا كنص Markdown عبر https://api.shrkity.com/api/v1/docs/integrator.md (بلا مصادقة).

أنشئ مفتاحًا

في تطبيق شركتي للأعمال افتح الإعدادات · المنشأة · الوصول عبر API وأنشئ مفتاحًا. اختر صلاحياته (قالب BFF أو قالب العمليات)، وقيّده بعناوين IP لخوادمك عندما يحمل صلاحيات التنفيذ، وانسخ السر — يظهر مرة واحدة فقط.

صادِق طلباتك

أرسل المفتاح مع كل طلب في الترويسة Authorization: Bearer shk_live_… أو في X-Api-Key. من خادم إلى خادم فقط — لا من متصفح أو تطبيق جوال أبدًا.

نفّذ أول استدعاء

اعرض الخدمات المنشورة عبر GET /services (ترويسات الموضوع تفرّق كتالوج الأفراد عن الشركات) ثم أنشئ طلبًا. كل استجابة تطابق ما يراه فريقك على سطح المكتب.

انطلق بأمان

أرسل Idempotency-Key مع عمليات الكتابة، وفضّل X-Shirkty-Require-Subject: 1 عند إنشاء طلب العميل، وتحقق من X-Shirkty-Mode: subject في الاختبارات، وبدّل المفاتيح بإنشاء مفتاح جديد وإلغاء القديم.

الرابط الأساسي https://api.shrkity.com/api/v1 رابطك الأساسي الدقيق يظهر في تبويب الوصول عبر API.

إنشاء طلب: عمليات مقابل موضوع

POST /orders وضع مزدوج. نفس المسار يخدم أتمتة الموظفين وخلفيات تطبيقات العملاء ذات العلامة — والفرق هو ترويسات الموضوع. الاستجابات الناجحة تضع X-Shirkty-Mode: subject|operator. وإنشاء العمليات يرسل أيضًا X-Shirkty-Mode-Warning حتى تفشل اختبارات واجهة BFF إن نُسيت ترويسة العميل.

عمليات (بلا ترويسات موضوع)

يُنشأ الطلب كحساب الجهاز لمساحة العمل. اختياريًا عيّن created_by_user_id / client_user_id لتثبيت مالك العميل، وcompany_id عندما تحتاج الخدمة منشأة. شكل الاستجابة يبقى شكل العمليات الكلاسيكي.

موضوع / BFF

أرسل X-Shirkty-Client-User-Id (مطلوب) وX-Shirkty-Company-Id اختياريًا. يُنشأ الطلب باسم ذلك العميل. يجب أن تطابق معرّفات الجسم الترويسات وإلا تحصل على subject_mismatch. تُعاد فحص العضوية تحت منشأتك.

سكة أمان للعلامة البيضاء: أرسل X-Shirkty-Require-Subject: 1 (أو ?require_subject=1) مع POST /orders حتى يعيد غياب ترويسة العميل 422 subject_required بدل إنشاء عمليات صامت.

رحلة العميل بعد الإنشاء (بدء خطوة، إكمال نموذج، رفع مستند، دفع/توقيع دون اتصال) تحتاج orders:execute وattachments:write وغالباً attachments:read — انظر واجهة BFF للمزوّد.

كتالوج الخدمات: أفراد مقابل شركة

في وضع الموضوع، GET /services يطابق تطبيق شركتي للعملاء: الظهور يُحكَم بـ requires_company لا بـ applies_to في سير العمل.

شخصي (ترويسة العميل فقط)

يعرض الخدمات ذات requires_company = false. إنشاء الطلب لا يرسل شركة.

شركة (+ ترويسة الشركة)

يعرض الخدمات ذات requires_company = true. لطلبات الشركة / الموظف؛ وrequires_employee يحتاج أيضًا company_employee_id.

applies_to (company · employee · individual) تُعاد لشارات الواجهة فقط. وضع العمليات (بلا موضوع) يعيد القائمة المنشورة كاملة ويقبل اختياريًا ?requires_company= / ?audience=. كل صف يتضمن order_context: { personal_ok, company_ok, employee_ok }.

المصادقة

مفتاح API بيانات اعتماد،
لا كلمة مرور تُعاد استخدامها.

يعمل مفتاح API باسم منشأتك كاملة ضمن الصلاحيات التي تمنحها له. شركتي تخزّن بصمته فقط — إن فُقد فألغِه وأنشئ غيره.

صلاحيات بحسب المورد. orders:write ينشئ الطلبات ولا يلمس الكوبونات. لا يوجد invoices:write — الفواتير تصدرها المنظومة؛ استخدم invoices:read وملف PDF. امنح ما يحتاجه التكامل فقط.

قائمة IP إلزامية للتنفيذ. المفاتيح التي تتضمن orders:execute أو attachments:write أو documents:write يجب تقييدها بعناوين خوادم أو نطاقات CIDR عند الإنشاء/التحديث (422 بدونه). ويُنصح به بقوة على كل مفتاح إنتاج.

مرتبط بالباقة وقابل للإلغاء فورًا. يُتحقق من الوصول مع كل طلب (بما في ذلك غياب الاشتراك → plan_required)، والمفتاح الملغى يتوقف خلال دقيقة في كل مكان.

المصادقة

# bearer token (recommended)
curl https://api.shrkity.com/api/v1/services \
  -H "Authorization: Bearer shk_live_…"

# or the X-Api-Key header
curl https://api.shrkity.com/api/v1/services \
  -H "X-Api-Key: shk_live_…"

يبدأ المفتاح بـ shk_live_ يليه 40 حرفًا. أي شكل آخر يُرفض قبل أن يلمس بياناتك.

الأخطاء

كل خطأ يأتي بصيغة JSON مع رسالة مفهومة، وعند الحاجة رمز آلي تتفرّع عليه برمجيتك. إخفاقات المصادقة والتفويض تسمّي سببها دائمًا.

invalid_api_key

401

المفتاح غير معروف أو غير صالح أو ملغى (revoked_api_key) أو منتهٍ (expired_api_key).

plan_required

403

باقة المنشأة الحالية لا تتضمن الوصول عبر API (أو الاشتراك مفقود).

ip_not_allowed

403

المفتاح مقيّد بعناوين مصدر محددة وجاء هذا الاستدعاء من غيرها.

insufficient_scope

403

المفتاح يفتقد الصلاحية المطلوبة؛ تسمّيها الاستجابة في required_scope.

subject_forbidden

403

ترويسات الموضوع تسمّي عميلًا ليس عضوًا في هذه المنشأة (لا يوجد access context مطابق).

company_not_verified

409

الشركة في حالة انتظار التحقق أو مرفوضة ولا تصلح لعمليات الكتابة.

subject_required · subject_mismatch · subject_invalid

422

مسارات BFF تحتاج X-Shirkty-Client-User-Id، أو اختلف حقل في الجسم عن ترويسات الموضوع، أو لم يكن معرّف الموضوع عددًا صحيحًا موجبًا.

payment_method_not_supported

422

استُدعي دفع خطوة الطلب دون اتصال بمحفظة إلكترونية (دفع اشتراك الباقات يدعم المحافظ الإلكترونية على مسار منفصل).

422

تحقق

جسم الطلب لم يجتز التحقق؛ تخبرك الرسالة بما يجب إصلاحه بالضبط.

429

حد المعدّل

طلبات كثيرة جدًا؛ انتظر عدد الثواني في Retry-After.

شكل الخطأ

{
  "message": "The API key does not have the required scope.",
  "code": "insufficient_scope",
  "required_scope": "orders:write"
}

تقسيم الصفحات

كل قائمة تقبل page (الافتراضي 1) وper_page (الافتراضي 10 وبحد أقصى 200) وتعيد كائن meta إلى جانب البيانات. تابع الصفحات حتى تصبح has_next خاطئة.

GET /orders?page=2&per_page=50

{
  "data": [ … ],
  "meta": {
    "total": 412,
    "per_page": 50,
    "current_page": 2,
    "last_page": 9,
    "has_next": true,
    "has_previous": true
  }
}

أمان إعادة المحاولة

الشبكات تنقطع في منتصف الطلب. أرسل ترويسة Idempotency-Key مع أي POST فتُحفظ أول استجابة ناجحة لمدة 24 ساعة؛ وإعادة المحاولة المطابقة تستلم الاستجابة المحفوظة نفسها — معلَّمة بـ Idempotency-Replayed: true — بدل إنشاء نسخة مكررة. لاستدعاءات موضوع BFF يدخل مفتاح التخزين أيضًا ترويسات الموضوع حتى لا يعيد مفتاح واحد يخدم عملاء كُثر تشغيل استجابة عميل آخر.

استخدم قيمة ثابتة لكل إجراء منطقي، مثل مرجع الطلب في نظامك. إجراء جديد يعني مفتاحًا جديدًا.

إنشاء آمن لإعادة المحاولة

curl https://api.shrkity.com/api/v1/orders \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Idempotency-Key: erp-po-10422" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Require-Subject: 1" \
  -d '{ "service_definition_id": 18 }'

# run it twice — one order exists.

حدود المعدّل

لكل مفتاح 180 طلبًا في الدقيقة. كل استجابة تحمل رصيدك المتبقي، واستجابة 429 تخبرك كم تنتظر بالضبط. إنشاء الطلبات يخضع إضافيًا لحصة الطلبات الشهرية في باقتك. وتتوفر ملخصات استخدام يومية في درج الوصول عبر API على سطح المكتب.

ترويسات الاستجابة

X-RateLimit-Limit: 180
X-RateLimit-Remaining: 177
# on 429 only:
Retry-After: 21

الإصدارات

العقد هو الرابط. الاستجابات تحت /api/v1 لا تتغير إلا بالإضافة؛ لا يُعاد تسمية حقل ولا يُحذف ضمن v1. التغيير الكاسر يعني /api/v2 موازيًا مع فترة إيقاف تدريجي، لا تعديلًا صامتًا. ابنِ على الحقول التي تستخدمها وتجاهل الباقي. وثيقة OpenAPI حاليًا 1.1.1 (واجهة BFF للمزوّد، سكك الوضع المزدوج، دفع الباقات، فصل صلاحيات المرفقات، النظرة العامة ومهام العميل الغنية).

واجهة BFF للمزوّد

ابنِ تطبيق عميل بعلامتك على خادمك.

واجهات الويب والجوال التي تملكها يجب ألا تحتفظ بمفتاح API. خادمك يصادق بالمفتاح، ويربط المستخدم المسجّل بعميل في شركتي، ويستدعي /api/v1 بترويسات الموضوع. شركتي تعيد التحقق من العضوية والملكية تحت منشأتك.

وضع العمليات (Ops)

مفتاح API فقط — قوائم على مستوى المنشأة وأتمتة الموظفين (ERP، CRM، المالية). بلا ترويسات موضوع. استخدم مفتاحًا بلا orders:execute / attachments:* / documents:write إن احتجت العمليات فقط. يوفّر سطح المكتب قالب عمليات لهذا الغرض.

وضع الموضوع (BFF)

أرسل X-Shirkty-Client-User-Id (مطلوب) وX-Shirkty-Company-Id اختياريًا. تُقيَّد القوائم بذلك العميل؛ تنفيذ الخطوات والمرفقات وقبول عروض الأسعار والنظرة العامة وclient-tasks ودفع اشتراك الباقات تتطلب الموضوع دائمًا.

صلاحيات BFF الموصى بها

services:read · packages:read · subscriptions:read · subscriptions:write · orders:read · orders:write · orders:execute · clients:read · companies:read · documents:read · documents:write · attachments:read · attachments:write · invoices:read · quotations:read · quotations:write

GET /tenant/api-keys/scopes (جلسة سطح المكتب) يعيد كتالوج الصلاحيات وbff_recommended_scopes. قائمة IP إلزامية عندما يتضمن المفتاح صلاحيات التنفيذ / كتابة المرفقات / كتابة المستندات.

مسارات الموضوع دائمًا (غياب الترويسة → 422 subject_required): /client-tasks، /overview، تنفيذ/توقيع/دفع الخطوات، /attachments*، قبول/رفض عروض الأسعار، دفع/معاينة كوبون اشتراك الباقات.

الصفحة الرئيسية وصندوق الوارد. GET /overview يعيد عدّادات الصفحة الرئيسية (طلبات نشطة، مهام قابلة للتنفيذ، مستندات قاربت الانتهاء). GET /client-tasks يعيد بطاقات صندوق وارد مُقسَّمة (اسم الخدمة، مرجع الطلب، تسميات الخطوة، SLA، links إلى الطلب/الخطوة) مع فلاتر: status، step_type، service_definition_id، subject_kind. حمّل إعداد النموذج/الدفع/التوقيع الكامل عبر GET …/steps/{key}.

المرفقات. POST /attachments يحتاج attachments:write؛ وGET /attachments/{id}/download يحتاج attachments:read (أو الكتابة القديمة). ملفات التجهيز خاصة في تخزين كائنات مع تسليم موقّع قصير العمر — لا مسارات قرص عامة.

الويب هوكس ترسل طلبات POST موقّعة (منها step.client_action_required) ليدفع خادمك «إجراء مطلوب» دون استطلاع مستمر. دفع خطوة الطلب يقبل المحافظ دون اتصال فقط؛ أما دفع اشتراك الباقات فيدعم إثباتًا دون اتصال و روابط دفع مستضافة إلكترونيًا.

المستخدم النهائي لا يصادق على شركتي بمفتاح API. جلستك وعلامتك؛ شركتي هي مصدر الحقيقة للعمل.

استدعاء بموضوع

curl https://api.shrkity.com/api/v1/client-tasks \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42"

# X-Shirkty-Mode: subject

النظرة العامة

curl https://api.shrkity.com/api/v1/overview \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001"

قائمة تحقق الوضع المزدوج (علامة بيضاء)

افصل مفاتيح العمليات عن BFF (BFF يحمل التنفيذ + المرفقات؛ قائمة IP إلزامية).
لا تضع المفتاح في تطبيق الجوال — خادمك فقط.
كل استدعاء موجّه للعميل: Authorization + X-Shirkty-Client-User-Id (+ الشركة عند الحاجة).
إنشاء طلب العميل: ترويسات الموضوع ومعها تفضيل X-Shirkty-Require-Subject: 1.
تحقق من X-Shirkty-Mode: subject في اختبارات التكامل لمسارات العميل.
اربط مستخدم الجوال بمعرّف عميل شركتي فقط بعد صلاحية العضوية (access_contexts).

خدمة ذاتية للعميل

الباقات والاشتراكات على واجهة BFF.

بترويسات الموضوع وصلاحيات packages:read + subscriptions:read + subscriptions:write يستطيع تطبيقك ذو العلامة تصفّح الباقات وإتمام الدفع دون سطح المكتب. بلا ترويسات موضوع تبقى نفس المسارات بسلوك العمليات/الموظفين (الكتالوج الكامل، التعيين، الإيقاف، الاستئناف، التجديد).

GET /packages

تصفّح

الموضوع → كتالوج العميل لهذه المنشأة. تفاصيل الباقة عبر GET /packages/{id}.

GET /subscriptions

اشتراكاتي

الموضوع → قائمة/عرض اشتراكات صاحب الحساب فقط.

POST /subscriptions

بدء

الجسم { package_id, linked_company_id? }. الباقات المجانية تُفعَّل؛ والمدفوعة تعيد needs_payment مع المحافظ.

POST /subscriptions/preview-coupon

كوبون

موضوع دائمًا. معاينة الرمز قبل الدفع.

POST /subscriptions/checkout

دفع

موضوع دائمًا. إنشاء الاشتراك + الدفع في خطوة واحدة: إثبات دون اتصال أو محفظة إلكترونية قابلة للشحن wallet_id (رابط payment_url مستضاف لـ WebView).

…/payment-options · …/pay · …/payment/cancel

معلّق

موضوع دائمًا. متابعة الدفع لاشتراك معلّق/فترة سماح؛ الإلكتروني يعيد رابطًا مستضافًا؛ والإلغاء يتيح البدء من جديد.

…/apply-coupon · …/remove-coupon · …/link-company · …/cancel

إدارة

تعديل الكوبون على دفع معلّق، وربط الشركة، والإلغاء بنهاية الفترة — ضمن نطاق الموضوع.

مدفوع · إلكتروني

معاينة الكوبون → الدفع بمحفظة إلكترونية قابلة للشحن → افتح payment_url في WebView → ويب هوك البوابة يفعّل الاشتراك.

مدفوع · دون اتصال

الدفع بمحفظة دون اتصال + مرفق إثبات → يتحقق الموظفون على سطح المكتب → نشط. دفع خطوة الطلب يبقى دون اتصال فقط؛ دفع اشتراك الباقات هو السطح الذي يدعم القناتين.

الدفع (مثال)

curl https://api.shrkity.com/api/v1/subscriptions/checkout \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "Idempotency-Key: sub-checkout-9c2e" \
  -d '{
    "package_id": 12,
    "wallet_id": 3
  }'

المرجع

كل نقطة وصول، بحسب المورد.

يُولَّد هذا المرجع من وثيقة OpenAPI نفسها التي تقدّمها المنصة عبر /api/v1/openapi.json (حاليًا 1.1.1) — فما تقرؤه هنا هو ما يفرضه الخادم. ودليل BFF الطويل أيضًا عبر /api/v1/docs/integrator.md. وتبقى المسارات وأسماء الحقول والأنواع بالإنجليزية كما يفرضها العقد.

الخدمات

كتالوج الخدمات المنشورة (للقراءة فقط).

3 نقاط وصول

GET /services عرض الخدمات المنشورة

عرض الخدمات المنشورة

الصلاحية: services:read

المعاملات

search

query · string

يطابق الاسم أو الاسم العربي أو الرمز

200 · قائمة مقسّمة لصفحات

مثال على الطلب

curl https://api.shrkity.com/api/v1/services \
  -H "Authorization: Bearer shk_live_…"

GET /services/{id} عرض خدمة منشورة مع متطلبات الطلب

حقول القائمة إضافةً إلى starts_at_price (هل يعتمد السعر على خيارات تُحدَّد وقت التنفيذ) وفحوصات الأهلية التي ستحكم إنشاء طلب لهذه الخدمة.

الصلاحية: services:read

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)404 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/services/{id} \
  -H "Authorization: Bearer shk_live_…"

GET /services/{id}/required-documents عرض المستندات التي سيطلبها سير عمل الخدمة

مجمّعة عبر خطوات المستندات في سير العمل، وفق ترتيب التنفيذ. استخدمها لتجميع الملفات من جانبك قبل تنفيذ الطلب أو أثناءه.

الصلاحية: services:read

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)404 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/services/{id}/required-documents \
  -H "Authorization: Bearer shk_live_…"

الطلبات

طلبات الخدمة.

16 نقاط وصول

GET /orders عرض الطلبات

عرض الطلبات

الصلاحية: orders:read

المعاملات

status

query · string

company_id

query · integer

service_definition_id

query · integer

priority

query · string

search

query · string

created_from

query · string

created_to

query · string

200 · قائمة مقسّمة لصفحات

مثال على الطلب

curl https://api.shrkity.com/api/v1/orders \
  -H "Authorization: Bearer shk_live_…"

POST /orders إنشاء طلب

ينشئ طلب خدمة لخدمة منشورة. يخضع للحد الشهري للطلبات في الباقة (يُعاد 422 عند بلوغه). يدعم Idempotency-Key.

الصلاحية: orders:write

حقول الطلب

service_definition_id

integer · مطلوب

خدمة منشورة (راجع GET /services)

client_user_id

integer

بديل لـ created_by_user_id؛ يجب أن يطابق X-Shirkty-Client-User-Id عند وجود ترويسة الموضوع

created_by_user_id

integer

مسار العمليات: تثبيت منشئ الطلب؛ مسار الموضوع يجب أن يطابق الترويسة أو يُحذف

company_id

integer

مطلوب عندما تتطلب الخدمة سياق منشأة؛ ويجب أن يطابق X-Shirkty-Company-Id عند تعيين كليهما

company_employee_id

integer

الموظف المقصود بالطلب، عندما تتطلب الخدمة موظفًا

priority

string · low | normal | high | urgent

201 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)422 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/orders \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "service_definition_id": 42,
    "client_user_id": 42,
    "created_by_user_id": 42,
    "company_id": 42,
    "company_employee_id": 42
  }'

GET /orders/{id} عرض طلب مع خطواته وتفصيل سعره

عرض طلب مع خطواته وتفصيل سعره

الصلاحية: orders:read

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)404 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/orders/{id} \
  -H "Authorization: Bearer shk_live_…"

PATCH /orders/{id} تعديل طلب

تعديل طلب

الصلاحية: orders:write

المعاملات

id

path · integer · مطلوب

حقول الطلب

priority

string · low | normal | high | urgent

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/orders/{id} \
  -X PATCH \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "priority": "low"
  }'

GET /orders/{id}/steps/{step_key} عرض خطوة واحدة من الطلب

عرض خطوة واحدة من الطلب

الصلاحية: orders:read

المعاملات

id

path · integer · مطلوب

step_key

path · string · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/orders/{id}/steps/{step_key} \
  -H "Authorization: Bearer shk_live_…"

POST /orders/{id}/cancel إلغاء طلب

إلغاء طلب

الصلاحية: orders:write

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/orders/{id}/cancel \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

POST /orders/{id}/apply-coupon تطبيق كوبون على الطلب

تطبيق كوبون على الطلب

الصلاحية: orders:write

المعاملات

id

path · integer · مطلوب

حقول الطلب

code

string · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/orders/{id}/apply-coupon \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME10"
  }'

DELETE /orders/{id}/coupon إزالة الكوبون المطبّق من الطلب

إزالة الكوبون المطبّق من الطلب

الصلاحية: orders:write

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/orders/{id}/coupon \
  -X DELETE \
  -H "Authorization: Bearer shk_live_…"

POST /orders/{id}/steps/{step_key}/start بدء خطوة بممثل عميل (الموضوع)

الصلاحية: orders:execute. يتطلب موضوعًا دائمًا.

الصلاحية: orders:execute

المعاملات

id

path · integer · مطلوب

step_key

path · string · مطلوب

X-Shirkty-Client-User-Id

header · integer · مطلوب

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

سياق منشأة اختياري للموضوع

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/orders/{id}/steps/{step_key}/start \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42"

POST /orders/{id}/steps/{step_key}/complete إكمال خطوة form_input باسم الموضوع

الصلاحية: orders:execute.

الصلاحية: orders:execute

المعاملات

id

path · integer · مطلوب

step_key

path · string · مطلوب

X-Shirkty-Client-User-Id

header · integer · مطلوب

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

سياق منشأة اختياري للموضوع

حقول الطلب

response_data

object

notes

string

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/orders/{id}/steps/{step_key}/complete \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "response_data": "…",
    "notes": "…"
  }'

POST /orders/{id}/steps/{step_key}/complete-manual إكمال خطوة manual_task باسم الموضوع

إكمال خطوة manual_task باسم الموضوع

الصلاحية: orders:write

المعاملات

id

path · integer · مطلوب

step_key

path · string · مطلوب

X-Shirkty-Client-User-Id

header · integer · مطلوب

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

سياق منشأة اختياري للموضوع

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/orders/{id}/steps/{step_key}/complete-manual \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42"

POST /orders/{id}/steps/{step_key}/complete-document إكمال خطوة document_request بمرفقات مرحلية

الصلاحية: orders:execute. ارفع الملفات عبر POST /attachments أولًا.

الصلاحية: orders:execute

المعاملات

id

path · integer · مطلوب

step_key

path · string · مطلوب

X-Shirkty-Client-User-Id

header · integer · مطلوب

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

سياق منشأة اختياري للموضوع

حقول الطلب

document_records

array · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/orders/{id}/steps/{step_key}/complete-document \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "document_records": []
  }'

GET /orders/{id}/steps/{step_key}/signature/document تنزيل مستند التوقيع دون اتصال المصدر

تنزيل مستند التوقيع دون اتصال المصدر

الصلاحية: orders:read

المعاملات

id

path · integer · مطلوب

step_key

path · string · مطلوب

X-Shirkty-Client-User-Id

header · integer · مطلوب

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

سياق منشأة اختياري للموضوع

200 · بث ملف

مثال على الطلب

curl https://api.shrkity.com/api/v1/orders/{id}/steps/{step_key}/signature/document \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42"

POST /orders/{id}/steps/{step_key}/signature/sign تسجيل توقيع دون اتصال بـ attachment_id مرحلي

الصلاحية: orders:execute. قناة دون اتصال فقط.

الصلاحية: orders:execute

المعاملات

id

path · integer · مطلوب

step_key

path · string · مطلوب

X-Shirkty-Client-User-Id

header · integer · مطلوب

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

سياق منشأة اختياري للموضوع

حقول الطلب

attachment_id

integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/orders/{id}/steps/{step_key}/signature/sign \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "attachment_id": 42
  }'

GET /orders/{id}/steps/{step_key}/payment-options عرض محافظ الدفع دون اتصال والمبلغ المستحق لخطوة الدفع

الصلاحية: orders:read. لا تُدرج المحافظ الإلكترونية (BFF دون اتصال فقط).

الصلاحية: orders:read

المعاملات

id

path · integer · مطلوب

step_key

path · string · مطلوب

X-Shirkty-Client-User-Id

header · integer · مطلوب

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

سياق منشأة اختياري للموضوع

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/orders/{id}/steps/{step_key}/payment-options \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42"

POST /orders/{id}/steps/{step_key}/pay تقديم دفع دون اتصال لخطوة دفع

الصلاحية: orders:execute. محافظ دون اتصال فقط؛ الإلكتروني → payment_method_not_supported.

الصلاحية: orders:execute

المعاملات

id

path · integer · مطلوب

step_key

path · string · مطلوب

X-Shirkty-Client-User-Id

header · integer · مطلوب

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

سياق منشأة اختياري للموضوع

حقول الطلب

wallet_id

integer · مطلوب

proof_attachment_id

integer

proof_reference

string

proof_notes

string

201 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)422 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/orders/{id}/steps/{step_key}/pay \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_id": 42,
    "proof_attachment_id": 42,
    "proof_reference": "…",
    "proof_notes": "…"
  }'

مهام العميل

صندوق وارد للخطوات التي تتطلب إجراءً من عميل موضوع BFF.

2 نقاط وصول

GET /client-tasks عرض الخطوات التي تتطلب إجراءً من العميل (الموضوع)

الصلاحية: orders:read

المعاملات

X-Shirkty-Client-User-Id

header · integer · مطلوب

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

سياق منشأة اختياري للموضوع

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)422 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/client-tasks \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42"

GET /overview Subject home overview (BFF)

Always requires X-Shirkty-Client-User-Id. Scope: orders:read. Returns paginated inbox cards (service name, order reference, step definition labels, SLA, links) with filters status, step_type, service_definition_id, subject_kind. Returns counts (active_orders, actionable_tasks, expiring_documents) and recent_orders for the subject under this tenant.

الصلاحية: orders:read

المعاملات

X-Shirkty-Client-User-Id

header · integer · مطلوب

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

سياق منشأة اختياري للموضوع

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)422 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/overview \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42"

المرفقات

Staged file upload/download for BFF subjects. POST requires attachments:write; GET download requires attachments:read (or legacy attachments:write). Always requires subject headers. Invoices are read-only (invoices:read).

2 نقاط وصول

POST /attachments رفع ملف مرحلي باسم الموضوع (multipart)

Scope: attachments:write. Supports Idempotency-Key. Use returned attachment_id for document/payment/signature steps. Download uses attachments:read.

الصلاحية: attachments:write

المعاملات

X-Shirkty-Client-User-Id

header · integer · مطلوب

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

سياق منشأة اختياري للموضوع

201 · مرفق مرحلي

مثال على الطلب

curl https://api.shrkity.com/api/v1/attachments \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42" \
  -F "file=@/path/to/document.pdf"

GET /attachments/{id}/download بث مرفق مرحلي رفعه الموضوع

Scope: attachments:read (preferred) or attachments:write (legacy). Always subject.

الصلاحية: attachments:read

المعاملات

id

path · integer · مطلوب

X-Shirkty-Client-User-Id

header · integer · مطلوب

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

سياق منشأة اختياري للموضوع

200 · بث ملف403 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/attachments/{id}/download \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42"

العملاء

عملاء المنشأة.

3 نقاط وصول

GET /clients عرض العملاء

عرض العملاء

الصلاحية: clients:read

200 · قائمة مقسّمة لصفحات

مثال على الطلب

curl https://api.shrkity.com/api/v1/clients \
  -H "Authorization: Bearer shk_live_…"

POST /clients إنشاء عميل

إنشاء عميل

الصلاحية: clients:write

حقول الطلب

name

string · مطلوب

email

string · مطلوب

phone_number

string

201 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)422 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/clients \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Trading Co.",
    "email": "[email protected]",
    "phone_number": "…"
  }'

GET /clients/{client_id} عرض عميل واحد إن وُجد له access_context تحت هذه المنشأة

عرض عميل واحد إن وُجد له access_context تحت هذه المنشأة

الصلاحية: clients:read

المعاملات

client_id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)404 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/clients/{client_id} \
  -H "Authorization: Bearer shk_live_…"

الشركات

منشآت العملاء وموظفوها.

7 نقاط وصول

GET /companies عرض المنشآت

عرض المنشآت

الصلاحية: companies:read

200 · قائمة مقسّمة لصفحات

مثال على الطلب

curl https://api.shrkity.com/api/v1/companies \
  -H "Authorization: Bearer shk_live_…"

POST /companies إنشاء منشأة

إنشاء منشأة

الصلاحية: companies:write

حقول الطلب

حمولة المنشأة — legal_name وtype وحقول السجل؛ راجع نموذج «إضافة منشأة» في البوابة لمعرفة مجموعة الحقول.

201 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)422 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/companies \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ …see field reference… }'

PUT /companies/{id} تعديل منشأة

تعديل منشأة

الصلاحية: companies:write

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/companies/{id} \
  -X PUT \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ …see field reference… }'

GET /companies/{company_id}/workers عرض موظفي المنشأة

عرض موظفي المنشأة

الصلاحية: companies:read

المعاملات

company_id

path · integer · مطلوب

200 · قائمة مقسّمة لصفحات

مثال على الطلب

curl https://api.shrkity.com/api/v1/companies/{company_id}/workers \
  -H "Authorization: Bearer shk_live_…"

POST /companies/{company_id}/workers إضافة موظف إلى المنشأة

ينشئ موظف منشأة — وهو الشخص المقصود بالطلب المرتبط بموظف. مجموعة الحقول تطابق نموذج «إضافة موظف» في البوابة.

الصلاحية: companies:write

المعاملات

company_id

path · integer · مطلوب

201 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)422 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/companies/{company_id}/workers \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ …see field reference… }'

PATCH /companies/{company_id}/workers/{id} تعديل موظف

تعديل موظف

الصلاحية: companies:write

المعاملات

company_id

path · integer · مطلوب

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/companies/{company_id}/workers/{id} \
  -X PATCH \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ …see field reference… }'

DELETE /companies/{company_id}/workers/{id} إزالة موظف

إزالة موظف

الصلاحية: companies:write

المعاملات

company_id

path · integer · مطلوب

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/companies/{company_id}/workers/{id} \
  -X DELETE \
  -H "Authorization: Bearer shk_live_…"

الباقات

الباقات التي تنشئها المنشأة (للقراءة فقط).

2 نقاط وصول

GET /packages عرض الباقات

عرض الباقات

الصلاحية: packages:read

200 · قائمة مقسّمة لصفحات

مثال على الطلب

curl https://api.shrkity.com/api/v1/packages \
  -H "Authorization: Bearer shk_live_…"

GET /packages/{id} عرض باقة

عرض باقة

الصلاحية: packages:read

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/packages/{id} \
  -H "Authorization: Bearer shk_live_…"

الاشتراكات

اشتراكات الباقات.

9 نقاط وصول

POST /subscriptions/checkout Client paid package checkout (BFF subject)

Always requires X-Shirkty-Client-User-Id. Scope: subscriptions:write. Body: package_id, wallet_id (offline or chargeable online), optional coupon_code, linked_company_id, proof_*. Online wallets return payment_url.

الصلاحية: subscriptions:write

المعاملات

X-Shirkty-Client-User-Id

header · integer · مطلوب

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

سياق منشأة اختياري للموضوع

201 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)422 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/subscriptions/checkout \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42"

POST /subscriptions/preview-coupon Preview subscription coupon (BFF subject)

Always subject. Scope: subscriptions:write.

الصلاحية: subscriptions:write

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/subscriptions/preview-coupon \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

GET /subscriptions عرض اشتراكات الباقات

عرض اشتراكات الباقات

الصلاحية: subscriptions:read

200 · قائمة مقسّمة لصفحات

مثال على الطلب

curl https://api.shrkity.com/api/v1/subscriptions \
  -H "Authorization: Bearer shk_live_…"

POST /subscriptions إسناد اشتراك باقة

إسناد اشتراك باقة

الصلاحية: subscriptions:write

حقول الطلب

package_id إضافةً إلى المالك (company_id أو مستخدم العميل)، بما يطابق مسار «الإسناد» في البوابة.

201 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/subscriptions \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ …see field reference… }'

GET /subscriptions/{id} عرض اشتراك مع مخصصاته

عرض اشتراك مع مخصصاته

الصلاحية: subscriptions:read

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/subscriptions/{id} \
  -H "Authorization: Bearer shk_live_…"

POST /subscriptions/{id}/pause إيقاف اشتراك نشط مؤقتًا

إيقاف اشتراك نشط مؤقتًا

الصلاحية: subscriptions:write

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)409 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/subscriptions/{id}/pause \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

POST /subscriptions/{id}/resume استئناف اشتراك موقوف

استئناف اشتراك موقوف

الصلاحية: subscriptions:write

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)409 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/subscriptions/{id}/resume \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

POST /subscriptions/{id}/cancel إلغاء اشتراك

إلغاء اشتراك

الصلاحية: subscriptions:write

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)409 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/subscriptions/{id}/cancel \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

POST /subscriptions/{id}/renew تجديد اشتراك منتهٍ قابل للتجديد

تجديد اشتراك منتهٍ قابل للتجديد

الصلاحية: subscriptions:write

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)409 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/subscriptions/{id}/renew \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

الكوبونات

كوبونات الخصم.

6 نقاط وصول

GET /coupons عرض الكوبونات

عرض الكوبونات

الصلاحية: coupons:read

200 · قائمة مقسّمة لصفحات

مثال على الطلب

curl https://api.shrkity.com/api/v1/coupons \
  -H "Authorization: Bearer shk_live_…"

POST /coupons إنشاء كوبون

إنشاء كوبون

الصلاحية: coupons:write

حقول الطلب

code

string · مطلوب

name

string · مطلوب

description

string

discount_type

string · fixed | percentage · مطلوب

discount_value

number · مطلوب

max_discount_amount

number

min_order_amount

number

valid_from

string

valid_until

string

usage_limit_total

integer

usage_limit_per_subject

integer

is_active

boolean

201 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)422 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/coupons \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME10",
    "name": "Acme Trading Co.",
    "discount_type": "fixed",
    "discount_value": 250,
    "description": "…"
  }'

GET /coupons/{id} عرض كوبون

عرض كوبون

الصلاحية: coupons:read

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/coupons/{id} \
  -H "Authorization: Bearer shk_live_…"

PATCH /coupons/{id} تعديل كوبون

تعديل كوبون

الصلاحية: coupons:write

المعاملات

id

path · integer · مطلوب

حقول الطلب

code

string · مطلوب

name

string · مطلوب

description

string

discount_type

string · fixed | percentage · مطلوب

discount_value

number · مطلوب

max_discount_amount

number

min_order_amount

number

valid_from

string

valid_until

string

usage_limit_total

integer

usage_limit_per_subject

integer

is_active

boolean

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/coupons/{id} \
  -X PATCH \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME10",
    "name": "Acme Trading Co.",
    "discount_type": "fixed",
    "discount_value": 250,
    "description": "…"
  }'

DELETE /coupons/{id} حذف كوبون

حذف كوبون

الصلاحية: coupons:write

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/coupons/{id} \
  -X DELETE \
  -H "Authorization: Bearer shk_live_…"

GET /coupons/{id}/redemptions عرض عمليات استخدام الكوبون

عرض عمليات استخدام الكوبون

الصلاحية: coupons:read

المعاملات

id

path · integer · مطلوب

200 · قائمة مقسّمة لصفحات

مثال على الطلب

curl https://api.shrkity.com/api/v1/coupons/{id}/redemptions \
  -H "Authorization: Bearer shk_live_…"

عروض الأسعار

عروض أسعار مخصّصة.

7 نقاط وصول

GET /quotations عرض عروض الأسعار

عرض عروض الأسعار

الصلاحية: quotations:read

200 · قائمة مقسّمة لصفحات

مثال على الطلب

curl https://api.shrkity.com/api/v1/quotations \
  -H "Authorization: Bearer shk_live_…"

POST /quotations إنشاء عرض سعر

إنشاء عرض سعر

الصلاحية: quotations:write

حقول الطلب

المستلم + بنود العرض، بما يطابق نموذج «عرض سعر جديد» في البوابة.

201 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/quotations \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ …see field reference… }'

GET /quotations/{id} استعراض عرض السعر

استعراض عرض السعر

الصلاحية: quotations:read

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/quotations/{id} \
  -H "Authorization: Bearer shk_live_…"

POST /quotations/{id}/send إرسال عرض السعر إلى المستلم

إرسال عرض السعر إلى المستلم

الصلاحية: quotations:write

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/quotations/{id}/send \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

POST /quotations/{id}/withdraw سحب عرض سعر مُرسَل

سحب عرض سعر مُرسَل

الصلاحية: quotations:write

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/quotations/{id}/withdraw \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

POST /quotations/{id}/accept قبول عرض سعر كعميل الموضوع

الصلاحية: quotations:write. يتطلب موضوعًا دائمًا.

الصلاحية: quotations:write

المعاملات

id

path · integer · مطلوب

X-Shirkty-Client-User-Id

header · integer · مطلوب

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

سياق منشأة اختياري للموضوع

حقول الطلب

linked_company_id

integer

مطلوب عندما يحتاج عرض السعر ربط منشأة (موضوع شخصي)

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/quotations/{id}/accept \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "linked_company_id": 42
  }'

POST /quotations/{id}/reject رفض عرض سعر كعميل الموضوع

رفض عرض سعر كعميل الموضوع

الصلاحية: quotations:write

المعاملات

id

path · integer · مطلوب

X-Shirkty-Client-User-Id

header · integer · مطلوب

BFF subject: Shirkty client user id

X-Shirkty-Company-Id

header · integer

سياق منشأة اختياري للموضوع

حقول الطلب

reason

string · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/quotations/{id}/reject \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "X-Shirkty-Client-User-Id: 1001" \
  -H "X-Shirkty-Company-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "…"
  }'

الفواتير

فواتير صادرة عن النظام (للقراءة فقط).

3 نقاط وصول

GET /invoices عرض الفواتير

عرض الفواتير

الصلاحية: invoices:read

200 · قائمة مقسّمة لصفحات

مثال على الطلب

curl https://api.shrkity.com/api/v1/invoices \
  -H "Authorization: Bearer shk_live_…"

GET /invoices/{id} عرض فاتورة

عرض فاتورة

الصلاحية: invoices:read

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/invoices/{id} \
  -H "Authorization: Bearer shk_live_…"

GET /invoices/{id}/pdf عرض ملف الفاتورة PDF (تحويل 302 إلى الملف)

عرض ملف الفاتورة PDF (تحويل 302 إلى الملف)

الصلاحية: invoices:read

المعاملات

id

path · integer · مطلوب

302 · تحويل إلى ملف الـ PDF المُولَّد

مثال على الطلب

curl https://api.shrkity.com/api/v1/invoices/{id}/pdf \
  -H "Authorization: Bearer shk_live_…"

الاتصالات

طلبات الاتصال من العميل إلى المنشأة.

4 نقاط وصول

GET /connections عرض طلبات الاتصال والاتصالات النشطة

عرض طلبات الاتصال والاتصالات النشطة

الصلاحية: connections:read

المعاملات

status

query · string

مثل pending، active، rejected، revoked

200 · قائمة مقسّمة لصفحات

مثال على الطلب

curl https://api.shrkity.com/api/v1/connections \
  -H "Authorization: Bearer shk_live_…"

POST /connections/{id}/approve الموافقة على اتصال معلّق

يحصل العميل على صلاحية الوصول إلى السجل المشترك، وتبدأ الطلبات والمستندات بالتدفّق.

الصلاحية: connections:write

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)409 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/connections/{id}/approve \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

POST /connections/{id}/reject رفض اتصال معلّق

يمكن اختياريًا تمرير {"reason": "…"}.

الصلاحية: connections:write

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)409 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/connections/{id}/reject \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

POST /connections/{id}/revoke إلغاء اتصال نشط

ينهي العلاقة، ويمكن اختياريًا تمرير {"reason": "…"}.

الصلاحية: connections:write

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)409 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/connections/{id}/revoke \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

المستندات

سجلات مستندات التزام العملاء.

3 نقاط وصول

GET /documents عرض مستندات التزام العملاء

سجلات المستندات عبر المنشآت التي تخدمها: السجل التجاري والتراخيص والإقامة وغيرها من عناصر الالتزام، مع الحالة وتاريخ الانتهاء. اجمع company_id مع expiring_soon=true (أو expires_from/expires_to) لتغذية مسار التجديد.

الصلاحية: documents:read

المعاملات

company_id

query · integer

company_employee_id

query · integer

document_type_id

query · integer

status

query · string

expiring_soon

query · boolean

المستندات داخل نافذة التجديد فقط

expires_from

query · string

expires_to

query · string

search

query · string

200 · قائمة مقسّمة لصفحات

مثال على الطلب

curl https://api.shrkity.com/api/v1/documents \
  -H "Authorization: Bearer shk_live_…"

GET /documents/{id} عرض سجل مستند

عرض سجل مستند

الصلاحية: documents:read

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)404 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/documents/{id} \
  -H "Authorization: Bearer shk_live_…"

GET /document-types عرض أنواع مستندات المنشأة

عرض أنواع مستندات المنشأة

الصلاحية: documents:read

200 · قائمة مقسّمة لصفحات

مثال على الطلب

curl https://api.shrkity.com/api/v1/document-types \
  -H "Authorization: Bearer shk_live_…"

الويب هوكس

اشتراكات الأحداث الصادرة: طلبات POST موقّعة لأحداث التدقيق التي تشترك بها.

7 نقاط وصول

GET /webhooks عرض الويب هوكس (لا تُضمَّن الأسرار أبدًا — أعد التدوير للحصول على سر جديد)

عرض الويب هوكس (لا تُضمَّن الأسرار أبدًا — أعد التدوير للحصول على سر جديد)

الصلاحية: webhooks:read

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/webhooks \
  -H "Authorization: Bearer shk_live_…"

POST /webhooks إنشاء ويب هوك

عمليات التسليم عبارة عن طلبات POST موقّعة باستخدام X-Shirkty-Signature: t=<unix>,v1=<hex hmac-sha256(secret, t + '.' + body)>. يُعرض سر التوقيع مرة واحدة هنا ومرة عند كل تدوير. تتباعد إعادات المحاولة 1m/5m/30m/2h/8h، ثم يُعلَّم التسليم بأنه ميّت؛ ولا تُتَّبع عمليات إعادة التوجيه أبدًا. يجب أن تكون عناوين URL نقاط نهاية https عامة — وتُرفض النطاقات الشبكية الخاصة والمحجوزة. أزل التكرار اعتمادًا على delivery_id. بحد أقصى 5 ويب هوكس لكل مساحة عمل.

الصلاحية: webhooks:write

حقول الطلب

name

string · مطلوب

url

string · مطلوب

https مطلوب (يُسمح بـ http على localhost أثناء التطوير)

events

array · مطلوب

معرّفات إجراءات التدقيق، أو أحرف بدل بادئة (order.*) أو * — مثل ["order.*", "quotation.accepted"]

is_active

boolean

201 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)422 · خطأ

مثال على الطلب

curl https://api.shrkity.com/api/v1/webhooks \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Trading Co.",
    "url": "…",
    "events": [],
    "is_active": true
  }'

PATCH /webhooks/{id} تعديل ويب هوك (name، url، events، is_active)

تعديل ويب هوك (name، url، events، is_active)

الصلاحية: webhooks:write

المعاملات

id

path · integer · مطلوب

حقول الطلب

name

string · مطلوب

url

string · مطلوب

https مطلوب (يُسمح بـ http على localhost أثناء التطوير)

events

array · مطلوب

معرّفات إجراءات التدقيق، أو أحرف بدل بادئة (order.*) أو * — مثل ["order.*", "quotation.accepted"]

is_active

boolean

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/webhooks/{id} \
  -X PATCH \
  -H "Authorization: Bearer shk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Trading Co.",
    "url": "…",
    "events": [],
    "is_active": true
  }'

DELETE /webhooks/{id} حذف ويب هوك

حذف ويب هوك

الصلاحية: webhooks:write

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/webhooks/{id} \
  -X DELETE \
  -H "Authorization: Bearer shk_live_…"

POST /webhooks/{id}/test إرسال حدث webhook.test تجريبي الآن

يرسل حدث webhook.test تجريبيًا بشكل متزامن ويبلّغ بنتيجة مبدئية: {ok, category} حيث تكون category إحدى ok | non_2xx | connect_failed | invalid_url. خاضع لتحديد معدّل صارم.

الصلاحية: webhooks:write

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/webhooks/{id}/test \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

GET /webhooks/{id}/deliveries عرض عمليات التسليم الأخيرة مع الحالة والمحاولات

عرض عمليات التسليم الأخيرة مع الحالة والمحاولات

الصلاحية: webhooks:read

المعاملات

id

path · integer · مطلوب

200 · قائمة مقسّمة لصفحات

مثال على الطلب

curl https://api.shrkity.com/api/v1/webhooks/{id}/deliveries \
  -H "Authorization: Bearer shk_live_…"

POST /webhooks/{id}/rotate-secret تدوير سر التوقيع (يُعرض مرة واحدة)

تدوير سر التوقيع (يُعرض مرة واحدة)

الصلاحية: webhooks:write

المعاملات

id

path · integer · مطلوب

200 · مورد واحد (يطابق شكله استجابة البوابة لنفس المورد؛ والحقول إضافية فقط ضمن v1)

مثال على الطلب

curl https://api.shrkity.com/api/v1/webhooks/{id}/rotate-secret \
  -X POST \
  -H "Authorization: Bearer shk_live_…"

جاهز للبناء على شركتي؟

الوصول عبر API يأتي مع باقتَي التوسّع والمؤسسات. أنشئ أول مفتاح API لك من تطبيق سطح المكتب وستتحدث أنظمتك مع مكتبك الخلفي اليوم.

اطلب عرضًا توضيحيًا شاهد الأسعار

مكتبك كله، على واجهة API واحدة.

من مفتاح API إلى أول طلب في دقائق.

أنشئ مفتاحًا

صادِق طلباتك

نفّذ أول استدعاء

انطلق بأمان

إنشاء طلب: عمليات مقابل موضوع

كتالوج الخدمات: أفراد مقابل شركة

مفتاح API بيانات اعتماد،لا كلمة مرور تُعاد استخدامها.

الأخطاء

تقسيم الصفحات

أمان إعادة المحاولة

حدود المعدّل

الإصدارات

ابنِ تطبيق عميل بعلامتك على خادمك.

وضع العمليات (Ops)

وضع الموضوع (BFF)

صلاحيات BFF الموصى بها

قائمة تحقق الوضع المزدوج (علامة بيضاء)

الباقات والاشتراكات على واجهة BFF.

مدفوع · إلكتروني

مدفوع · دون اتصال

كل نقطة وصول، بحسب المورد.

الخدمات

الطلبات

مهام العميل

المرفقات

العملاء

الشركات

الباقات

الاشتراكات

الكوبونات

عروض الأسعار

الفواتير

الاتصالات

المستندات

الويب هوكس

جاهز للبناء على شركتي؟

مكتبك كله،
على واجهة API واحدة.

مفتاح API بيانات اعتماد،
لا كلمة مرور تُعاد استخدامها.