المطوّرون

مكتبك كله،
على واجهة 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" \
  -d '{
    "service_definition_id": 18,
    "company_id": 42
  }'

# 201 Created
{
  "id": 1208,
  "status": "pending",
  "steps": [ … ]
}

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

الدليل

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

الوصول عبر API جزء من باقتَي التوسّع والمؤسسات. يُنشئ مالك المنشأة مفاتيح API من تطبيق سطح المكتب، بصلاحيات محددة لما يحتاجه تكاملك بالضبط، ويظهر المفتاح مرة واحدة فقط.

أنشئ مفتاحًا

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

صادِق طلباتك

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

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

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

انطلق بأمان

أرسل Idempotency-Key مع عمليات الكتابة فلا تتكرر الأعمال عند إعادة المحاولة، وراقب ترويسات حدود المعدّل، وبدّل المفاتيح بإنشاء مفتاح جديد وإلغاء القديم.

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

المصادقة

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

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

صلاحيات بحسب المورد. orders:write ينشئ الطلبات ولا يلمس الكوبونات. امنح ما يحتاجه التكامل فقط.

قابل للتقييد بعناوين IP. قيّد المفتاح بعناوين خوادمك أو نطاقات CIDR، وتُرفض الاستدعاءات من أي مكان آخر.

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

المصادقة

# 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.

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 — بدل إنشاء نسخة مكررة.

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

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

curl https://api.shrkity.com/api/v1/orders \
  -X POST \
  -H "Authorization: Bearer shk_live_…" \
  -H "Idempotency-Key: erp-po-10422" \
  -d '{ "service_definition_id": 18, "company_id": 42 }'

# run it twice — one order exists.

حدود المعدّل

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

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

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
# on 429 only:
Retry-After: 21

الإصدارات

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

المرجع

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

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

الخدمات

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

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_…"

الطلبات

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

8 نقاط وصول

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)

company_id

integer

مطلوب عندما تتطلب الخدمة سياق منشأة

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,
    "company_id": 42,
    "company_employee_id": 42,
    "priority": "low"
  }'

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_…"

العملاء

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

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": "…"
  }'

PUT /clients/{client_id} تعديل عميل

تعديل عميل

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

المعاملات

client_id

path · integer · مطلوب

حقول الطلب

name

string · مطلوب

email

string · مطلوب

phone_number

string

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

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

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

الشركات

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

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_…"

الاشتراكات

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

7 نقاط وصول

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_…"

عروض الأسعار

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

5 نقاط وصول

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_…"

الفواتير

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

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_…"

المستندات

سجلات مستندات التزام العملاء (للقراءة فقط).

2 نقاط وصول

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_…"

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

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

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

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

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

أنشئ مفتاحًا

صادِق طلباتك

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

انطلق بأمان

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

الأخطاء

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

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

حدود المعدّل

الإصدارات

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

الخدمات

الطلبات

العملاء

الشركات

الباقات

الاشتراكات

الكوبونات

عروض الأسعار

الفواتير

الاتصالات

المستندات

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

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

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