Ügyféladatok dúsítása
Egészítsd ki az ügyféllistádat cégadatokkal.
Van egy listád cégnevekkel, városokkal vagy cégjegyzékszámokkal, és hivatalos cégadatokkal szeretnéd kiegészíteni. Csak a fetch-organization kell hozzá; előtte nem kell keresned.
Cégek párosítása
Ügyfelenként küldj egy kérést a legjobb rendelkezésre álló adattal. A cégbíróság és a cégjegyzékszám a legjobb, mert egyediek. Ha ezek nincsenek meg, használd a cégnevet jogi formával és várossal. A példakérésünk a Hetzner Online GmbH-t (Ansbach HRB 6089) név és város alapján keresi.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: AZ_API_KULCSOD" \ --data-urlencode 'q=Hetzner Online GmbH Gunzenhausen'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-organization", headers={"x-api-key": "AZ_API_KULCSOD"}, 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": "AZ_API_KULCSOD" }, }); 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}
Vesd össze a választ a saját adataiddal, például az address irányítószámát vagy városát. Gyakori neveknél különben egy azonos nevű cég is visszajöhet.
Mentsd el az entity_id-t az ügyfeleddel együtt. Minden későbbi lekérés, dokumentum, Signals-jelzés és monitor ezután ezzel az azonosítóval működik.
ai_search=on-default) célzottan használd a pontatlan bejegyzésekhez; plusz 20 kredit kerül, találat nélkül is.
Sok cég lekérése
A fetch-organization limitje percenként 60 kérés. Küldd a kéréseket egyenletesen, egymás után. HTTP 429 esetén várj annyi másodpercet, amennyit a Retry-After megad. Ha többre van szükséged, az Enterprise magasabb limiteket kínál, lásd Árak.
Adj minden kérésnek egy Idempotency-Key-t, például az ügyfélszámot. Ha 24 órán belül ugyanazzal a kulccsal és ugyanazokkal a paraméterekkel megismétled, nem kerül semmibe.
HTTP 408 esetén (a kérés túl sokáig tartott) az API semmit nem számol fel, az AI módot sem. 500-as vagy magasabb státuszú hibánál csak az AI módot számoljuk fel, ha kiválasztottad. Próbáld újra később ugyanazzal az Idempotency-Key-jel.
A szkript az ugyfelek.csv fájlt olvassa be az id, name, city és register oszlopokkal. A register oszlopban a cégjegyzékszám áll a bírósággal, például Ansbach HRB 6089, vagy semmi. A szkript egy másolatot ír entity_id-val, cégbírósággal és cégjegyzékszámmal, és összeszámolja a felhasznált krediteket.
import csv import time import requests API = "https://handelsregister.ai/api/v1/fetch-organization" HEADERS = {"x-api-key": "AZ_API_KULCSOD", "Accept": "application/json"} PER_MINUTE = 60 # a fetch-organization limitje def lookup(row): # A cégbíróság és a cégjegyzékszám együtt egyedi, különben név és város q = row["register"] or f'{row["name"]} {row["city"]}' headers = {**HEADERS, "Idempotency-Key": f'ugyfel-{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("ugyfelek.csv", newline="") as source, open("ugyfelek_bovitett.csv", "w", newline="") as target: reader = csv.DictReader(source) writer = csv.DictWriter(target, fieldnames=reader.fieldnames + ["entity_id", "cegbirosag", "cegjegyzekszam"]) writer.writeheader() for row in reader: response = lookup(row) if response.status_code == 402: print("Nincs elég kredit, a futás leállt") 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["cegbirosag"] = registration.get("court") row["cegjegyzekszam"] = f'{registration.get("register_type")} {registration.get("register_number")}' writer.writerow(row) time.sleep(60 / PER_MINUTE) print(f"Felhasználva: {spent} kredit")
Egy második futás 24 órán belül nem kerül semmibe. A válasz ilyenkor Idempotency-Status: replayed headert és 0 értékű request_credit_cost mezőt tartalmaz.
1{2 "entity_id": "94eb910fef13f94585c48c263fa446d4",3 "name": "Hetzner Online GmbH",4 "meta": {5 "request_credit_cost": 0,6 "credits_remaining": 1457 }8}
enrich funkciót, egy kész adatdúsítást CSV-, JSON- és Excel-fájlokhoz.
A költségek szemmel tartása
Becsülj előre az árlistával: cégenként 5 kredit az alapadatokért, plusz az egyes funkciók ára. Az alapadatok minden találatnál kerülnek valamibe. Az adat nélküli funkciók ingyenesek, így a tényleges költség gyakran alacsonyabb. A felárak nem funkciók: az AI mód találat nélkül is kerül valamibe, a valós idejű mód minden sikeres lekérésnél.
| Mi | Kredit |
|---|---|
| Cégprofil az alapadatokkal | 5 |
| Minden funkció, csak ha ad vissza adatot | 1–80 |
| AI mód, találat nélkül is | +20 |
| Valós idejű mód, minden sikeres élő lekérésnél | +10 |
Limit: percenként 60 kérés.
Hogy egy kérés ténylegesen mennyibe került, azt minden válasz tartalmazza a meta.request_credit_cost alatt.
Hogy egy kérés mennyibe került, az a meta.request_credit_cost, a megmaradt egyenleg a meta.credits_remaining mezőben van. Összesítsd a költségeket menet közben, ahogy a fenti szkript is teszi.
Minden kérés előtt az API ellenőrzi, hogy az egyenleged fedezi-e a lehető legmagasabb árat. Ha nem, HTTP 402-vel válaszol, és semmit nem számol fel. A szkript ekkor leáll.
Az egyenlegedet és a felhasználásodat bármikor ingyen ellenőrizheted az account végponton.
Gyakori buktatók
- Cégjegyzékszám bíróság nélkül: ha az adataidban csak „HRB 6089” áll, az API nem talál céget. Add hozzá a cégbíróságot, vagy használj nevet és várost.
- Egy kulcs, egy kérés: ugyanaz az
Idempotency-Keymás paraméterekkel HTTP 422-t ad. Módosított kéréshez használj új kulcsot. - Kulcsformátum: legfeljebb 128 karakter engedélyezett betűkből, számjegyekből és a
. _ : -jelekből, betűvel vagy számjeggyel kezdve. Más formátumú kulcsot az API figyelmen kívül hagy. A kérés ilyenkor e védelem nélkül fut. - Időkorlát: valós idejű móddal vagy sok funkcióval egy kérés tovább tart. Állítsd a kliensed időkorlátját legalább 120 másodpercre.