كيف أربط واجهة الطلبات والعقود؟
توفّر هذه الواجهة للقراءة فقط بيانات الطلبات والعقود والمدفوعات والإيصالات المتاحة لعيادة واحدة، لاستخدامها في 1C أو نظام محاسبي آخر. لا تنفّذ الواجهة الدفع ولا تغلق العقود ولا تُصدر الإيصالات.
التفعيل والمفتاح الموحّد
يفتح مسؤول النظام أولاً صفحة تعديل العيادة في /admin، ثم يفعّل إتاحة الواجهة للعيادة في تبويب النظام ويحفظ التغييرات. هذا الإذن معطّل افتراضياً. بدونه يُخفى قسم الواجهة من لوحة العيادة وتُحظر إدارة المفتاح وطلبات الواجهة.
بعد ذلك يفتح المسؤول الرئيسي للعيادة الإعدادات ← الإعدادات العامة ← واجهة الأنظمة الخارجية، ثم يفعّل الوصول ويحفظ الإعدادات. يمكن إظهار المفتاح ونسخه وإعادة إصداره في القسم نفسه. لا يستطيع المسؤول العادي إدارة المفتاح، ولا تستطيع العيادة منح نفسها إذن النظام.
يؤدي سحب الإذن في /admin إلى إخفاء القسم فوراً وحظر الوصول بالمفتاح الحالي. يُحتفظ بالمفتاح وإعداد التفعيل الخاص بالعيادة؛ وعند إعادة الإذن تعود الحالة السابقة. يتطلب الوصول كلاً من إذن النظام وتفعيل الواجهة من العيادة.

