handelsregister.ai
تسجيل الدخول إنشاء حساب
التوثيق إثراء بيانات العملاء

إثراء بيانات العملاء

أضف بيانات الشركات إلى قائمة عملائك.

لديك قائمة بأسماء شركات أو مدن أو أرقام سجل وتريد أن تضيف إليها بيانات الشركات الرسمية. كل ما تحتاجه هو fetch-organization؛ ولا تحتاج إلى بحث مسبق.

1

مطابقة الشركات

أرسل طلبًا واحدًا لكل عميل بأفضل تفصيل لديك. محكمة السجل ورقم السجل هما الأفضل، لأنهما فريدان. وإن لم يتوفرا لديك، فاستخدم اسم الشركة مع الشكل القانوني والمدينة. يبحث طلبنا النموذجي عن 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 Gunzenhausen'
1{2  "entity_id": "94eb910fef13f94585c48c263fa446d4",3  "name": "Hetzner Online GmbH",4  "status": "ACTIVE",5  "registration": {6    "court": "Ansbach",7    "register_type": "HRB",8    "register_number": "6089"9  },10  "address": {11    "house_number": "25",12    "street": "Industriestraße",13    "postal_code": "91710",14    "city": "Gunzenhausen",15    "county": "Weißenburg-Gunzenhausen",16    "state": "Bayern",17    "country": "DEU",18    "coordinates": {19      "latitude": 49.12483,20      "longitude": 10.7805221    }22  },23  "meta": {24    "request_credit_cost": 5,25    "credits_remaining": 14526  }27}
200 · مثال على استجابة: مطابقة بالاسم والمدينة (مقتطف)

تحقّق من الاستجابة مقابل بياناتك، مثلًا الرمز البريدي أو المدينة في address. ومع الأسماء الشائعة قد تعود شركة تحمل الاسم نفسه بخلاف ذلك.

احفظ الـ entity_id مع عميلك. وتعمل حينها جميع عمليات الجلب اللاحقة والمستندات وSignals والمراقبات على هذا المعرّف.

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

جلب شركات كثيرة

يسمح fetch-organization بـ 60 طلب في الدقيقة. أرسل الطلبات بالتساوي، واحدًا تلو الآخر. وعند HTTP 429 انتظر الثواني المذكورة في Retry-After. وإذا احتجت إلى المزيد، تقدّم Enterprise حدودًا أعلى، انظر الأسعار.

أعطِ كل طلب Idempotency-Key، مثل رقم العميل. إذا كررته بالمفتاح نفسه والمعاملات نفسها خلال 24 ساعة، فلا يكلّف شيئًا.

عند HTTP 408 (استغرق الطلب وقتًا طويلًا جدًا) لا تحتسب الـ API شيئًا، ولا حتى وضع الذكاء الاصطناعي. وعند خطأ بالحالة 500 أو أعلى يُحتسب وضع الذكاء الاصطناعي فقط، إذا اخترته. حاول مرة أخرى لاحقًا بالـ Idempotency-Key نفسه.

يقرأ السكربت customers.csv بالأعمدة id وname وcity وregister. يحتوي العمود register على رقم السجل مع محكمته، مثل Ansbach HRB 6089، أو لا شيء. ويكتب السكربت نسخة مع entity_id ومحكمة السجل ورقم السجل ويعدّ الأرصدة المستهلكة.

سكربت Python 
import csv
import time

import requests

API = "https://handelsregister.ai/api/v1/fetch-organization"
HEADERS = {"x-api-key": "YOUR_API_KEY", "Accept": "application/json"}
PER_MINUTE = 60  # حدّ fetch-organization


def lookup(row):
    # محكمة السجل مع رقم السجل فريدان؛ وإلا فالاسم والمدينة
    q = row["register"] or f'{row["name"]} {row["city"]}'
    headers = {**HEADERS, "Idempotency-Key": f'customer-{row["id"]}'}
    for attempt in range(5):
        response = requests.get(API, params={"q": q}, headers=headers, timeout=120)
        if response.status_code == 429:
            time.sleep(int(response.headers.get("Retry-After", "10")))
        elif response.status_code in (408, 500, 502, 503, 504):
            time.sleep(30 * (attempt + 1))
        else:
            break
    return response


