تنزيل المستندات
مستخرجات السجل وقوائم الشركاء وعقود التأسيس كملفات.
يجلب fetch-document مستندًا من السجل التجاري (Handelsregister) ويُرجعه كملف: بصيغة PDF، أو بصيغة XML لمحتوى السجل المنظّم. كل ما تحتاجه هو الـ entity_id الخاص بالشركة، انظر جلب ملف شركة.
اختيار نوع المستند
هناك خمسة أنواع من المستندات. تمرّر النوع في document_type، مكتوبًا تمامًا كما في الجدول، بما في ذلك الأحرف الكبيرة والصغيرة.
| document_type | المستند | الصيغة | لـ |
|---|---|---|---|
| AD | Aktueller Abdruck (المستخرج الحالي): جميع القيود السارية اليوم | كل شركة مسجلة | |
| CD | Chronologischer Abdruck (المستخرج الزمني): جميع القيود بترتيب زمني | كل شركة مسجلة | |
| SI | Strukturierter Registerinhalt (محتوى السجل المنظّم) بصيغة XJustiz، قابل للقراءة آليًا | XML | كل شركة مسجلة |
| shareholders_list | Gesellschafterliste (قائمة الشركاء) | GmbH وUG | |
| articles_of_association | Satzung أو Gesellschaftsvertrag (عقد التأسيس) | شركات الأموال والتعاونيات |
جلب مستند
مرّر الـ entity_id كـ company_id والنوع كـ document_type. الاستجابة هي الملف نفسه، وليست JSON. يحفظ طلبنا النموذجي Aktueller Abdruck لـ Hetzner Online GmbH، Ansbach HRB 6089.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode "company_id=94eb910fef13f94585c48c263fa446d4" \ --data-urlencode "document_type=AD" \ --fail-with-body --max-time 120 \ -o hetzner-ad.pdf
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-document", headers={"x-api-key": "YOUR_API_KEY"}, params={ "company_id": "94eb910fef13f94585c48c263fa446d4", "document_type": "AD", }, timeout=120, ) response.raise_for_status() with open("hetzner-ad.pdf", "wb") as file: file.write(response.content) print(response.headers["X-Credits-Charged"], "رصيد محتسب")
import { writeFile } from "node:fs/promises"; const url = new URL("https://handelsregister.ai/api/v1/fetch-document"); url.searchParams.append("company_id", "94eb910fef13f94585c48c263fa446d4"); url.searchParams.append("document_type", "AD"); const response = await fetch(url, { headers: { "x-api-key": "YOUR_API_KEY" }, signal: AbortSignal.timeout(120_000), }); if (!response.ok) throw new Error(`HTTP ${response.status}`); await writeFile("hetzner-ad.pdf", Buffer.from(await response.arrayBuffer())); console.log(response.headers.get("x-credits-charged"), "رصيد محتسب");
لأن الاستجابة ليست JSON، فالتفاصيل المتعلقة بها موجودة في الـ Headers:
| الحقل | المعنى |
|---|---|
| Content-Type |
application/pdf، ولمحتوى السجل المنظّم application/xml. |
| Content-Disposition | اسم الملف مع entity_id والنوع واليوم الذي جاء فيه المستند من السجل. |
| X-Credits-Charged | تكلفة الطلب. |
| X-Credits-Remaining | رصيدك بعد ذلك. |
إذا لم يوجد المستند للشركة، تحصل على HTTP 404 دون تكلفة.
1{2 "error": "Document fetch failed",3 "message": "Document not available for this company. It may not exist or may become available later.",4 "meta": {5 "request_credit_cost": 0,6 "credits_remaining": 1457 }8}
الجلب في الخلفية
إذا لم يستطع عميلك الانتظار هذه المدة، اضبط async=true. إذا كان المستند متاحًا بالفعل، يأتي فورًا. وإلا تستجيب الـ API بـ HTTP 202 وتذكر وقت الانتظار بالثواني في Retry-After. في المثال نجلب Chronologischer Abdruck لـ SAP SE، Mannheim HRB 719915.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode 'company_id=e3918174fb6c5d04e5e217e6ee4a6ffe' \ --data-urlencode 'document_type=CD' \ --data-urlencode 'async=true'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-document", headers={"x-api-key": "YOUR_API_KEY"}, params={ "company_id": "e3918174fb6c5d04e5e217e6ee4a6ffe", "document_type": "CD", "async": "true", }, ) data = response.json()
const url = new URL("https://handelsregister.ai/api/v1/fetch-document"); url.searchParams.append("company_id", "e3918174fb6c5d04e5e217e6ee4a6ffe"); url.searchParams.append("document_type", "CD"); url.searchParams.append("async", "true"); const response = await fetch(url, { headers: { "x-api-key": "YOUR_API_KEY" }, }); const data = await response.json();
1{2 "status": "processing",3 "meta": {4 "message": "The document is being retrieved. Repeat this request after Retry-After seconds to receive it.",5 "retry_after": 20,6 "request_credit_cost": 0,7 "credits_remaining": 1458 }9}
كرّر الطلب نفسه بعد هذه المدة، فيأتي الملف مع HTTP 200. الملف المسلَّم وحده يكلّف أرصدة؛ واستجابة 202 مجانية. إذا لم تتوفر سعة حاليًا، تحصل على HTTP 503، أيضًا مع Retry-After.
يُحتسب كل تكرار ضمن الحد. لذلك انتظر المدة المذكورة بدلًا من السؤال مجددًا على فترات قصيرة.
التكاليف والحدود
| ماذا | الأرصدة |
|---|---|
| مستند واحد تم تسليمه | 15 |
الحد: 5 طلب في الدقيقة. يتشارك البحث والمستندات وSignals حصة واحدة من 60 طلب في الدقيقة.
يكلّف كل مستند مسلَّم 15 رصيد، أيًّا كان النوع. ولأن كل مستند يأتي من السجل، فلـ fetch-document حد خاص أدنى يبلغ 5 طلب في الدقيقة.
مع Idempotency-Key تدفع مقابل المستند مرة واحدة فقط، حتى لو كررت الطلب بعد انقطاعه. المزيد تحت الحدود.
Retry-After. ولا تحتسب الـ API شيئًا. حاول مرة أخرى بعد بضع دقائق.
أخطاء شائعة
- رقم السجل بدلًا من entity_id: يقبل
company_idفقط الـ entity_id المكوّن من 32 حرفًا. Ansbach HRB 6089يُرجع HTTP 400. - قائمة الشركاء لأشكال قانونية أخرى: موجودة فقط لـ GmbH وUG. لـ KG أو تاجر فرد تحصل على HTTP 404.
- المستندات كملفات صور: إذا كان المستند متاحًا في السجل بصيغة TIFF فقط، تستجيب الـ API بـ HTTP 415 ولا تحتسب شيئًا.