الوصول إلى API

مصادقة طلب

استخدم https://allocyn.com/api/public/v1 للخدمة المستضافة. ولأي نشر آخر، استخدم نطاق HTTPS الخاص به وأي مسار أساسي، مثل https://example.com/allocyn/api/public/v1.

أرسل المفتاح الكامل في X-Allocyn-Key. لا يحل محله رمز Bearer أو سر Webhook أو ملف تعريف ارتباط تسجيل الدخول في المتصفح. وفّر ALLOCYN_API_KEY بأمان قبل تشغيل مثال PowerShell؛ فهو ينفّذ طلب قراءة واحدًا.

GET /api/public/v1/projects?page=1&pageSize=100 HTTP/1.1
Host: allocyn.com
Accept: application/json
X-Allocyn-Key: <your-api-key>

$apiBase = 'https://allocyn.com/api/public/v1'
if ([string]::IsNullOrWhiteSpace($env:ALLOCYN_API_KEY)) {
    throw 'Set ALLOCYN_API_KEY securely before running this example.'
}
$apiHeaders = @{ 'X-Allocyn-Key' = $env:ALLOCYN_API_KEY; Accept = 'application/json' }
$page = Invoke-RestMethod -Method Get -Uri "$apiBase/projects?page=1&pageSize=100" -Headers $apiHeaders
$page.data | Select-Object code, name, status, health

الموارد والنطاقات المدعومة

هذه المسارات نسبية إلى عنوان API العامة الأساسي وتقبل GET. لا توجد نقاط نهاية عامة لتغيير هذه الموارد أو تسجيل الوقت أو إنشاء التقارير وتنزيلها أو إدارة العملاء وWebhooks باستخدام مفتاح API.

التنقل بين الصفحات

يعيد كل مورد data وmeta. زد قيمة page ما دامت meta.hasMore تساوي true. تحسب القيمة المعادة هذه الصفحة فقط؛ وتحتوي الصفحة التي تتجاوز البيانات المتاحة على مصفوفة data فارغة.

تُرتب المشاريع حسب الرمز، وعناصر العمل حسب العنوان، والأشخاص حسب اسم العرض، جميعها تصاعديًا؛ وتُرتب التقارير حسب وقت الإنشاء تنازليًا. تقسيم الصفحات ليس لقطة ثابتة: قد تغيّر التحديثات وتساوي قيم الفرز حدود الصفحات. أزل التكرارات حسب id وطابق البيانات دوريًا. لا تتوفر معلمات للتصفية أو الفرز المخصص أو التغييرات منذ تاريخ معين.

{
  "data": [{
    "id": "11111111-1111-7111-8111-111111111111",
    "code": "CLIENT-PORTAL",
    "name": "Client portal",
    "status": "Active",
    "health": "OnTrack",
    "startsOn": "2026-09-01",
    "currentTargetEndDate": "2026-11-30"
  }],
  "meta": { "page": 1, "pageSize": 100, "returned": 1, "hasMore": false }
}

مرجع حقول الاستجابة

تظهر هذه الحقول في كل كائن data. المعرّفات نصوص معتمة، وقيم الحالة وصحة المشروع أسماء تعداد من الخادم، وقيم التاريخ دون الوقت بتنسيق YYYY-MM-DD، والطوابع الزمنية بتوقيت UTC تستخدم ISO 8601. قد تكون الحقول الاختيارية null. معرّفات السجلات المرتبطة ليست روابط تنزيل.

الحدود والأخطاء

يُشارك حد العميل بين طلباته إلى API العامة ضمن نوافذ ثابتة مدة كل منها دقيقة بتوقيت UTC. يسمح حد عام منفصل بـ300 طلب في الدقيقة لكل عنوان IP بعيد، ويُشارك مع الطلبات الأخرى من ذلك العنوان. رفع إعداد العميل لا يتجاوز هذا الحد؛ وقد تفرض بنية الاستضافة حدودًا إضافية.

يعيد تجاوز حد طلبات العميل الرمز 401 دون ترويسة مخصصة للسبب أو موعد إعادة التعيين. بعد التحقق من بيانات الاعتماد والنطاقات، أعد محاولة الطلب الذي تجاوز الحد بعد بداية الدقيقة التالية بتوقيت UTC. لا تكرر المحاولات باستمرار عند استمرار استجابات 401. قد تكون رسائل الأخطاء مترجمة، وقد تعيد الخوادم الوسيطة أجسام استجابة مختلفة.

