البيانات الأساسية
الاسم والشكل القانوني وقيد السجل والعنوان وغرض الشركة ورأس المال وقواعد التمثيل: البيانات الأساسية لكل ملف شركة.
تصف البيانات الأساسية هوية الشركة: الاسم والشكل القانوني وقيد السجل والعنوان والغرض ورأس المال وقواعد التمثيل. وهي جزء من البيانات الأساسية وتأتي مع كل ملف شركة، دون طلب ميزة.
تأتي معظم الحقول من السجل التجاري (Handelsregister) والسجلات الرسمية الأخرى. ونجمع أيضًا الكلمات المفتاحية والمنتجات وبيانات الاتصال من الويب. ما يجب على الشركة تسجيله يتوقف على شكلها القانوني؛ ويبيّن عمود «التوفر» ذلك لكل حقل.
مثال
الأمثلة في هذه الصفحة مأخوذة من طلب نموذجي لـ Hetzner Online GmbH، Ansbach HRB 6089. إذا تغيّر قيدها، يُرجع طلبك قيمًا مختلفة.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode 'q=Hetzner Online GmbH'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-organization", headers={"x-api-key": "YOUR_API_KEY"}, params={ "q": "Hetzner Online GmbH", }, ) data = response.json()
const url = new URL("https://handelsregister.ai/api/v1/fetch-organization"); url.searchParams.append("q", "Hetzner Online GmbH"); const response = await fetch(url, { headers: { "x-api-key": "YOUR_API_KEY" }, }); const data = await response.json();
1{2 "entity_id": "94eb910fef13f94585c48c263fa446d4",3 "name": "Hetzner Online GmbH",4 "status": "ACTIVE",5 "legal_form": "GmbH",6 "registration": {7 "court": "Ansbach",8 "register_type": "HRB",9 "register_number": "6089"10 },11 "keywords": [12 "Dedicated Server",13 "Cloud Hosting",14 "Webhosting",15 "Colocation",16 "Object Storage",17 "Domainregistrierung",18 "SSL-Zertifikate",19 "Web-Hosting-Unternehmen"20 ],21 "products_and_services": [22 "Dedizierte Root-Server (Dedicated Servers)",23 "Cloud-Server und virtuelle Server",24 "Managed Server",25 "Webhosting (Shared Hosting)",26 "Colocation Rack / Rechenzentrumsflächen",27 "Storage Box / Object Storage / Storage Share",28 "Domain-Registrierung",29 "SSL-Zertifikate",30 "Load Balancer",31 "DNS Console",32 "Registration Robot",33 "Custom Solutions"34 ],35 "industry_classification": {36 "WZ2008": [37 {38 "code": "62.01.0",39 "label": "Erbringung von Dienstleistungen der Informationstechnologie"40 },41 {42 "code": "63.11.0",43 "label": "Datenverarbeitung, Hosting und damit verbundene Tätigkeiten"44 },45 {46 "code": "61.90.0",47 "label": "Telekommunikation, sonstige"48 }49 ],50 "WZ2025": [51 {52 "code": "62.20.1",53 "label": "Erbringung von Beratungsleistungen auf dem Gebiet der Informationstechnologie"54 },55 {56 "code": "46.50.1",57 "label": "Großhandel mit Datenverarbeitungsgeräten, peripheren Geräten und Software"58 },59 {60 "code": "62.90.0",61 "label": "Erbringung von sonstigen Dienstleistungen der Informationstechnologie"62 }63 ]64 },65 "contact_data": {66 "website": "https://www.hetzner.com/",67 "phone_number": "09831 5050",68 "email": "[email protected]"69 },70 "address": {71 "house_number": "25",72 "street": "Industriestraße",73 "postal_code": "91710",74 "city": "Gunzenhausen",75 "county": "Weißenburg-Gunzenhausen",76 "state": "Bayern",77 "country": "DEU",78 "coordinates": {79 "latitude": 49.12483,80 "longitude": 10.7805281 }82 },83 "seat": {84 "city": "Gunzenhausen"85 },86 "registration_date": null,87 "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 "value": [94 "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."95 ],96 "effective_from": "2002-10-15",97 "effective_to": "2015-07-28"98 },99 {100 "value": [101 "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."102 ],103 "effective_from": "2015-07-28",104 "effective_to": null105 }106 ]107 },108 "capital": {109 "current": {110 "amount": 50000,111 "currency": "EUR",112 "kind": "STAMMKAPITAL"113 },114 "history": [115 {116 "value": {117 "amount": 50000,118 "currency": "EUR",119 "kind": "GRUNDKAPITAL"120 },121 "effective_from": "2002-10-15",122 "effective_to": null123 }124 ]125 },126 "purpose": "Die Durchführung von Internet- und Netzwerkdienstleistungen, das Erstellen und Vertreiben von Software, der Handel mit Hard- und Software, der Betrieb einer Werbeagentur,darüber hinaus der Im- und Export von Waren aller Art, soweit sie keiner Einfuhr- oder Ausfuhrbeschränkung unterliegen und soweit keine Genehmigungen erforderlich sind.",127 "meta": {128 "request_credit_cost": 5,129 "credits_remaining": 145130 }131}
الاسم والشكل القانوني
يصف الاسم والشكل القانوني والحالة الشركة، ويحدّدها الـ entity_id. احفظ الـ entity_id إذا أردت جلب شركة أو مراقبتها لاحقًا، أو ربطها ببياناتك.
| الحقل | المعنى | مثال | التوفر |
|---|---|---|---|
| entity_idstring | معرّف الشركة لدى handelsregister.ai. احفظه كمفتاح في بياناتك. في المعامل q يطابق هذه الشركة تحديدًا.البيانات الأساسية |
"94eb910fef13f94585c48c263fa446d4" |
دائمًا |
| namestring | اسم الشركة كما يظهر في السجل، مع لاحقة الشكل القانوني. |
"Hetzner Online GmbH" |
كما في الأعلى |
| legal_formstring |
الشكل القانوني، عادةً بالاختصار الألماني الشائع. قارن دون مراعاة حالة الأحرف، لأن التهجئة قد تختلف قليلًا، مثل oHG. ومع وضع الذكاء الاصطناعي قد يظهر الشكل الكامل. تبيّن القائمة القيم الشائعة؛ وهناك غيرها.القيم: GmbH Gesellschaft mit beschränkter Haftung (شركة ذات مسؤولية محدودة), UG (haftungsbeschränkt) Unternehmergesellschaft (GmbH مصغّرة), AG Aktiengesellschaft (شركة مساهمة), SE Societas Europaea (شركة أوروبية), KGaA Kommanditgesellschaft auf Aktien (شركة توصية بالأسهم), GmbH & Co. KG KG مع GmbH كشريك متضامن, KG Kommanditgesellschaft (شركة توصية بسيطة), OHG Offene Handelsgesellschaft (شركة تضامن), e.K. eingetragener Kaufmann (تاجر فرد مسجل), eG eingetragene Genossenschaft (جمعية تعاونية مسجلة), PartG Partnerschaftsgesellschaft (شراكة مهنية)، وكذلك بمسؤولية مهنية محدودة, e.V. eingetragener Verein (جمعية مسجلة), eGbR eingetragene Gesellschaft bürgerlichen Rechts (شركة مدنية مسجلة) |
"GmbH" |
كما في الأعلى |
| statusstring |
حالة الشركة في السجل. قيم أخرى ممكنة؛ تعامل مع القيم غير المعروفة على أنها «غير نشطة».القيم: ACTIVE نشطة, INSOLVENT في إجراءات إعسار, DISSOLVED منحلّة، في طور التصفية, TERMINATED مشطوبة من السجل |
"ACTIVE" |
كما في الأعلى |
قيد السجل
تحدّد محكمة السجل ونوع السجل ورقم السجل الشركة. نكتبها معًا، في مثالنا «Ansbach HRB 6089». ويمكنك أيضًا تمريرها بهذه الصيغة في المعامل q.
| الحقل | المعنى | مثال | التوفر |
|---|---|---|---|
| registrationobject|null | قيد الشركة في السجل.فارغ عندما يعرف وضع الذكاء الاصطناعي الشركة من مصادر الويب فقط؛ ويبدأ الـ entity_id حينها بـ AI_TMP_البيانات الأساسية | – | دائمًا |
| registration.courtstring | محكمة السجل كاسم مكان، دون «Amtsgericht» (المحكمة المحلية)، مثل Ansbach أو Charlottenburg (Berlin). |
"Ansbach" |
كما في الأعلى |
| registration.register_typestring |
نوع السجل، أي السجل، وللسجل التجاري قسمه.القيم: HRB السجل التجاري القسم B: GmbH وUG وAG وSE وKGaA, HRA السجل التجاري القسم A: e.K. وOHG وKG وGmbH & Co. KG, GnR Genossenschaftsregister (سجل التعاونيات), PR Partnerschaftsregister (سجل الشراكات), VR Vereinsregister (سجل الجمعيات), GsR Gesellschaftsregister (سجل الشركات المدنية) لـ eGbR |
"HRB" |
كما في الأعلى |
| registration.register_numberstring | رقم السجل كنص. فريد فقط مع محكمة السجل ونوع السجل. |
"6089" |
كما في الأعلى |
| registration_datestring|null | تاريخ القيد في السجل، كطابع زمني بصيغة ISO 8601.فارغ عندما التاريخ غير مسجل |
"2013-03-18T00:00:00+00:00" |
غالبًا: GmbH, UG, AG, SE, KGaA, KG, OHG, eG, PartG نادرًا: GmbH & Co. KG, e.K. |
رقم السجل فريد فقط مع محكمة السجل الخاصة به. قد يكون للعديد من المحاكم الرقم نفسه.
العنوان والمقر المسجل
address هو عنوان العمل، وseat هو المقر المسجل (Sitz) في السجل. وقد يختلفان، مثلًا عندما تكون الشركة مسجلة في ميونخ وتعمل في Gauting.
| الحقل | المعنى | مثال | التوفر |
|---|---|---|---|
| addressobject | عنوان عمل الشركة.البيانات الأساسية | – | دائمًا |
| address.streetstring|null | الشارع دون رقم المبنى.فارغ عندما يتكون العنوان من المدينة فقط |
"Industriestraße" |
غالبًا |
| address.house_numberstring|null | رقم المبنى كنص، وكذلك مع لاحقة مثل «6 a».فارغ عندما ليس للعنوان رقم مبنى |
"25" |
كما في الأعلى |
| address.postal_codestring|null | الرمز البريدي كنص، لتبقى الأصفار البادئة محفوظة.فارغ عندما يتكون العنوان من المدينة فقط |
"91710" |
كما في الأعلى |
| address.citystring | مدينة عنوان العمل. |
"Gunzenhausen" |
دائمًا |
| address.countystring | المقاطعة (Landkreis) أو المدينة المستقلة عن المقاطعات. يغيب كمفتاح في بعض العناوين. |
"Weißenburg-Gunzenhausen" |
غالبًا |
| address.statestring | الولاية الاتحادية (Bundesland). يغيب كمفتاح في بعض العناوين. |
"Bayern" |
كما في الأعلى |
| address.countrystring | البلد كرمز ISO 3166 من ثلاثة أحرف، مثل DEU. يغيب كمفتاح في بعض العناوين. |
"DEU" |
كما في الأعلى |
| address.coordinatesobject | الإحداثيات الجغرافية لعنوان العمل، للخرائط وعمليات البحث ضمن نطاق. | – | كما في الأعلى |
| address.coordinates.latitudenumber|null | خط العرض بالدرجات العشرية.فارغ عندما تعذّر تحديد الموقع الجغرافي للعنوان |
49.12483 |
كما في الأعلى |
| address.coordinates.longitudenumber|null | خط الطول بالدرجات العشرية.فارغ عندما تعذّر تحديد الموقع الجغرافي للعنوان |
10.78052 |
كما في الأعلى |
| seatobject | المقر المسجل للشركة (Sitz) في السجل. | – | دائمًا |
| seat.citystring | مدينة المقر المسجل. وقد تختلف عن عنوان العمل. |
"Gunzenhausen" |
كما في الأعلى |
غرض الشركة والقطاع
غرض الشركة (Unternehmensgegenstand) مسجل في السجل لـ GmbH وUG وAG وSE وKGaA وeG وPartG. أما GmbH & Co. KG وKG وOHG والتجار الأفراد (e.K.) فلا يسجلون غرضًا. والقطاع والكلمات المفتاحية والمنتجات والخدمات متوفرة لكل شكل قانوني.
| الحقل | المعنى | مثال | التوفر |
|---|---|---|---|
| purposestring|null | غرض الشركة كما يظهر في السجل، بالألمانية. مع وضع الذكاء الاصطناعي يكون ملخصًا قصيرًا للنشاط، حتى للأشكال القانونية التي لا تسجّل غرضًا.فارغ عندما الشكل القانوني لا يسجّل غرضًا، مثل KG وOHG وe.K.البيانات الأساسية |
"Die Durchführung von Internet- und Netzwerkdienstleistun…" |
دائمًا: GmbH, UG, AG, SE, KGaA, eG, PartG أبدًا: GmbH & Co. KG, KG, OHG, e.K. |
| industry_classificationobject | القطاع وفق التصنيف الألماني للأنشطة الاقتصادية (WZ)، بنسختين. | – | دائمًا |
| industry_classification.WZ2025array | رموز القطاعات وفق WZ 2025، النسخة الحالية. ويستخدم فلتر القطاع في البحث هذه الرموز أيضًا.فارغ عندما تعذّر تعيين قطاع | – | غالبًا |
| industry_classification.WZ2025[].codestring | رمز WZ من خمسة أرقام، مثل 62.20.1. |
"62.20.1" |
كما في الأعلى |
| industry_classification.WZ2025[].labelstring | اسم النشاط الاقتصادي، بالألمانية. |
"Erbringung von Beratungsleistungen auf dem Gebiet der In…" |
كما في الأعلى |
| industry_classification.WZ2008array | رموز القطاعات وفق النسخة الأقدم WZ 2008، للأنظمة التي لا تزال تستخدمها.فارغ عندما لا يوجد تعيين وفق WZ 2008 | – | أحيانًا |
| industry_classification.WZ2008[].codestring | رمز WZ من خمسة أرقام وفق WZ 2008. |
"62.01.0" |
كما في الأعلى |
| industry_classification.WZ2008[].labelstring | اسم النشاط الاقتصادي، بالألمانية. |
"Erbringung von Dienstleistungen der Informationstechnolo…" |
كما في الأعلى |
| keywordsarray | كلمات مفتاحية عن نشاط الشركة، مجمّعة من مصادر الويب العامة. موسّعة مع وضع الذكاء الاصطناعي.فارغ عندما حضور الشركة على الويب ضعيف | – | كما في الأعلى |
| products_and_servicesarray | منتجات الشركة وخدماتها كقائمة، مجمّعة من مصادر الويب العامة. موسّعة مع وضع الذكاء الاصطناعي.فارغ عندما حضور الشركة على الويب ضعيف | – | كما في الأعلى |
مع وضع الذكاء الاصطناعي يحتوي
purpose على ملخص قصير للنشاط بدلًا من نص السجل. ويضيف وضع الذكاء الاصطناعي كلمات مفتاحية ومنتجات وخدمات من الويب.
رأس المال
تسجّل شركات الأموال رأس مالها (Stammkapital أو Grundkapital)، وكل تغيير بتاريخه. current هو المبلغ الساري، وhistory التغييرات بترتيب زمني. ليس لشركات الأشخاص والتجار الأفراد رأس مال ثابت؛ وهناك يكون current بقيمة null وhistory فارغًا.
| الحقل | المعنى | مثال | التوفر |
|---|---|---|---|
| capitalobject | رأس المال المسجل مع تاريخه.البيانات الأساسية | – | دائمًا |
| capital.currentobject|null | مبلغ رأس المال الساري.فارغ عندما الشكل القانوني لا يسجّل رأس مال ثابتًا، مثل KG وOHG وe.K. وPartG | – |
دائمًا: GmbH, UG, AG, SE, KGaA نادرًا: eG أبدًا: GmbH & Co. KG, KG, OHG, e.K., PartG |
| capital.current.amountnumber | المبلغ كرقم، بعملة currency. |
50000 |
كما في الأعلى |
| capital.current.currencystring | العملة كرمز ISO 4217، وهي EUR في جميع الحالات تقريبًا. |
"EUR" |
كما في الأعلى |
| capital.current.kindstring |
نوع رأس المال. قيم أخرى ممكنة.القيم: STAMMKAPITAL Stammkapital (رأس المال الأساسي) لـ GmbH أو UG, GRUNDKAPITAL Grundkapital (رأس مال الأسهم) لـ AG أو SE أو KGaA, LIABILITY_SUM Haftsumme (مبلغ المسؤولية)، مثلًا لجمعية تعاونية, CONDITIONAL رأس مال مشروط لـ AG، في قيود سابقة |
"STAMMKAPITAL" |
كما في الأعلى |
| capital.historyarray | جميع المبالغ المسجلة بترتيب زمني، بما في ذلك المبلغ الساري. | – | كما في الأعلى |
| capital.history[].valueobject | المبلغ مع amount وcurrency وkind، بالبنية نفسها التي لـ current. | – | كما في الأعلى |
| capital.history[].value.change_amountobject | مبلغ التغيير وفق قيد السجل، مع amount وcurrency. أما ما إذا زِيد رأس المال أو خُفّض فيتبيّن بمقارنته بالمبلغ السابق. | – |
أحيانًا: AG, SE, KGaA نادرًا: GmbH, UG, eG أبدًا: GmbH & Co. KG, KG, OHG, e.K., PartG |
| capital.history[].effective_fromstring|null | ساري المفعول من هذا اليوم، بالصيغة YYYY-MM-DD. |
"2002-10-15" |
دائمًا: GmbH, UG, AG, SE, KGaA نادرًا: eG أبدًا: GmbH & Co. KG, KG, OHG, e.K., PartG |
| capital.history[].effective_tostring|null | ساري المفعول حتى هذا اليوم.فارغ عندما المبلغ لا يزال ساريًا |
"2005-02-28" |
كما في الأعلى |
نقرأ تاريخ رأس المال آليًا من قيود السجل. نستخدم لذلك أحدث التقنيات ونستثمر كثيرًا في الجودة؛ ومع ذلك تبقى أخطاء فردية ممكنة.
قواعد التمثيل
تحدّد قواعد التمثيل (Vertretungsregelung) من يحق له التصرف باسم الشركة. تحتويها الاستجابة حرفيًا من السجل، بالألمانية. في طلبنا النموذجي لـ Hetzner Online GmbH ذكر التاريخ مجلس الإدارة (Vorstand) حتى 28 يوليو 2015، ثم المديرين بعد ذلك. أما صلاحية الأشخاص الأفراد فتجدها تحت صلاحية التمثيل.
| الحقل | المعنى | مثال | التوفر |
|---|---|---|---|
| representation_schemeobject | قواعد التمثيل العامة للشركة مع تاريخها.البيانات الأساسية | – |
دائمًا: GmbH, UG, GmbH & Co. KG, KG, OHG, eG, PartG غالبًا: AG, SE, KGaA, e.K. |
| representation_scheme.currentarray|null | القواعد السارية كقائمة من فقرات نصية، حرفيًا من السجل.فارغ عندما لا توجد قواعد مسجلة | – | كما في الأعلى |
| representation_scheme.historyarray | جميع النسخ المسجلة مع صلاحيتها، بما في ذلك النسخة السارية. | – | كما في الأعلى |
| representation_scheme.history[].valuearray | نص هذه النسخة كقائمة من الفقرات. | – | كما في الأعلى |
| representation_scheme.history[].effective_fromstring|null | سارية المفعول من هذا اليوم، بالصيغة YYYY-MM-DD. |
"2002-10-15" |
كما في الأعلى |
| representation_scheme.history[].effective_tostring|null | سارية المفعول حتى هذا اليوم.فارغ عندما النسخة لا تزال سارية |
"2015-07-28" |
كما في الأعلى |
مع الوقت الفعلي يكون
history فارغًا. النسخة السارية موجودة في current.
الاتصال والويب
بيانات الاتصال ليست في السجل. نجمعها من موقع الشركة على الويب. لذلك يتوقف وجودها على ما تنشره الشركة على الويب.
| الحقل | المعنى | مثال | التوفر |
|---|---|---|---|
| contact_dataobject | بيانات الاتصال من موقع الشركة على الويب.البيانات الأساسية | – | دائمًا |
| contact_data.websitestring|null | عنوان الموقع.فارغ عندما لم يُعثر على موقع |
"https://www.hetzner.com/" |
أحيانًا |
| contact_data.phone_numberstring|null | رقم الهاتف كما تنشره الشركة. الصيغة غير موحّدة.فارغ عندما لم يُعثر على رقم |
"09831 5050" |
كما في الأعلى |
| contact_data.emailstring|null | عنوان البريد الإلكتروني العام للشركة.فارغ عندما لم يُعثر على عنوان |
"[email protected]" |
كما في الأعلى |
| website_contentstring|null |
نص الموقع بصيغة Markdown، مثلًا لتحليلك الخاص أو لنموذج لغوي. يأتي مع الميزة website_content، فقط مع وضع الذكاء الاصطناعي ودون تكلفة إضافية.فارغ عندما لم يُعثر على موقعwebsite_content |
"Dedicated Servers, Cloud & Hosting from Germany | Hetzne…" |
كما في الأعلى |
الوقت الفعلي
مع realtime_mode=handelsregister-default تستعلم الـ API أيضًا من السجل التجاري مباشرةً. تحتوي الاستجابة حينها على الأشخاص المسجلين حاليًا وعلى _realtime_mode بنتيجة الاستعلام. يُحتسب الوقت الفعلي فقط إذا نجح الاستعلام، لكن حينها بغض النظر عما يُرجعه.
| الحقل | المعنى | مثال | التوفر |
|---|---|---|---|
| _realtime_modeobject | نتيجة استعلام الوقت الفعلي. موجودة في الاستجابة فقط إذا طلبت realtime_mode.البيانات الأساسية | – | دائمًا |
| _realtime_mode.modestring | الوضع المطلوب، handelsregister-default. |
"handelsregister-default" |
كما في الأعلى |
| _realtime_mode.statusstring |
ما إذا نجح الاستعلام المباشر. مع أي قيمة أخرى تحتوي الاستجابة على البيانات المخزنة، ولا يُحتسب الوقت الفعلي.القيم: success نجح الاستعلام المباشر، والبيانات تأتي مباشرةً من السجل التجاري |
"success" |
كما في الأعلى |
يستغرق استعلام الوقت الفعلي وقتًا أطول، لذا اضبط مهلة الانتظار في عميلك على 120 ثانية على الأقل. إذا فشل الاستعلام المباشر، تُرجع الـ API البيانات المخزنة. حينها لا يكون
_realtime_mode.status بقيمة success، ولا يُحتسب الوقت الفعلي. وإذا استغرق الطلب وقتًا طويلًا جدًا، تحصل على 408 دون تكلفة؛ حاول مرة أخرى لاحقًا.