التأمين/API v2

السجلات حسب رمز ACAPS

GET/api/v2/insurance/intermediaries/{code}

معلومة مهمة. نسخة من دليل 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[].categorystring

agent: وكيل؛ 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.licensenull

null: لم يتم تحديد رخصة مفتوحة لدليل ACAPS هذا.

القيم المقبولة: null

meta.terms_urlstring

الشروط القانونية لموقع ACAPS.

meta.redistribution_statusstring

permission-not-obtained: لم تُحصل موافقة إعادة النشر.

القيم المقبولة: "permission-not-obtained"

meta.retrieved_atstring

تاريخ جلب المشروع لملف المصدر؛ وليس تاريخ رصد البيانات.

meta.source_updated_atnull

آخر تحديث معلن من المصدر؛ وليس تاريخ جلب الملف.

القيم المقبولة: null

meta.transformation_versionstring

إصدار قواعد تحويل مجموعة البيانات؛ مستقل عن إصدار الواجهة.

meta.source_record_countinteger

عدد السجلات في المصدر قبل مرشحات الواجهة.

meta.coverageobject

النطاق الجغرافي والزمني المتاح فعلياً.

meta.coverage.recordsinteger

عدد السجلات المختلفة في النسخة قبل التصفية.

meta.coverage.completeboolean

هل يشمل الجمع جميع السجلات المعلنة في الدليل؛ لا يضمن شمولية تغطية السوق.

meta.real_timeboolean

تعني false أن المشاهدات تاريخية دون تحديث مباشر.

القيم المقبولة: false

meta.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: معامل غير صالح أو مفقود.
404: المورد غير موجود.

تتضمن الأخطاء error.code وerror.message وerror.request_id.

errorobject: تفاصيل الطلب الفاشل؛ تحل محل data وmeta.
error.codestring: رمز ثابت للخطأ، مثل RESOURCE_NOT_FOUND؛ استعمله في منطق التطبيق.
error.messagestring: شرح مقروء للخطأ؛ استعمل code في منطق التطبيق.
error.request_idstring: معرّف هذا الطلب، يفيد عند الإبلاغ عن مشكلة.

السجلات حسب رمز ACAPS

المعاملات

طلبك