Berig kundedata
Føj virksomhedsdata til din kundeliste.
Du har en liste med virksomhedsnavne, byer eller registernumre og vil føje officielle virksomhedsdata til den. Alt, du skal bruge, er fetch-organization; du behøver ikke søge først.
Match virksomheder
Send én forespørgsel pr. kunde med den bedste oplysning, du har. Registerret og registernummer er bedst, fordi de er entydige. Har du dem ikke, så brug virksomhedens navn med selskabsform og by. Vores eksempelforespørgsel slår Hetzner Online GmbH, Ansbach HRB 6089, op via navn og by.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: DIN_API_NOEGLE" \ --data-urlencode 'q=Hetzner Online GmbH Gunzenhausen'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-organization", headers={"x-api-key": "DIN_API_NOEGLE"}, 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": "DIN_API_NOEGLE" }, }); 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}
Tjek svaret mod dine data, f.eks. postnummer eller by i address. Ved almindelige navne kunne der ellers komme en virksomhed med samme navn tilbage.
Gem entity_id ved din kunde. Alle senere hentninger, dokumenter, Signals og monitors kører så på denne identifikator.
ai_search=on-default) målrettet til uskarpe poster; den koster ekstra 20 kreditter, også uden match.
Hent mange virksomheder
fetch-organization tillader 60 forespørgsler pr. minut. Send forespørgslerne jævnt, én efter én. Ved HTTP 429 venter du de sekunder, der står i Retry-After. Har du brug for mere, tilbyder Enterprise højere grænser, se Priser.
Giv hver forespørgsel en Idempotency-Key, f.eks. kundenummeret. Gentager du den med samme nøgle og samme parametre inden for 24 timer, koster den intet.
Ved HTTP 408 (forespørgslen tog for lang tid) afregner API’et intet, heller ikke AI-tilstand. Ved en fejl med status 500 eller højere afregnes kun AI-tilstand, hvis du har valgt den. Prøv igen senere med den samme Idempotency-Key.
Scriptet læser kunder.csv med kolonnerne id, name, city og register. Kolonnen register indeholder registernummeret med ret, f.eks. Ansbach HRB 6089, eller intet. Scriptet skriver en kopi med entity_id, registerret og registernummer og tæller de brugte kreditter.
import csv import time import requests API = "https://handelsregister.ai/api/v1/fetch-organization" HEADERS = {"x-api-key": "DIN_API_NOEGLE", "Accept": "application/json"} PER_MINUTE = 60 # grænse for fetch-organization def lookup(row): # Registerret plus registernummer er entydigt; ellers navn og by q = row["register"] or f'{row["name"]} {row["city"]}' headers = {**HEADERS, "Idempotency-Key": f'kunde-{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("kunder.csv", newline="") as source, open("kunder_beriget.csv", "w", newline="") as target: reader = csv.DictReader(source) writer = csv.DictWriter(target, fieldnames=reader.fieldnames + ["entity_id", "registerret", "registernummer"]) writer.writeheader() for row in reader: response = lookup(row) if response.status_code == 402: print("Ikke nok kreditter, kørslen er stoppet") 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["registerret"] = registration.get("court") row["registernummer"] = f'{registration.get("register_type")} {registration.get("register_number")}' writer.writerow(row) time.sleep(60 / PER_MINUTE) print(f"Brugt: {spent} kreditter")
En anden kørsel inden for 24 timer koster intet. Svaret har så Idempotency-Status: replayed og 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, en færdig berigelse for CSV-, JSON- og Excel-filer.
Hold øje med omkostningerne
Estimér på forhånd med prislisten: 5 kreditter pr. virksomhed for grunddataene plus prisen for hver feature. Grunddataene koster ved hvert match. Features uden data koster intet, så de faktiske omkostninger er ofte lavere. Tillæggene er ikke features: AI-tilstand koster også uden match, Realtid ved hvert vellykket opslag.
| Hvad | Kreditter |
|---|---|
| Virksomhedsprofil med grunddata | 5 |
| Hver feature, kun når den returnerer data | 1 til 80 |
| AI-tilstand, også uden match | +20 |
| Realtid, for hvert vellykket live-opslag | +10 |
Grænse: 60 forespørgsler pr. minut.
Hvad en forespørgsel faktisk kostede, står i hvert svar under meta.request_credit_cost.
Hvad en forespørgsel kostede, står i meta.request_credit_cost, den resterende saldo i meta.credits_remaining. Læg omkostningerne sammen undervejs, som i scriptet ovenfor.
Før hver forespørgsel tjekker API’et, om din saldo dækker den højest mulige pris. Gør den ikke det, svarer API’et med HTTP 402 og afregner intet. Scriptet stopper så.
Din saldo og dit forbrug kan du når som helst tjekke gratis via account.
Typiske faldgruber
- Registernummer uden ret: Står der kun «HRB 6089» i dine data, finder API’et ingen virksomhed. Tilføj registerretten, eller brug navn og by.
- Én nøgle, én forespørgsel: Den samme
Idempotency-Keymed andre parametre returnerer HTTP 422. Til en ændret forespørgsel bruger du en ny nøgle. - Nøgleformat: Op til 128 tegn af bogstaver, cifre og
. _ : -er tilladt, startende med et bogstav eller ciffer. API’et ignorerer en nøgle i ethvert andet format. Forespørgslen kører så uden denne beskyttelse. - Timeout: Med Realtid eller mange features tager en forespørgsel længere tid. Sæt din klients timeout til mindst 120 sekunder.