spent = 0
with open("customers.csv", newline="") as source, open("customers_enriched.csv", "w", newline="") as target:
    reader = csv.DictReader(source)
    writer = csv.DictWriter(target, fieldnames=reader.fieldnames + ["entity_id", "register_court", "register_number"])
    writer.writeheader()
    for row in reader:
        response = lookup(row)
        if response.status_code == 402:
            print("الرصيد غير كافٍ، تم إيقاف التشغيل")
            break
        data = response.json()
        spent += data.get("meta", {}).get("request_credit_cost", 0)
        if response.status_code == 200:
            registration = data.get("registration") or {}
            row["entity_id"] = data["entity_id"]
            row["register_court"] = registration.get("court")
            row["register_number"] = f'{registration.get("register_type")} {registration.get("register_number")}'
        writer.writerow(row)
        time.sleep(60 / PER_MINUTE)

print(f"المستهلك: {spent} رصيد")

التشغيل الثاني خلال 24 ساعة لا يكلّف شيئًا. تحمل الاستجابة حينها Idempotency-Status: replayed وrequest_credit_cost بقيمة 0. 

1{2  "entity_id": "94eb910fef13f94585c48c263fa446d4",3  "name": "Hetzner Online GmbH",4  "meta": {5    "request_credit_cost": 0,6    "credits_remaining": 1457  }8}
200 · مثال على استجابة: طلب مكرر بالـ Idempotency-Key نفسه (مقتطف)
يأتي Python SDK مع enrich، وهو إثراء جاهز لملفات CSV وJSON وExcel.
3

متابعة التكاليف

قدّر مسبقًا بقائمة الأسعار: 5 رصيد لكل شركة للبيانات الأساسية، إضافةً إلى سعر كل ميزة. تكلّف البيانات الأساسية مع كل مطابقة. والميزات دون بيانات لا تكلّف شيئًا، لذا كثيرًا ما تكون التكاليف الفعلية أقل. والرسوم الإضافية ليست ميزات: وضع الذكاء الاصطناعي يكلّف حتى دون نتيجة مطابقة، والوقت الفعلي مع كل جلب ناجح.

التكاليف والحدود
ماذا الأرصدة
ملف الشركة مع البيانات الأساسية 5
كل ميزة، فقط عندما تُرجع بيانات من 1 إلى 80
وضع الذكاء الاصطناعي، حتى دون نتيجة مطابقة +20
الوقت الفعلي، لكل جلب مباشر ناجح +10

الحد: 60 طلب في الدقيقة. التكلفة الفعلية لكل طلب موجودة في كل استجابة تحت meta.request_credit_cost.

تكلفة الطلب موجودة في meta.request_credit_cost، والرصيد المتبقي في meta.credits_remaining. اجمع التكاليف أولًا بأول، كما في السكربت أعلاه.

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

يمكنك التحقق من رصيدك واستخدامك في أي وقت مجانًا عبر account.

أخطاء شائعة

  • رقم السجل دون محكمة: إذا كانت بياناتك تقول «HRB 6089» فقط، فلا تجد الـ API أي شركة. أضف محكمة السجل أو استخدم الاسم والمدينة.
  • مفتاح واحد، طلب واحد: الـ Idempotency-Key نفسه مع معاملات مختلفة يُرجع HTTP 422. لطلب متغير استخدم مفتاحًا جديدًا.
  • صيغة المفتاح: يُسمح بما يصل إلى 128 حرفًا من الحروف والأرقام و. _ : -، على أن يبدأ بحرف أو رقم. وتتجاهل الـ API المفتاح بأي صيغة أخرى. ويُنفَّذ الطلب حينها دون هذه الحماية.
  • مهلة الانتظار: مع الوقت الفعلي أو ميزات كثيرة يستغرق الطلب وقتًا أطول. اضبط مهلة الانتظار في عميلك على 120 ثانية على الأقل.

التالي

fetch-organization جميع معاملات ملف الشركة وميزاته وأخطائه. الفوترة الأسعار لكل نقطة نهاية وميزة. الحدود الطلبات في الدقيقة وIdempotency-Key. Python SDK الإثراء باستخدام Python SDK.