Wzbogacaj dane klientów
Uzupełnij listę klientów o dane firm.
Masz listę nazw firm, miejscowości lub numerów rejestru i chcesz uzupełnić ją o urzędowe dane firm. Wystarczy fetch-organization; nie musisz najpierw szukać.
Dopasuj firmy
Wyślij jedno zapytanie na klienta z najlepszą informacją, jaką masz. Najlepsze są sąd rejestrowy i numer rejestru, bo są jednoznaczne. Jeśli ich nie masz, użyj nazwy firmy z formą prawną i miejscowością. Nasze przykładowe zapytanie szuka Hetzner Online GmbH, Ansbach HRB 6089, po nazwie i miejscowości.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: TWOJ_KLUCZ_API" \ --data-urlencode 'q=Hetzner Online GmbH Gunzenhausen'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-organization", headers={"x-api-key": "TWOJ_KLUCZ_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": "TWOJ_KLUCZ_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}
Porównaj odpowiedź ze swoimi danymi, np. kod pocztowy lub miejscowość w address. Przy popularnych nazwach mogłaby inaczej wrócić firma o tej samej nazwie.
Zapisz entity_id przy kliencie. Wszystkie późniejsze pobrania, dokumenty, Signals i monitory działają wtedy na tym identyfikatorze.
ai_search=on-default) stosuj wybiórczo przy nieprecyzyjnych wpisach; kosztuje dodatkowo 20 kredytów, także bez trafienia.
Pobierz wiele firm
fetch-organization pozwala na 60 zapytań na minutę. Wysyłaj zapytania równomiernie, jedno po drugim. Przy HTTP 429 odczekaj sekundy z Retry-After. Jeśli potrzebujesz więcej, Enterprise oferuje wyższe limity, zobacz Ceny.
Daj każdemu zapytaniu Idempotency-Key, np. numer klienta. Jeśli powtórzysz je z tym samym kluczem i tymi samymi parametrami w ciągu 24 godzin, nic nie kosztuje.
Przy HTTP 408 (zapytanie trwało za długo) API nic nie nalicza, nawet trybu AI. Przy błędzie ze statusem 500 lub wyższym naliczany jest tylko tryb AI, jeśli go wybrałeś. Spróbuj ponownie później z tym samym Idempotency-Key.
Skrypt czyta klienci.csv z kolumnami id, name, city i register. Kolumna register zawiera numer rejestru z sądem, np. Ansbach HRB 6089, albo nic. Skrypt zapisuje kopię z entity_id, sądem rejestrowym i numerem rejestru i sumuje zużyte kredyty.
import csv import time import requests API = "https://handelsregister.ai/api/v1/fetch-organization" HEADERS = {"x-api-key": "TWOJ_KLUCZ_API", "Accept": "application/json"} PER_MINUTE = 60 # limit fetch-organization def lookup(row): # Sąd rejestrowy z numerem rejestru jest jednoznaczny, w przeciwnym razie nazwa i miejscowość q = row["register"] or f'{row["name"]} {row["city"]}' headers = {**HEADERS, "Idempotency-Key": f'klient-{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("klienci.csv", newline="") as source, open("klienci_wzbogaceni.csv", "w", newline="") as target: reader = csv.DictReader(source) writer = csv.DictWriter(target, fieldnames=reader.fieldnames + ["entity_id", "sad_rejestrowy", "numer_rejestru"]) writer.writeheader() for row in reader: response = lookup(row) if response.status_code == 402: print("Za mało kredytów, przebieg zatrzymany") 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["sad_rejestrowy"] = registration.get("court") row["numer_rejestru"] = f'{registration.get("register_type")} {registration.get("register_number")}' writer.writerow(row) time.sleep(60 / PER_MINUTE) print(f"Zużyto: {spent} kredytów")
Drugi przebieg w ciągu 24 godzin nic nie kosztuje. Odpowiedź ma wtedy 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, gotowe wzbogacanie plików CSV, JSON i Excel.
Pilnuj kosztów
Oszacuj z góry na podstawie cennika: 5 kredytów za firmę za dane podstawowe plus cena każdego feature. Dane podstawowe kosztują przy każdym trafieniu. Features bez danych nic nie kosztują, więc faktyczne koszty są często niższe. Dopłaty nie są features: tryb AI kosztuje także bez trafienia, tryb czasu rzeczywistego przy każdym udanym pobraniu.
| Co | Kredyty |
|---|---|
| Profil firmy z danymi podstawowymi | 5 |
| Każdy feature, tylko gdy zwraca dane | od 1 do 80 |
| Tryb AI, także bez trafienia | +20 |
| Tryb czasu rzeczywistego, przy każdym udanym pobraniu na żywo | +10 |
Limit: 60 zapytań na minutę.
Ile zapytanie faktycznie kosztowało, znajdziesz w każdej odpowiedzi pod meta.request_credit_cost.
Ile kosztowało zapytanie, stoi w meta.request_credit_cost, pozostałe saldo w meta.credits_remaining. Sumuj koszty na bieżąco, jak w skrypcie powyżej.
Przed każdym zapytaniem API sprawdza, czy twoje saldo pokrywa najwyższą możliwą cenę. Jeśli nie, API odpowiada HTTP 402 i nic nie nalicza. Skrypt wtedy się zatrzymuje.
Saldo i użycie sprawdzisz w każdej chwili bezpłatnie przez account.
Częste pułapki
- Numer rejestru bez sądu: jeśli w twoich danych jest tylko „HRB 6089”, API nie znajdzie firmy. Dodaj sąd rejestrowy albo użyj nazwy i miejscowości.
- Jeden klucz, jedno zapytanie: ten sam
Idempotency-Keyz innymi parametrami zwraca HTTP 422. Dla zmienionego zapytania użyj nowego klucza. - Format klucza: dozwolone do 128 znaków z liter, cyfr i
. _ : -, zaczynając od litery lub cyfry. Klucz w innym formacie API ignoruje. Zapytanie działa wtedy bez tej ochrony. - Timeout: w trybie czasu rzeczywistego lub z wieloma features zapytanie trwa dłużej. Ustaw timeout klienta na co najmniej 120 sekund.