الأقسام
في هذه الصفحة

كيف أربط واجهة الطلبات والعقود؟

توفّر هذه الواجهة للقراءة فقط بيانات الطلبات والعقود والمدفوعات والإيصالات المتاحة لعيادة واحدة، لاستخدامها في 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.