Îmbogățește datele clienților
Adaugă date despre companii în lista ta de clienți.
Ai o listă de denumiri de companii, localități sau numere de registru și vrei să adaugi date oficiale despre companii. Ai nevoie doar de fetch-organization; nu trebuie să cauți înainte.
Potrivește companiile
Trimite câte o cerere per client cu cea mai bună informație pe care o ai. Instanța de registru și numărul de registru sunt cele mai bune, pentru că sunt unice. Dacă nu le ai, folosește denumirea companiei cu forma juridică și localitatea. Cererea noastră exemplu caută Hetzner Online GmbH, Ansbach HRB 6089, după nume și localitate.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: CHEIA_TA_API" \ --data-urlencode 'q=Hetzner Online GmbH Gunzenhausen'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-organization", headers={"x-api-key": "CHEIA_TA_API"}, params={ "q": "Hetzner Online GmbH Gunzenhausen", }, ) data = response.json()
const url = new URL("https://handelsregister.ai/api/v1/fetch-organization"); url.searchParams.append("q", "Hetzner Online GmbH Gunzenhausen"); const response = await fetch(url, { headers: { "x-api-key": "CHEIA_TA_API" }, }); const data = await response.json();
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}
Compară răspunsul cu datele tale, de exemplu codul poștal sau localitatea din address. La nume frecvente ar putea veni altfel înapoi o companie cu același nume.
Salvează entity_id la clientul tău. Toate preluările ulterioare, documentele, Signals și monitoarele rulează apoi pe acest identificator.
ai_search=on-default) țintit pentru intrări vagi; costă în plus 20 de credite, chiar și fără potrivire.
Preia multe companii
fetch-organization permite 60 cereri pe minut. Trimite cererile uniform, una după alta. La HTTP 429, așteaptă secundele din Retry-After. Dacă ai nevoie de mai mult, Enterprise oferă limite mai mari, vezi Prețuri.
Dă fiecărei cereri un Idempotency-Key, de exemplu numărul clientului. Dacă o repeți cu aceeași cheie și aceiași parametri în 24 de ore, nu costă nimic.
La HTTP 408 (cererea a durat prea mult), API-ul nu taxează nimic, nici măcar Modul AI. La o eroare cu status 500 sau mai mare, se taxează doar Modul AI, dacă l-ai ales. Încearcă din nou mai târziu cu același Idempotency-Key.
Scriptul citește customers.csv cu coloanele id, name, city și register. Coloana register conține numărul de registru cu instanța sa, de ex. Ansbach HRB 6089, sau nimic. Scriptul scrie o copie cu entity_id, instanța de registru și numărul de registru și numără creditele consumate.
import csv import time import requests API = "https://handelsregister.ai/api/v1/fetch-organization" HEADERS = {"x-api-key": "CHEIA_TA_API", "Accept": "application/json"} PER_MINUTE = 60 # limita lui fetch-organization def lookup(row): # Instanța de registru plus numărul de registru sunt unice; altfel numele și localitatea 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("Credite insuficiente, rularea s-a oprit") 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"Consumat: {spent} credite")
O a doua rulare în 24 de ore nu costă nimic. Răspunsul poartă atunci Idempotency-Status: replayed și 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}
enrich, o îmbogățire gata făcută pentru fișiere CSV, JSON și Excel.
Ține costurile sub control
Estimează dinainte cu lista de prețuri: 5 credite per companie pentru datele de bază, plus prețul fiecărei funcții. Datele de bază costă la fiecare potrivire. Funcțiile fără date nu costă nimic, deci costurile reale sunt adesea mai mici. Suprataxele nu sunt funcții: Modul AI costă chiar și fără potrivire, Timp real la fiecare preluare reușită.
| Ce | Credite |
|---|---|
| Profil companie cu datele de bază | 5 |
| Fiecare funcție, doar când returnează date | 1 până la 80 |
| Modul AI, chiar și fără potrivire | +20 |
| Timp real, pentru fiecare preluare live reușită | +10 |
Limită: 60 cereri pe minut.
Cât a costat de fapt o cerere găsești în fiecare răspuns la meta.request_credit_cost.
Cât a costat o cerere se află în meta.request_credit_cost, soldul rămas în meta.credits_remaining. Adună costurile pe parcurs, ca în scriptul de mai sus.
Înainte de fiecare cerere, API-ul verifică dacă soldul tău acoperă prețul maxim posibil. Dacă nu, API-ul răspunde cu HTTP 402 și nu taxează nimic. Scriptul se oprește atunci.
Soldul și consumul le poți verifica oricând gratuit prin account.
Capcane frecvente
- Număr de registru fără instanță: Dacă în datele tale scrie doar „HRB 6089”, API-ul nu găsește nicio companie. Adaugă instanța de registru sau folosește numele și localitatea.
- O cheie, o cerere: Același
Idempotency-Keycu alți parametri returnează HTTP 422. Pentru o cerere modificată folosește o cheie nouă. - Formatul cheii: Sunt permise până la 128 de caractere din litere, cifre și
. _ : -, începând cu o literă sau o cifră. API-ul ignoră o cheie în orice alt format. Cererea rulează atunci fără această protecție. - Timeout: Cu Timp real sau multe funcții, o cerere durează mai mult. Setează timeoutul clientului la cel puțin 120 de secunde.