يُستخدم مفتاح واحد للطلبات والعقود، ويُرسل في الترويسة Authorization: Bearer <API_KEY> وليس في عنوان URL. يؤدي تعطيل الوصول إلى حظر الطلبات فوراً مع الاحتفاظ بالمفتاح. تؤدي إعادة الإصدار إلى إبطال المفتاح السابق فوراً.
يحدّد المفتاح العيادة. لا تُقبل المعلمة clinic_id. تعيد محاولة قراءة سجل عيادة أخرى الحالة 404، كما في حالة السجل غير الموجود.
المسارات والصيغ
العنوان الأساسي هو https://medsenger.ru/api/integrations/v1.
| المسار | الوظيفة |
|---|---|
GET /consulting-orders |
قائمة الطلبات أو تحديثاتها |
GET /consulting-orders/{id} |
طلب واحد |
GET /contracts |
قائمة العقود أو تحديثاتها |
GET /contracts/{id} |
عقد واحد |
تنزيل مواصفات OpenAPI 3.0. تتضمن المواصفات الحقول والحالات والمخططات الدقيقة. تُرجع القوائم data: [] وmeta، ويُرجع السجل الفردي data: {}. تُرسل جميع التواريخ، بما فيها تواريخ المدفوعات والإيصالات المتداخلة، كأعداد صحيحة من ثواني Unix (int64). المبالغ أعداد صحيحة من الكوبيك في amount_minor والعملة RUB. تعني null أن القيمة غير معروفة أو غير متاحة.
curl --get 'https://medsenger.ru/api/integrations/v1/consulting-orders' \
--header "Authorization: Bearer $MEDSENGER_API_KEY" \
--data-urlencode 'limit=100'
معلمات القوائم
تُرسل المعلمات في سلسلة الاستعلام. جميع المعلمات اختيارية. كل طلب مستقل، ولا تُستخدم جلسة تصدير أو رموز متابعة.
| المعلمة | النوع | الوصف |
|---|---|---|
page |
integer | رقم الصفحة بدءاً من 1. الافتراضي: 1. |
limit |
integer | حجم الصفحة من 1 إلى 500. الافتراضي: 100. |
updated_since |
integer, int64 | السجلات المتغيرة منذ طابع Unix الزمني المحدد، مع تضمين الحد الأدنى. عند غيابه لا يُطبّق قيد على وقت التغيير. |
created_from |
integer, int64 | الحد الأدنى لوقت الإنشاء بثواني Unix، شاملاً. |
created_to |
integer, int64 | الحد الأعلى لوقت الإنشاء بثواني Unix، شاملاً. يجب ألا تتجاوز البداية النهاية. |
status |
string | الحالة الحالية للطلب أو العقد؛ القيم المسموحة موضحة أدناه. |
is_paid |
0 أو 1 | للطلبات فقط: وجود دفعة مرتبطة غير مدفوعة أو مدفوعة. |
تقبل المعلمات الزمنية أعداداً صحيحة من الثواني من 0 إلى 253402300799 (نهاية عام 9999). لا تُقبل الملّي ثانية أو نصوص التواريخ. تشير الحدود إلى الثواني المحددة دون تقريب إلى أيام كاملة. تُطبّق جميع شروط المرشّحات المرسلة معاً.
يشير updated_since إلى نشر تغيير البيانات المصدَّرة، بما فيه الدفع والإيصال وإتمام الخدمة. الطلبات التي لا تتضمن دفعة مرتبطة مستبعدة من كلٍّ من is_paid=0 وis_paid=1.
curl --get 'https://medsenger.ru/api/integrations/v1/contracts' \
--header "Authorization: Bearer $MEDSENGER_API_KEY" \
--data-urlencode 'updated_since=1791972000' \
--data-urlencode 'page=1' \
--data-urlencode 'limit=100'
استجابة القائمة
تُرجع data القائمة، وتُرجع meta بيانات الصفحة.
| الحقل | النوع | الوصف |
|---|---|---|
meta.page |
integer | رقم الصفحة المطلوبة. |
meta.limit |
integer | حجم الصفحة. |
meta.has_more |
boolean | وجود سجلات لاحقة تطابق المرشّحات. |
meta.generated_at |
integer, int64 | وقت بدء معالجة الطلب الحالي على الخادم بثواني Unix. |
{"data":[],"meta":{"has_more":false,"page":1,"limit":100,"generated_at":1791972060}}
تُرتّب القوائم تصاعدياً حسب ID. تُرجع الواجهة الحالة الحالية ورقم آخر تغيير revision. لا تُرجع الحالات التاريخية الوسيطة. قد تتغيّر البيانات بين طلبات الصفحات، ولذلك لا تمثل الاستجابات لقطة موحّدة للحظة واحدة.
تحتوي السجلات المحذوفة على id وclinic_id وdeleted: true وrevision وupdated_at. تظهر هذه العلامات أيضاً في القوائم دون مرشّحات.
بيانات الطلب
يتضمن الطلب المعرّفات والتواريخ والحالة (created أو payment_required أو accepted أو declined)، والخدمة والمدة والطبيب المختار واسم العميل وبريده وهاتفه والدفعة وحالة العقد المرتبط. تعني payment: null عدم وجود فاتورة مرتبطة، ولا تؤكد أن الخدمة مجانية. قد يظل contract: null بعد الدفع أثناء إنشاء العقد.
يحفظ service شروط العرض الأصلي، ولا يستبدلها بأسعار دليل الخدمات الحالية. في السجلات القديمة التي لا تحتوي على عرض محفوظ، تكون captured=false والاسم والسعر غير المعروفين null. مبلغ الفاتورة المعتمد موجود في payment.amount_minor.
بيانات العقد
تشمل الواجهة جميع عقود العيادة، حتى العقود المنشأة يدوياً دون طلب أو دفع إلكتروني. يتضمن الرد الرقم وبيانات المريض واتصالاته والخدمة والطبيب الرئيسي والمسؤول ونوع العقد وتواريخ البدء والانتهاء والتفعيل ونمطي البدء المؤجل والمدة غير المحدودة وحالة الاستنتاج الطبي وتأكيد إتمام الخدمة ومصفوفة payments.
| الحقل | المعنى |
|---|---|
status |
waiting_activation أو active أو expired أو closed |
awaiting_conclusion |
هل لا يزال استكمال الاستنتاج الطبي منتظراً؟ |
concluded_at |
وقت إتمام الاستنتاج |
service_completed_at |
وقت التأكيد الصريح لتقديم الخدمة |
service_completed_by |
نوع ومعرّف من أكّد الإتمام |
consulting_order_id |
الطلب المرتبط أو null |
انتهاء المدة أو إغلاق العقد لا يؤكد تلقائياً تقديم الخدمة. يتاح تأكيد الخدمة دون ربط صندوق نقدي، ولا يُستنتج من وجود إيصال نهائي. إعادة فتح العقد لا تلغي تلقائياً خدمة سبق تأكيد تقديمها. تظهر تغييرات المدة والطبيب والتفعيل والاستنتاج وانتهاء المدة في المزامنة.
لا تُصدَّر التشخيصات أو المحادثات أو الوثائق الطبية أو نص الاستنتاج أو بيانات دخول بوابة الدفع أو روابط الدخول المحتوية على رموز.
المدفوعات والإيصالات الاختيارية
قد يحتوي العقد على عدة مدفوعات. تحمل الدفعة نفسها ID نفسه في الطلب والعقد. توثّق is_paid الدفع المؤكد. قد تشير status=requires_review وissue إلى استرداد أو إلغاء أو مشكلة مطابقة، حتى مع is_paid=true.
يصف payment.fiscalization آلية الإيصالات السحابية في Medsenger لهذه العملية. عند enabled_for_order=false لا تُصدر الإيصالات عبر هذه الآلية؛ هذا ليس خطأ ولا يعني أن نظاماً خارجياً أو بوابة الدفع لم تُصدر إيصالاً. النمطان هما on_contract وadvance، وأنواع الإيصالات full وadvance وsettlement.
حالات الإيصال هي pending وsubmitting وaccepted وprocessed وconfirmed وfailed. تعني processed إنشاء الإيصال وانتظار إرساله إلى OFD، وتعني confirmed تأكيد الإرسال. تتاح معرّفات الإيصال ورابطه والبيانات الضريبية المعروفة. لا تغيّر إعدادات العيادة الجديدة إعدادات العملية السابقة.
تُحدَّد بيئة الدفع وبيئة الصندوق النقدي منفصلتين: test أو production أو null إذا كانت غير معروفة. تعني null أن البيئة غير معروفة.
الأخطاء والحدود
صيغة الخطأ: {"error":{"code":"unauthorized","message":"…","details":{}}}. الحقل code رمز خطأ ثابت، وmessage نص مترجم، وdetails معلومات إضافية.
| HTTP | الرمز | المعنى |
|---|---|---|
| 401 | unauthorized |
لا يوجد مفتاح صالح. |
| 403 | api_disabled |
الواجهة معطّلة من النظام أو العيادة. |
| 404 | not_found |
السجل مفقود أو غير متاح. |
| 405 | method_not_allowed |
طريقة HTTP غير مدعومة. |
| 422 | invalid_parameters |
معلمات الطلب غير صالحة. |
| 429 | rate_limited |
تجاوز حد الطلبات. |
| 503 | export_preparing |
لم يكتمل تحضير البيانات. |
| 500 | internal_error |
خطأ داخلي في الخادم. |
الحد الافتراضي 120 طلباً في الدقيقة لكل عيادة، مشترك بين الموردين. تتضمن استجابات 429 و503 الترويسة Retry-After بمدة الانتظار بالثواني. قد يصاحب تحضير قائمة كبيرة الرد 503 export_preparing.