Rikasta asiakasdataa

Lisää yritystiedot asiakaslistaasi.

Sinulla on lista yritysten nimiä, paikkakuntia tai rekisterinumeroita, ja haluat lisätä niihin virallisia yritystietoja. Tarvitset vain fetch-organizationin; sinun ei tarvitse hakea ensin.

Yhdistä yritykset

Lähetä yksi pyyntö asiakasta kohden parhaalla tiedollasi. Rekisterituomioistuin ja rekisterinumero ovat parhaita, koska ne ovat yksiselitteisiä. Jos sinulla ei ole niitä, käytä toiminimeä yhtiömuotoineen ja paikkakuntaa. Esimerkkipyyntömme hakee yrityksen Hetzner Online GmbH, Ansbach HRB 6089, nimellä ja paikkakunnalla.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: SINUN_API_AVAIMESI" \
  --data-urlencode 'q=Hetzner Online GmbH Gunzenhausen'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "SINUN_API_AVAIMESI"},
    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": "SINUN_API_AVAIMESI" },
});
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}

200 · Esimerkkivastaus: osuma nimelle ja paikkakunnalle (ote)

Tarkista vastaus omaa dataasi vasten, esimerkiksi postinumero tai paikkakunta kentässä address. Yleisillä nimillä voisi muuten palautua samanniminen yritys.

Tallenna entity_id asiakkaasi tietoihin. Kaikki myöhemmät haut, asiakirjat, Signals ja monitorit toimivat silloin tällä tunnisteella.

Jos API ei löydä yritystä, saat vastauksen HTTP 404. Ilman AI-tilaa tämä ei maksa mitään. Merkitse asiakas tarkistettavaksi. Käytä AI-tilaa (ai_search=on-default) valikoiden epätarkkoihin merkintöihin; se maksaa lisäksi 20 krediittiä, myös ilman osumaa.

Hae monta yritystä

fetch-organization sallii 60 pyyntöä minuutissa. Lähetä pyynnöt tasaisesti peräkkäin. Vastauksella HTTP 429 odota headerin Retry-After sekunnit. Jos tarvitset enemmän, Enterprise tarjoaa korkeammat rajat, katso Hinnasto.

Anna jokaiselle pyynnölle Idempotency-Key, esimerkiksi asiakasnumero. Jos toistat sen samalla avaimella ja samoilla parametreilla 24 tunnin sisällä, se ei maksa mitään.

Vastauksella HTTP 408 (pyyntö kesti liian kauan) API ei veloita mitään, ei edes AI-tilaa. Virheellä, jonka tila on 500 tai suurempi, veloitetaan vain AI-tila, jos valitsit sen. Yritä myöhemmin uudelleen samalla Idempotency-Keyllä.

Skripti lukee tiedoston asiakkaat.csv, jossa on sarakkeet id, name, city ja register. Sarakkeessa register on rekisterinumero tuomioistuimineen, kuten Ansbach HRB 6089, tai ei mitään. Skripti kirjoittaa kopion, jossa on entity_id, rekisterituomioistuin ja rekisterinumero, ja laskee käytetyt krediitit.

Python-skripti

import csv
import time

import requests

API = "https://handelsregister.ai/api/v1/fetch-organization"
HEADERS = {"x-api-key": "SINUN_API_AVAIMESI", "Accept": "application/json"}
PER_MINUTE = 60  # fetch-organizationin raja


def lookup(row):
    # Rekisterituomioistuin ja rekisterinumero ovat yksiselitteisiä, muuten nimi ja paikkakunta
    q = row["register"] or f'{row["name"]} {row["city"]}'
    headers = {**HEADERS, "Idempotency-Key": f'asiakas-{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("asiakkaat.csv", newline="") as source, open("asiakkaat_rikastettu.csv", "w", newline="") as target:
    reader = csv.DictReader(source)
    writer = csv.DictWriter(target, fieldnames=reader.fieldnames + ["entity_id", "rekisterituomioistuin", "rekisterinumero"])
    writer.writeheader()
    for row in reader:
        response = lookup(row)
        if response.status_code == 402:
            print("Krediitit eivät riitä, ajo pysäytetty")
            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["rekisterituomioistuin"] = registration.get("court")
            row["rekisterinumero"] = f'{registration.get("register_type")} {registration.get("register_number")}'
        writer.writerow(row)
        time.sleep(60 / PER_MINUTE)

print(f"Käytetty: {spent} krediittiä")

Toinen ajo 24 tunnin sisällä ei maksa mitään. Vastauksessa on silloin Idempotency-Status: replayed ja 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}

200 · Esimerkkivastaus: toistettu pyyntö samalla Idempotency-Keyllä (ote)

Python SDK:n mukana tulee enrich, valmis rikastus CSV-, JSON- ja Excel-tiedostoille.

Pidä kustannukset silmällä

Arvioi etukäteen hinnaston avulla: 5 krediittiä yritystä kohden perustiedoista sekä kunkin ominaisuuden hinta. Perustiedot maksavat jokaisesta osumasta. Ominaisuudet ilman dataa eivät maksa mitään, joten todelliset kustannukset ovat usein pienemmät. Lisämaksut eivät ole ominaisuuksia: AI-tila maksaa myös ilman osumaa, Reaaliaika jokaisesta onnistuneesta hausta.

Kustannukset ja rajat
Mitä	Krediitit
Yritysprofiili perustiedoilla	5
Jokainen ominaisuus, vain kun se palauttaa dataa	1–80
AI-tila, myös ilman osumaa	+20
Reaaliaika, jokaisesta onnistuneesta suorasta hausta	+10

Raja: 60 pyyntöä minuutissa. Pyynnön todellinen hinta on jokaisessa vastauksessa kentässä meta.request_credit_cost.

Mitä pyyntö maksoi, on kentässä meta.request_credit_cost, jäljellä oleva saldo kentässä meta.credits_remaining. Laske kustannukset yhteen ajon aikana, kuten yllä olevassa skriptissä.

Ennen jokaista pyyntöä API tarkistaa, riittääkö saldosi korkeimpaan mahdolliseen hintaan. Jos ei riitä, API vastaa HTTP 402 eikä veloita mitään. Skripti pysähtyy silloin.

Saldosi ja käyttösi voit tarkistaa milloin tahansa maksutta päätepisteen account kautta.

Yleiset sudenkuopat

Rekisterinumero ilman tuomioistuinta: Jos datassasi lukee vain ”HRB 6089”, API ei löydä yritystä. Lisää rekisterituomioistuin tai käytä nimeä ja paikkakuntaa.
Yksi avain, yksi pyyntö: Sama Idempotency-Key eri parametreilla palauttaa HTTP 422. Muutetulle pyynnölle käytä uutta avainta.
Avaimen muoto: Sallittu on enintään 128 merkkiä kirjaimista, numeroista ja merkeistä . _ : -, alkaen kirjaimella tai numerolla. API ohittaa muun muotoisen avaimen. Pyyntö suoritetaan silloin ilman tätä suojaa.
Aikakatkaisu: Reaaliajalla tai monella ominaisuudella pyyntö kestää kauemmin. Aseta asiakasohjelmasi aikakatkaisuksi vähintään 120 sekuntia.

Seuraavaksi

fetch-organization Yritysprofiilin kaikki parametrit, ominaisuudet ja virheet. Laskutus Hinnat päätepisteittäin ja ominaisuuksittain. Rajat Pyynnöt minuutissa ja Idempotency-Key. Python SDK Rikastaminen Python SDK:lla.