Node SDK

الـ API من JavaScript وTypeScript.

يقدّم Node SDK عميلًا لـ JavaScript وTypeScript، مع تعريفات أنواع للطلبات والاستجابات. يعيد المحاولة عند الأخطاء المؤقتة بنفسه ويحوّل استجابات الخطأ إلى فئات أخطاء مخصصة.

التثبيت

ثبّت الحزمة handelsregister عبر npm.

Terminal

npm install handelsregister
export HANDELSREGISTER_API_KEY=YOUR_API_KEY

ماذا
ماذا	القيمة
الحزمة	`handelsregister`
الإصدار الحالي	0.7.0
Node.js	22.13 أو أحدث
TypeScript	تعريفات الأنواع مضمّنة
الترخيص	AGPL-3.0
الكود المصدري	github.com/Handelsregister-AI/handelsregister-js

يقرأ الـ SDK مفتاح API من متغير البيئة HANDELSREGISTER_API_KEY. ويمكنك أيضًا تمريره عند إنشاء العميل. أما Bearer token فيمر عبر HANDELSREGISTER_BEARER_TOKEN أو bearerToken. يُرسل المفتاح دائمًا في الـ Header، وليس أبدًا في الـ URL.

الطلب الأول

تجلب fetchOrganization ملف شركة وتُرجع استجابة الـ API ككائن. يقبل المعامل q اسمًا، أو محكمة السجل مع رقم السجل، أو entity_id.

JavaScript

import { Handelsregister } from 'handelsregister';

const client = new Handelsregister({ apiKey: process.env.HANDELSREGISTER_API_KEY });

const company = await client.fetchOrganization({ q: 'Hetzner Online GmbH' });
console.log(company.entity_id, company.name);
console.log(company.registration); // { court: 'Ansbach', register_type: 'HRB', register_number: '6089' }
console.log(company.meta.request_credit_cost);

الاستجابة هي نفسها التي لـ fetch-organization. إليك مقتطفًا:

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  "meta": {12    "request_credit_cost": 5,13    "credits_remaining": 14514  }15}

200 · مقتطف من استجابتنا النموذجية لـ Hetzner Online GmbH، Ansbach HRB 6089، البيانات الأساسية فقط

تطلب مزيدًا من البيانات عبر features، ووضع الذكاء الاصطناعي عبر aiSearch: true، والوقت الفعلي عبر realtimeMode: true. جميع الميزات مذكورة تحت fetch-organization.

JavaScript

const company = await client.fetchOrganization({
  q: 'Ansbach HRB 6089',
  features: ['financial_kpi', 'related_persons'],
});

لمدة ساعة يجيب العميل عن الطلبات المتطابقة من ذاكرته المؤقتة، دون أرصدة جديدة. أما الطلبات مع الوقت الفعلي فتذهب دائمًا إلى الـ API. اضبط cacheEnabled: false لإيقاف الذاكرة المؤقتة.

معالجة الأخطاء

تصبح كل استجابة خطأ من الـ API خطأً بفئته الخاصة. وجميعها ترث من HandelsregisterError وتحمل statusCode، والاستجابة في response، والتكاليف في meta.

الاستثناء
الاستثناء	الحالة	المعنى
AuthenticationError	401	مفتاح API مفقود أو غير صالح.
InsufficientCreditsError	402	رصيدك لا يكفي لهذا الطلب.
SubscriptionRequiredError	403	يحتاج الطلب إلى خطة أعلى. يذكر `requiredPlans` الخطط المناسبة.
NotFoundError	404	لم يُعثر على شركة أو شخص مطابق.
RequestTimeoutError	408	لم يُجب السجل في الوقت المناسب. لم يُحتسب شيء.
RequestValidationError	400, 422	لمعامل ما قيمة غير صالحة.
RateLimitError	429	طلبات كثيرة جدًا في الدقيقة.
ServerError	5xx	مصدر البيانات غير متاح أو مثقل حاليًا. أعد المحاولة لاحقًا.

JavaScript

import {
  Handelsregister,
  HandelsregisterError,
  InsufficientCreditsError,
  NotFoundError,
  RequestTimeoutError,
} from 'handelsregister';

const client = new Handelsregister({ timeout: 120000 });

try {
  const company = await client.fetchOrganization({
    q: 'Hetzner Online GmbH',
    realtimeMode: true,
  });
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('لم يُعثر على شركة مطابقة');
  } else if (error instanceof InsufficientCreditsError) {
    console.log('الرصيد غير كافٍ:', error.meta);
  } else if (error instanceof RequestTimeoutError) {
    console.log('السجل لا يستجيب حاليًا، حاول لاحقًا');
  } else if (error instanceof HandelsregisterError) {
    console.log('خطأ:', error.statusCode, error.message);
  } else {
    throw error;
  }
}

عند أخطاء الشبكة والحالة 429 وأخطاء الخادم يعيد الـ SDK المحاولة بنفسه، بحد أقصى ثلاث محاولات إجمالًا. وإذا أرسلت الـ API وقت انتظار في Retry-After، فإنه يلتزم به.

افتراضيًا ينتظر العميل 90 ثانية للاستجابة. للوقت الفعلي وملفات الأشخاص والمستندات نوصي بـ 120 ثانية على الأقل، أي timeout: 120000.

سطر الأوامر

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

Terminal

# ملف الشركة دون وضع الذكاء الاصطناعي، مع المؤشرات المالية الرئيسية فقط
npx handelsregister fetch "Hetzner Online GmbH" --no-ai-search --feature financial_kpi

# حفظ قائمة الشركاء (Gesellschafterliste) بصيغة PDF
npx handelsregister document "Hetzner Online GmbH" --type shareholders_list --output hetzner.pdf

دون خيارات إضافية يفعّل handelsregister fetch وضع الذكاء الاصطناعي. ويكلّف الطلب حينها 25 رصيد بدلًا من 5، حتى دون ميزات. ومع --no-ai-search تطلب دون وضع الذكاء الاصطناعي.

يبحث handelsregister document أولًا عن الشركة عبر ملف شركة دون وضع الذكاء الاصطناعي. لذلك تُضاف 5 رصيد إلى 15 رصيد للمستند.

المرجع

المرجع الكامل بجميع الدوال موجود في ملف README في المستودع. يغطي الـ SDK الـ API بأكملها:

ملفات الشركات بجميع الميزات، وكذلك كفئة Company
ملفات الأشخاص، وكذلك كفئة Person
البحث والتصدير مع الفلاتر والفرز والتنقل التلقائي بين الصفحات
المستندات كملفات
Signals وMonitoring ونقاط نهاية webhook، مع التحقق من توقيع webhook
الحساب والرصيد والاستخدام ومفاتيح API
إثراء ملفات CSV وJSON وExcel كاملة

الـ SDK مرخّص بموجب AGPL-3.0. تجد الكود المصدري على GitHub والحزمة على npm.

fetch-organization جميع معاملات ملف الشركة وميزاته وحقوله. Python SDK الـ API نفسها من Python.