{
  "status": 401,
  "title": "API access denied",
  "detail": "The API key is invalid, expired, revoked, outside its rate limit, or missing the required scope."
}

نطاق المؤسسة والتوافر

ينتمي مفتاح API إلى مؤسسة واحدة. ويقرأ بيانات المؤسسة بالكامل ضمن النطاقات المحددة له، لا بيانات المشاريع المسندة إلى منشئه فقط. لا توجد ترويسة أو معلمة استعلام لاختيار المؤسسة من جانب المستدعي. أعطِ المفتاح فقط للخدمات المخوّلة بتلقي هذه المعلومات.

تتطلب الاستدعاءات مؤسسة نشطة، ووحدة التكاملات مفعّلة فيها، واشتراكًا مؤهلًا، واستحقاق API مفعّلًا. قد تسمح فترة تجريبية غير منتهية أو فترة مدفوعة مؤهلة بالوصول؛ أما الفترة التجريبية المنتهية أو فترة استرداد الاشتراك فلا تسمحان به. ويخضع الإنشاء أيضًا للحد المُعدّ لعملاء API.

استبدال مفتاح أو إلغاؤه

لا يمكن كشف مفاتيح العملاء الحاليين أو تدويرها أو تعديل نطاقاتهم أو تواريخ انتهائها مباشرةً. راعِ حد العملاء النشطين عند تشغيل العميلين القديم والجديد معًا. إذا لم تتوفر خانة، فنسّق فترة انقطاع أو تواصل مع المسؤول.

• أنشئ بديلًا باسم مميز والنطاقات وحد الطلبات وموعد الانتهاء المطلوبة؛ واحفظ مفتاحه الذي يظهر عند الإنشاء.
• حدّث خدمتك وتأكّد من نجاح قراءة مصرح بها، ثم ألغِ العميل القديم من قسم الوصول إلى API.
• عند الاشتباه في اختراق، ألغِ المفتاح أولًا. يمنع الإلغاء المصادقة مستقبلًا، لكنه لا يسترد بيانات قُرئت بالفعل ولا يلغي طلبًا سبق تفويضه. يبقى العملاء الملغون في القائمة ولا يمكن إعادة تفعيلهم من هذه الواجهة.

مرجع إدارة عملاء API

تستخدم هذه المسارات وصول المؤسسة المعتاد الموثّق، وليس X-Allocyn-Key. أضف قبلها /api/organization/integration-operations وأي مسار أساسي للنشر. يتطلب العرض integrations.view؛ ويتطلب الإنشاء والإلغاء أيضًا integrations.manage.

يتضمن ملخص العميل الحقول id وname وrequestsPerMinute وexpiresAtUtc وisActive وkeyPrefix وlastUsedAtUtc وpermissions وversion. أرسل أحدث قيمة version المعتمة بترميز Base64 عند الإلغاء؛ وأعد التحميل بعد تعارض 409. تعيد أخطاء التحقق الرمز 400، وقد تعيد إخفاقات المصادقة أو التفويض الرمز 401 أو 403.

انتهاء الصلاحية واستكشاف المشكلات

في طلبات الإدارة، قدّم طابعًا زمنيًا مستقبليًا بتوقيت UTC، مثل 2027-01-01T00:00:00Z، أو null للحقل expiresAtUtc. لا تحوّل أداة اختيار انتهاء الصلاحية في البوابة التاريخ والوقت المحليين صراحةً إلى UTC قبل الإرسال. تحقّق من الانتهاء المخزّن بدلًا من افتراض تحويل المنطقة الزمنية. يبقى العملاء المنتهون الذين لم تُلغَ مفاتيحهم محسوبين ضمن حد العملاء النشطين.

إذا لم تظهر الصفحة أو زر الإنشاء، فتحقّق من المؤسسة المختارة وintegrations.view وintegrations.manage ووصول الاشتراك وحدوده. للدعم، قدّم المسار والوقت بتوقيت UTC والحالة وترويسة الاستجابة X-Correlation-ID عند توفرها. لا ترسل مفتاح API مطلقًا.