Obohatit zákaznická data
Doplň data o firmách do svého seznamu zákazníků.
Máš seznam názvů firem, měst nebo rejstříkových čísel a chceš k nim doplnit úřední data o firmách. Stačí ti fetch-organization; předem hledat nemusíš.
Přiřadit firmy
Pošli jeden požadavek na zákazníka s nejlepším údajem, který máš. Nejlepší je rejstříkový soud a rejstříkové číslo, protože jsou jednoznačné. Pokud je nemáš, použij název firmy s právní formou a městem. Náš ukázkový požadavek hledá Hetzner Online GmbH, Ansbach HRB 6089, podle názvu a města.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: TVUJ_API_KLIC" \ --data-urlencode 'q=Hetzner Online GmbH Gunzenhausen'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-organization", headers={"x-api-key": "TVUJ_API_KLIC"}, 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": "TVUJ_API_KLIC" }, }); 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}
Porovnej odpověď se svými daty, například PSČ nebo město v address. U častých názvů by se jinak mohla vrátit firma se stejným názvem.
Ulož si entity_id u svého zákazníka. Všechna pozdější načtení, dokumenty, Signals a monitory pak běží přes tento identifikátor.
ai_search=on-default) používej cíleně u nepřesných záznamů; stojí 20 kreditů navíc, i bez shody.
Načíst mnoho firem
fetch-organization povoluje 60 požadavků za minutu. Posílej požadavky rovnoměrně, jeden po druhém. Při HTTP 429 počkej počet sekund z Retry-After. Pokud potřebuješ víc, Enterprise nabízí vyšší limity, viz Ceník.
Dej každému požadavku Idempotency-Key, například číslo zákazníka. Pokud ho zopakuješ se stejným klíčem a stejnými parametry do 24 hodin, nestojí nic.
Při HTTP 408 (požadavek trval příliš dlouho) API nic neúčtuje, ani AI režim. Při chybě se stavem 500 nebo vyšším se účtuje jen AI režim, pokud jsi ho zvolil. Zkus to později znovu se stejným Idempotency-Key.
Skript čte zakaznici.csv se sloupci id, name, city a register. Sloupec register obsahuje rejstříkové číslo se soudem, například Ansbach HRB 6089, nebo nic. Skript zapíše kopii s entity_id, rejstříkovým soudem a rejstříkovým číslem a sečte spotřebované kredity.
import csv import time import requests API = "https://handelsregister.ai/api/v1/fetch-organization" HEADERS = {"x-api-key": "TVUJ_API_KLIC", "Accept": "application/json"} PER_MINUTE = 60 # limit endpointu fetch-organization def lookup(row): # Rejstříkový soud plus rejstříkové číslo je jednoznačné; jinak název a město q = row["register"] or f'{row["name"]} {row["city"]}' headers = {**HEADERS, "Idempotency-Key": f'zakaznik-{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("zakaznici.csv", newline="") as source, open("zakaznici_obohaceni.csv", "w", newline="") as target: reader = csv.DictReader(source) writer = csv.DictWriter(target, fieldnames=reader.fieldnames + ["entity_id", "rejstrikovy_soud", "rejstrikove_cislo"]) writer.writeheader() for row in reader: response = lookup(row) if response.status_code == 402: print("Nedostatek kreditů, běh zastaven") 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["rejstrikovy_soud"] = registration.get("court") row["rejstrikove_cislo"] = f'{registration.get("register_type")} {registration.get("register_number")}' writer.writerow(row) time.sleep(60 / PER_MINUTE) print(f"Spotřebováno: {spent} kreditů")
Druhý běh do 24 hodin nestojí nic. Odpověď pak nese Idempotency-Status: replayed a 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, hotové obohacování pro soubory CSV, JSON a Excel.
Hlídat náklady
Odhadni předem podle ceníku: 5 kreditů za firmu za základní údaje plus cena každé funkce. Základní údaje stojí při každé shodě. Funkce bez dat nestojí nic, proto jsou skutečné náklady často nižší. Příplatky nejsou funkce: AI režim stojí i bez shody, režim v reálném čase při každém úspěšném načtení.
| Co | Kredity |
|---|---|
| Profil firmy se základními údaji | 5 |
| Každá funkce, jen když vrátí data | 1 až 80 |
| AI režim, i bez nalezené shody | +20 |
| Režim v reálném čase, za každé úspěšné živé načtení | +10 |
Limit: 60 požadavků za minutu.
Kolik požadavek skutečně stál, najdeš v každé odpovědi v meta.request_credit_cost.
Kolik požadavek stál, je v meta.request_credit_cost, zbývající zůstatek v meta.credits_remaining. Sčítej náklady průběžně, jako ve skriptu výše.
Před každým požadavkem API zkontroluje, zda tvůj zůstatek pokryje nejvyšší možnou cenu. Pokud ne, API odpoví HTTP 402 a nic neúčtuje. Skript se pak zastaví.
Zůstatek a využití si můžeš kdykoli zdarma zkontrolovat přes account.
Časté chyby
- Rejstříkové číslo bez soudu: Pokud tvoje data obsahují jen „HRB 6089“, API žádnou firmu nenajde. Doplň rejstříkový soud nebo použij název a město.
- Jeden klíč, jeden požadavek: Stejný
Idempotency-Keys jinými parametry vrátí HTTP 422. Pro změněný požadavek použij nový klíč. - Formát klíče: Povoleno je až 128 znaků z písmen, číslic a
. _ : -, začínajících písmenem nebo číslicí. Klíč v jiném formátu API ignoruje. Požadavek pak proběhne bez této ochrany. - Časový limit: V režimu v reálném čase nebo s mnoha funkcemi trvá požadavek déle. Nastav časový limit svého klienta alespoň na 120 sekund.