المفاهيم الأساسية

تحديد الشركات بشكل قاطع

يقبل المعامل q في fetch-organization ثلاثة أنواع من المدخلات. الأمثلة في هذه الصفحة طلبات لـ Hetzner Online GmbH، Ansbach HRB 6089:

تحديد الشركات بشكل قاطع
المُدخل	مثال	متى يناسب
اسم الشركة	`Hetzner Online GmbH`	للبداية. اكتب الاسم كاملًا قدر الإمكان كما يظهر في السجل.
محكمة السجل ورقم السجل	`Ansbach HRB 6089`	فريد لكل شركة مسجلة. المحكمة ونوع السجل والرقم متلازمة.
entity_id	`94eb910fef13f94585c48c263fa446d4`	للطلبات اللاحقة. تحصل عليه في كل استجابة.

رقم السجل وحده لا يكفي، لأن كل محكمة سجل تمنح أرقامها الخاصة. أما الترتيب فحرّ: في المثال يجد HRB 6089 Ansbach الشركة نفسها.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'q=Ansbach HRB 6089'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "q": "Ansbach HRB 6089",
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-organization");
url.searchParams.append("q", "Ansbach HRB 6089");

const response = await fetch(url, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const data = await response.json();

إذا كان لعدة شركات الاسم نفسه، فقد تُرجع الـ API إحداها، وليست بالضرورة التي تريدها، أو تستجيب بـ 404. عندما تكون الشركة الصحيحة مهمة، استعلم بمحكمة السجل ورقم السجل أو بالـ entity_id.

إذا لم تجد الـ API شركة، تستجيب بـ 404 ولا تحتسب شيئًا. وللمدخلات غير الدقيقة يوجد وضع الذكاء الاصطناعي (ai_search=on-default): فهو يجد الشركة أيضًا من أجزاء الاسم ويبحث عنها على الويب. يكلّف 20 رصيد إضافي، حتى لو لم يجد شركة. وللحصول على عدة مرشحين دفعة واحدة، استخدم البحث والتصدير.

الميزات

يحتوي كل ملف شركة على البيانات الأساسية، بما فيها الاسم والشكل القانوني والحالة وقيد السجل والعنوان والغرض والقطاع ورأس المال وقواعد التمثيل. وكل ما عدا ذلك تطلبه كميزة، مثل related_persons للمديرين أو financial_kpi للمؤشرات المالية.

تمرّر عدة ميزات بتكرار feature أو كقائمة: features=related_persons,financial_kpi. تظهر كل ميزة في الاستجابة تحت مفتاحها الخاص. والاستثناء الوحيد publications، إذ يُسمّى هناك history.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'q=Hetzner Online GmbH' \
  --data-urlencode 'feature=related_persons' \
  --data-urlencode 'feature=financial_kpi'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "q": "Hetzner Online GmbH",
        "feature": ["related_persons", "financial_kpi"],
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-organization");
url.searchParams.append("q", "Hetzner Online GmbH");
url.searchParams.append("feature", "related_persons");
url.searchParams.append("feature", "financial_kpi");

const response = await fetch(url, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const data = await response.json();

تتجاهل الـ API الأسماء غير المعروفة دون رسالة خطأ، لذا تحقّق من التهجئة. والميزات التي لا تشملها خطتك تُترك ولا تُحتسب.

جميع الميزات مع أسعارها مذكورة في fetch-organization، وكل حقل في كتالوج البيانات.

الأرصدة

طلبات البيانات تكلّف أرصدة. لملف الشركة تنطبق هذه القواعد:

ينطبق السعر الأساسي 5 رصيد عندما تُرجع الـ API شركة.
الميزة تكلّف أرصدة فقط عندما تُرجع بيانات في الاستجابة. والميزة الفارغة مجانية، بما في ذلك insolvency_publications دون إدخالات.
الوقت الفعلي ووضع الذكاء الاصطناعي ليسا ميزتين، بل رسومًا إضافية بقواعدها الخاصة:
- يكلّف الوقت الفعلي 10 رصيد إضافي بمجرد نجاح الجلب المباشر. وينطبق ذلك أيضًا عندما لا يُظهر شيئًا جديدًا.
- يكلّف وضع الذكاء الاصطناعي 20 رصيد إضافي، حتى لو لم يجد شركة. ولا تسقط الرسوم إلا عندما تلغي الـ API الطلب بـ 408 لأنه يستغرق وقتًا طويلًا جدًا.
جميع الأخطاء الأخرى لا تكلّف شيئًا.

القاعدة لكل ميزة على حدة موجودة في الفوترة، والأسعار في fetch-organization.

مثال: البيانات الأساسية مع related_persons وfinancial_kpi تكلّف 5 + 2 + 1 = 8 رصيد إذا أرجعت الميزتان بيانات.

قبل كل طلب تتحقق الـ API مما إذا كان رصيدك يغطي أعلى سعر ممكن. وإن لم يكن كذلك، تستجيب بـ 402 ولا تحتسب شيئًا. ما احتُسب فعليًا موجود في meta.request_credit_cost، ورصيدك بعد ذلك في meta.credits_remaining.

1{2  "meta": {3    "request_credit_cost": 5,4    "credits_remaining": 1455  }6}

200 · meta من طلبنا النموذجي بالبيانات الأساسية فقط

تحصل على الأرصدة كأرصدة بداية، أو كل شهر مع اشتراك أرصدة، أو مرة واحدة كأرصدة شحن. دون اشتراك أرصدة تكون أرصدة البداية وأرصدة الشحن صالحة لمدة 30 يومًا؛ ومع اشتراك نشط لا تنتهي صلاحيتها. كل ما عدا ذلك في الفوترة.

حداثة البيانات والوقت الفعلي

افتراضيًا يأتي ملف الشركة من قاعدة بياناتنا. ومدى حداثة المعلومة يتوقف على مصدرها.

السجل التجاري

نُبقي البيانات الأساسية والأشخاص وإعلانات السجل محدّثة في قاعدة بياناتنا من السجل. وهذا سريع ويكفي لمعظم الأغراض.

مع الوقت الفعلي (realtime_mode=handelsregister-default) تجلب الـ API ‏Aktueller Abdruck (AD، المستخرج الحالي) مباشرةً من السجل التجاري (Handelsregister) لحظة طلبك وتُرجعه بصيغة JSON. وتحصل أيضًا على الأشخاص المسجلين حاليًا في related_persons.current، دون أن تدفع مقابل الميزة.

ما إذا نجح الجلب المباشر يظهر في _realtime_mode.status. ونحتسب 10 رصيد للوقت الفعلي فقط عند success.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'q=Hetzner Online GmbH' \
  --data-urlencode 'realtime_mode=handelsregister-default'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "q": "Hetzner Online GmbH",
        "realtime_mode": "handelsregister-default",
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-organization");
url.searchParams.append("q", "Hetzner Online GmbH");
url.searchParams.append("realtime_mode", "handelsregister-default");

const response = await fetch(url, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
const data = await response.json();

1{2  "name": "Hetzner Online GmbH",3  "_realtime_mode": {4    "mode": "handelsregister-default",5    "status": "success"6  },7  "related_persons": {8    "current": [9      {10        "entity_id": "78ad32e16ff779f589a9e88d23356f74",11        "label": "MANAGING_DIRECTOR",12        "role": {13          "en": {14            "long": "Managing Director",15            "short": "MD"16          },17          "de": {18            "long": "Geschäftsführer",19            "short": "GF"20          }21        },22        "name": "Max Mustermann",23        "name_parts": {24          "given": "Max",25          "family": "Mustermann",26          "maiden": null,27          "canonical_name": "Mustermann, Max",28          "aliases": [29            "Mustermann, Max"30          ],31          "previous_names": null32        },33        "start_date": null,34        "end_date": null,35        "birth_date": "1976-01-15",36        "location": {37          "home": {38            "city": "Musterheim"39          }40        },41        "organization_representation_scheme": {42          "current": [43            "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."44          ],45          "history": []46        },47        "role_representation_scheme": {48          "current": [49            "einzelvertretungsberechtigt",50            "mit der Befugnis, im Namen der Gesellschaft mit sich im eigenen Namen oder als Vertreter eines Dritten Rechtsgeschäfte abzuschließen"51          ],52          "history": []53        }54      },55      {56        "entity_id": "73549375ff7d709b9e7e2941ad1ffaa3",57        "label": "MANAGING_DIRECTOR",58        "role": {59          "en": {60            "long": "Managing Director",61            "short": "MD"62          },63          "de": {64            "long": "Geschäftsführer",65            "short": "GF"66          }67        },68        "name": "Paul Musterwald",69        "name_parts": {70          "given": "Paul",71          "family": "Musterwald",72          "maiden": null,73          "canonical_name": "Musterwald, Paul",74          "aliases": [75            "Musterwald, Paul"76          ],77          "previous_names": null78        },79        "start_date": null,80        "end_date": null,81        "birth_date": "1989-07-18",82        "location": {83          "home": {84            "city": "Probebrück"85          }86        },87        "organization_representation_scheme": {88          "current": [89            "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."90          ],91          "history": []92        },93        "role_representation_scheme": {94          "current": [95            "einzelvertretungsberechtigt"96          ],97          "history": []98        }99      },100      {101        "entity_id": "cfecded2c1d17946c8ab0379aa786eed",102        "label": "MANAGING_DIRECTOR",103        "role": {104          "en": {105            "long": "Managing Director",106            "short": "MD"107          },108          "de": {109            "long": "Geschäftsführer",110            "short": "GF"111          }112        },113        "name": "Jan Musterhuber",114        "name_parts": {115          "given": "Jan",116          "family": "Musterhuber",117          "maiden": null,118          "canonical_name": "Musterhuber, Jan",119          "aliases": [120            "Musterhuber, Jan"121          ],122          "previous_names": null123        },124        "start_date": null,125        "end_date": null,126        "birth_date": "1955-11-06",127        "location": {128          "home": {129            "city": "Probeingen"130          }131        },132        "organization_representation_scheme": {133          "current": [134            "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."135          ],136          "history": []137        },138        "role_representation_scheme": {139          "current": [140            "einzelvertretungsberechtigt"141          ],142          "history": []143        }144      }145    ]146  },147  "meta": {148    "request_credit_cost": 15,149    "credits_remaining": 145150  }151}

200 · مقتطف من مثال على استجابة مع الوقت الفعلي لـ Hetzner Online GmbH

إذا فشل الجلب المباشر، تُرجع الـ API البيانات المخزنة من قاعدة بياناتنا. تعرف ذلك من _realtime_mode.status، الذي لا يكون حينها success. ولا يُحتسب الوقت الفعلي حينها، كما يُظهر meta.request_credit_cost أيضًا.

يستحق الوقت الفعلي ذلك عندما تهم حالة اليوم. مثلًا، تفحص شركاء أعمال جددًا قبل التوقيع، أو ترى من يحق له تمثيل الشركة الآن.

يستغرق جلب الوقت الفعلي وقتًا أطول من الجلب العادي. اضبط مهلة الانتظار في عميلك على 120 ثانية على الأقل. إذا استغرق الطلب وقتًا طويلًا جدًا، تستجيب الـ API بـ 408 ولا تحتسب شيئًا. حاول حينها مرة أخرى لاحقًا.

القوائم المالية السنوية

نبحث يوميًا عن القوائم المالية السنوية المنشورة حديثًا. لكن لدى الشركات حتى اثني عشر شهرًا بعد نهاية السنة المالية لنشرها (§ 325 HGB)، وكثير منها يستنفد المهلة كاملة. وبعض الشركات تتجاوز المهلة القانونية عمدًا وتنشر في وقت أبعد.

لذلك كثيرًا ما تغطي أحدث قائمة السنة قبل الماضية. المزيد في الحداثة.

إعلانات الإعسار

تنشر محاكم الإعسار إعلاناتها عادةً في يوم القرار أو بعده بقليل. تحصل عليها عبر الميزة insolvency_publications، كلٌّ منها مع المحكمة ورقم القضية والتاريخ.

الأخبار

تُرجع الميزة news أخبارًا عن الشركة من الويب، مع العنوان والمصدر والتاريخ والرابط. وتتوقف حداثتها على آخر مرة كُتب فيها عن الشركة. وللشركات الصغيرة كثيرًا ما توجد تقارير مطابقة قليلة فقط.

السجل التاريخي والصلاحية

كثير من التفاصيل يتغير مع الوقت. لذلك تُرجع الـ API الحالة الحالية والتاريخ جنبًا إلى جنب:

current هي الحالة اعتبارًا من اليوم.
يسرد history كل حالة مسجلة مع effective_from وeffective_to. إذا كان effective_to بقيمة null، فالحالة لا تزال سارية اليوم.
الأشخاص موجودون في related_persons.current وrelated_persons.past، كلٌّ منهم مع start_date وend_date.

كل تفصيل له تاريخ يأتي من السجلات والمنشورات، مثلًا من Chronologischer Abdruck (CD، المستخرج الزمني) للسجل التجاري أو من جميع القوائم المالية السنوية المنشورة.

هكذا يبدو الأمر في مثالنا لقواعد التمثيل لـ Hetzner Online GmbH. في الاستجابة النموذجية تذكر مجلس الإدارة حتى 28 يوليو 2015، والمديرين منذ ذلك الحين:

1{2  "representation_scheme": {3    "current": [4      "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."5    ],6    "history": [7      {8        "value": [9          "Ist nur ein Vorstandsmitglied bestellt, so vertritt es die Gesellschaft allein. Sind mehrere Vorstandsmitglieder bestellt, so wird die Gesellschaft durch zwei Vorstandsmitglieder oder durch ein Vorstandsmitglied gemeinsam mit einem Prokuristen vertreten."10        ],11        "effective_from": "2002-10-15",12        "effective_to": "2015-07-28"13      },14      {15        "value": [16          "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."17        ],18        "effective_from": "2015-07-28",19        "effective_to": null20      }21    ]22  }23}

مثال على استجابة: representation_scheme لـ Hetzner Online GmbH

تأتي معظم التواريخ بالصيغة YYYY-MM-DD. إلى أي مدى يعود التاريخ، تجده موصوفًا في العمر والتاريخ.

القيم الفارغة

ليس لكل شركة قيمة لكل حقل. تُظهر الـ API ذلك بطريقتين:

null: لا توجد قيمة لهذا الحقل.
[]: القائمة بلا إدخالات، مثلًا لا توجد إعلانات إعسار.

الميزة المطلوبة دون بيانات تأتي كـ null أو [] ولا تكلّف شيئًا.

1{2  "name": "dm-drogerie markt GmbH + Co. KG",3  "legal_form": "GmbH & Co. KG",4  "contact_data": {5    "website": "https://www.dm.de",6    "phone_number": "+49 721 55920",7    "email": null8  },9  "capital": {10    "current": null,11    "history": []12  },13  "mergers_and_acquisitions": null,14  "insolvency_publications": []15}

مقتطف من مثال على استجابة لـ dm-drogerie markt GmbH + Co. KG، مع قيم فارغة

في كودك عامل المفتاح المفقود وnull و[] بالطريقة نفسها، لأن بعض الكائنات الفارغة تأتي كـ []. واقرأ الحقول أيضًا بأسمائها، لأن ترتيب المفاتيح غير ثابت.

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

الاستقرار والإصدارات

تنمو الـ API بالإضافة. تصل البيانات والميزات الجديدة كحقول جديدة. لا نحذف الحقول الموجودة أبدًا، ولا نعيد تسميتها، ولا نغيّر نوعها ولا معناها. وهذا يُبقي كل إصدار متوافقًا مع ما قبله.

التغييرات التي قد تكسر الكود الحالي تأتي فقط في إصدار API جديد، مثلًا تحت /v2. يعمل الإصدار الحالي تحت /v1.

لذلك اجعل عميلك يتجاهل الحقول غير المعروفة ويعامل القيم غير المعروفة كحالة عامة. الحقول والميزات الجديدة مذكورة في سجل التغييرات.

الخطط

يمكنك استخدام ملف الشركة والمستندات والبحث والتصدير وSignals مع كل حساب، حتى دون اشتراك أرصدة. ويجلب اشتراك الأرصدة أرصدة جديدة كل شهر ويفتح مزيدًا من البيانات:

الخطط
ما تحصل عليه إضافةً	Plus	Pro	Max
ملف الشخص: أدوار الأشخاص ومساهماتهم	مشمول	مشمول	مشمول
البحث والتصدير: فلاتر للملكية والإدارة والإعسار	غير مشمول	مشمول	مشمول
ملف الشركة: أكثر من 90 مؤشرًا ماليًا موسَّعًا	غير مشمول	مشمول	مشمول
ملف الشركة: القوائم المالية للأنشطة لدى شركات الطاقة (§ 6b EnWG)	غير مشمول	غير مشمول	مشمول
ملف الشركة: المساهمون بالتفصيل (`shareholders_deep`)	غير مشمول	غير مشمول	مشمول
شبكة الشركة (`network`)	غير مشمول	مشمول	مشمول
Signals: حالات الإعسار	غير مشمول	مشمول	مشمول
Signals: التحويلات والاندماج والاستحواذ	غير مشمول	غير مشمول	مشمول

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

تجد أسعار الخطط وأرصدتها في صفحة الأسعار.

جلب ملف شركة الاسم ورقم السجل والـ entity_id عمليًا. توفر البيانات ما البيانات المتاحة حسب الشكل القانوني والحجم. الفوترة جميع الأسعار وكيف تتتبعها في كل استجابة. الأخطاء كيف تبدو الأخطاء وما يمكنك فعله.