MoroccoAPIالبحث عن وسطاء التأمين
معلومة مهمة. نسخة من دليل ACAPS: الوكلاء والسماسرة ومكاتب التدبير المباشر. راجع التغطية وتاريخ الجمع؛ لا يتم التحقق من الاعتماد آنياً. لم تُحصل موافقة إعادة النشر.
فهم الإجابة
data: النتائج المطلوبة، في كائن أو قائمة.
meta: مصادر البيانات ورخصتها وتواريخها. تعني null أن القيمة غير معروفة أو غير متاحة.
meta.pagination: القوائم: 100 نتيجة افتراضياً، و500 كحد أقصى. استخدم limit وoffset؛ تكون meta.pagination.next_offset بقيمة null في الصفحة الأخيرة.
مثال توضيحي: مع limit=10 وoffset=0 تتضمن الصفحة الأولى 10 نتائج على الأكثر. إذا كانت next_offset تساوي 10، اطلب التالية بـoffset=10 والمرشحات نفسها. توقف عندما تصبح next_offset بقيمة null.
API v2 هو المسار المرجعي. تبقى مسارات /api/v1 القديمة أسماء بديلة متوافقة مع السلوك المنشور حالياً، بما فيه تقسيم الصفحات؛ لم يُحدد موعد لحذفها.
حقول الإجابة 6
تشير [] إلى كل عنصر في القائمة. تعني null غير معروف أو غير متاح، ولا تعني صفراً. لغة الدليل لا تترجم قيم المصادر.
dataobject[]النتيجة المطلوبة: كائن واحد أو قائمة.
data[].acaps_codestringرمز ACAPS من المصدر مع الاحتفاظ بالأصفار واللواحق. قد تشترك عدة سجلات في رمز واحد.
data[].namestring | nullالاسم التجاري أو الممثل المهني؛ قد يحدد هوية شخص. null عند غيابه.
data[].categorystringagent: وكيل؛ broker: سمسار؛ direct-office: مكتب تدبير مباشر.
القيم المقبولة:
"agent""broker""direct-office"data[].insurerstring | nullشركة التأمين الموكلة في المصدر؛ null عند غيابها. لا يثبت الحصرية.
data[].citystring | nullاسم المنطقة كما ورد في المصدر؛ قد يتضمن حياً أو مدينة تابعة.
بنية البيانات
{
"type": "object",
"additionalProperties": false,
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"acaps_code",
"name",
"category",
"insurer",
"city"
],
"properties": {
"acaps_code": {
"type": "string",
"maxLength": 64,
"pattern": "^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$",
"description": "ACAPS code as published; retained as text, including leading zeros and branch suffixes."
},
"name": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "string",
"nullable": true,
"enum": [
null
]
}
],
"description": "Source business name or professional representative; may identify an individual. Null when blank in the source."
},
"category": {
"type": "string",
"enum": [
"agent",
"broker",
"direct-office"
]
},
"insurer": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "string",
"nullable": true,
"enum": [
null
]
}
],
"description": "Source mandante, or null when absent. Does not establish exclusivity."
},
"city": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "string",
"nullable": true,
"enum": [
null
]
}
],
"description": "Unmodified source locality label; may include a district or parent city."
}
}
}
},
"meta": {
"type": "object",
"additionalProperties": false,
"required": [
"dataset",
"total",
"license",
"terms_url",
"redistribution_status",
"retrieved_at",
"source_updated_at",
"transformation_version",
"source_record_count",
"coverage",
"real_time",
"limitations",
"sources",
"pagination"
],
"properties": {
"dataset": {
"enum": [
"acaps-insurance-intermediaries"
]
},
"total": {
"type": "integer",
"minimum": 0
},
"license": {
"type": "string",
"nullable": true,
"enum": [
null
]
},
"terms_url": {
"type": "string",
"format": "uri"
},
"redistribution_status": {
"enum": [
"permission-not-obtained"
]
},
"retrieved_at": {
"type": "string",
"format": "date"
},
"source_updated_at": {
"type": "string",
"nullable": true,
"enum": [
null
]
},
"transformation_version": {
"type": "string",
"minLength": 1
},
"source_record_count": {
"type": "integer",
"minimum": 1
},
"coverage": {
"type": "object",
"additionalProperties": false,
"required": [
"records",
"complete"
],
"properties": {
"records": {
"type": "integer",
"minimum": 1
},
"complete": {
"type": "boolean"
}
}
},
"real_time": {
"enum": [
false
]
},
"limitations": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"sources": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"dataset",
"producer",
"source_url"
],
"properties": {
"dataset": {
"type": "string",
"minLength": 1
},
"producer": {
"type": "string",
"minLength": 1
},
"source_url": {
"type": "string",
"format": "uri"
}
}
}
},
"pagination": {
"type": "object",
"additionalProperties": false,
"required": [
"limit",
"offset",
"count",
"has_more",
"next_offset"
],
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 500
},
"offset": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"count": {
"type": "integer",
"minimum": 0,
"maximum": 500
},
"has_more": {
"type": "boolean"
},
"next_offset": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
{
"type": "string",
"nullable": true,
"enum": [
null
]
}
]
}
}
}
}
}
}
}المصادر وتقسيم الصفحات 25
metaobjectسياق النتيجة: المصادر والتواريخ والرخصة وتقسيم الصفحات عند الاقتضاء.
meta.datasetstringاسم مجموعة البيانات الخاصة بالنتيجة أو المصدر.
القيم المقبولة:
"acaps-insurance-intermediaries"meta.totalintegerعدد النتائج المطابقة للمرشحات قبل تقسيم الصفحات؛ وليس حجم هذه الصفحة.
meta.licensenullnull: لم يتم تحديد رخصة مفتوحة لدليل ACAPS هذا.
القيم المقبولة:
nullmeta.terms_urlstringالشروط القانونية لموقع ACAPS.
meta.redistribution_statusstringpermission-not-obtained: لم تُحصل موافقة إعادة النشر.
القيم المقبولة:
"permission-not-obtained"meta.retrieved_atstringتاريخ جلب المشروع لملف المصدر؛ وليس تاريخ رصد البيانات.
meta.source_updated_atnullآخر تحديث معلن من المصدر؛ وليس تاريخ جلب الملف.
القيم المقبولة:
nullmeta.transformation_versionstringإصدار قواعد تحويل مجموعة البيانات؛ مستقل عن إصدار الواجهة.
meta.source_record_countintegerعدد السجلات في المصدر قبل مرشحات الواجهة.
meta.coverageobjectالنطاق الجغرافي والزمني المتاح فعلياً.
meta.coverage.recordsintegerعدد السجلات المختلفة في النسخة قبل التصفية.
meta.coverage.completebooleanهل يشمل الجمع جميع السجلات المعلنة في الدليل؛ لا يضمن شمولية تغطية السوق.
meta.real_timebooleanتعني false أن المشاهدات تاريخية دون تحديث مباشر.
القيم المقبولة:
falsemeta.limitationsstring[]القيود المعروفة للمصدر أو التغطية؛ اقرأها قبل استخدام البيانات.
meta.sourcesobject[]المصادر المستخدمة لهذه النتيجة مع الجهات المنتجة والرخص.
meta.sources[].datasetstringاسم مجموعة البيانات الخاصة بالنتيجة أو المصدر.
meta.sources[].producerstringالجهة التي تنشر البيانات الأصلية.
meta.sources[].source_urlstringصفحة نشر المصدر أو التعريف ببياناته.
meta.paginationobjectمعلومات لتصفّح نتائج القائمة صفحة بصفحة.
meta.pagination.limitintegerالعدد الأقصى المطلوب في الصفحة: 100 افتراضياً و500 كحد أقصى.
meta.pagination.offsetintegerعدد النتائج المتجاوزة قبل هذه الصفحة بعد التصفية. تبدأ الصفحة الأولى من 0.
meta.pagination.countintegerعدد النتائج الموجودة فعلياً في هذه الصفحة.
meta.pagination.has_morebooleanتكون true إذا بقيت صفحة أخرى من النتائج.
meta.pagination.next_offsetinteger | nullقيمة offset للصفحة التالية؛ null عند النهاية. احتفظ بالمرشحات نفسها.
الأخطاء
400: معامل غير صالح أو مفقود.
تتضمن الأخطاء error.code وerror.message وerror.request_id.
errorobjectتفاصيل الطلب الفاشل؛ تحل محل data وmeta.
error.codestringرمز ثابت للخطأ، مثل RESOURCE_NOT_FOUND؛ استعمله في منطق التطبيق.
error.messagestringشرح مقروء للخطأ؛ استعمل code في منطق التطبيق.
error.request_idstringمعرّف هذا الطلب، يفيد عند الإبلاغ عن مشكلة.