Enrichir des données clients
Ajouter des données d’entreprise à ta liste de clients.
Tu as une liste de noms d’entreprises, de villes ou de numéros de registre et veux y ajouter des données d’entreprise officielles. fetch-organization suffit ; une recherche préalable n’est pas nécessaire.
Associer les entreprises
Envoie une requête par client avec la meilleure information dont tu disposes. Le tribunal du registre et le numéro de registre sont l’idéal, car ils sont uniques. Si tu ne les as pas, utilise le nom de l’entreprise avec forme juridique et ville. Notre requête d’exemple recherche Hetzner Online GmbH, Ansbach HRB 6089, par nom et ville.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: TA_CLE_API" \ --data-urlencode 'q=Hetzner Online GmbH Gunzenhausen'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-organization", headers={"x-api-key": "TA_CLE_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": "TA_CLE_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}
Compare la réponse avec tes données, par exemple le code postal ou la ville dans address. Avec des noms courants, une entreprise homonyme pourrait sinon être renvoyée.
Enregistre l’entity_id avec ton client. Toutes les récupérations ultérieures, documents, Signals et moniteurs reposent ensuite sur cet identifiant.
ai_search=on-default) de façon ciblée pour les entrées approximatives ; il coûte 20 crédits en plus, même sans correspondance.
Récupérer de nombreuses entreprises
fetch-organization autorise 60 requêtes par minute. Envoie les requêtes de façon régulière, l’une après l’autre. En cas de HTTP 429, attends les secondes indiquées dans Retry-After. S’il t’en faut davantage, Enterprise offre des limites plus élevées, voir Tarifs.
Donne à chaque requête une Idempotency-Key, par exemple le numéro client. Si tu la répètes avec la même clé et les mêmes paramètres dans les 24 heures, elle ne coûte rien.
En cas de HTTP 408 (la requête a duré trop longtemps), l’API ne facture rien, pas même le mode IA. En cas d’erreur avec un statut 500 ou plus, seul le mode IA est facturé, si tu l’as choisi. Réessaie plus tard avec la même Idempotency-Key.
Le script lit clients.csv avec les colonnes id, name, city et register. La colonne register contient le numéro de registre avec son tribunal, comme Ansbach HRB 6089, ou rien. Le script écrit une copie avec entity_id, tribunal du registre et numéro de registre et compte les crédits consommés.
import csv import time import requests API = "https://handelsregister.ai/api/v1/fetch-organization" HEADERS = {"x-api-key": "TA_CLE_API", "Accept": "application/json"} PER_MINUTE = 60 # limite de fetch-organization def lookup(row): # Tribunal du registre plus numéro de registre est unique ; sinon nom et ville q = row["register"] or f'{row["name"]} {row["city"]}' headers = {**HEADERS, "Idempotency-Key": f'client-{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("clients.csv", newline="") as source, open("clients_enrichis.csv", "w", newline="") as target: reader = csv.DictReader(source) writer = csv.DictWriter(target, fieldnames=reader.fieldnames + ["entity_id", "tribunal_registre", "numero_registre"]) writer.writeheader() for row in reader: response = lookup(row) if response.status_code == 402: print("Pas assez de crédits, exécution arrêtée") 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["tribunal_registre"] = registration.get("court") row["numero_registre"] = f'{registration.get("register_type")} {registration.get("register_number")}' writer.writerow(row) time.sleep(60 / PER_MINUTE) print(f"Consommé : {spent} crédits")
Une deuxième exécution dans les 24 heures ne coûte rien. La réponse porte alors Idempotency-Status: replayed et 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, un enrichissement prêt à l’emploi pour les fichiers CSV, JSON et Excel.
Garder les coûts à l’œil
Estime à l’avance avec la liste de prix : 5 crédits par entreprise pour les données de base, plus le prix de chaque fonctionnalité. Les données de base sont facturées à chaque correspondance. Les fonctionnalités sans données ne coûtent rien, les coûts réels sont donc souvent plus bas. Les suppléments ne sont pas des fonctionnalités : le mode IA coûte même sans correspondance, le mode temps réel à chaque récupération réussie.
| Quoi | Crédits |
|---|---|
| Profil d’entreprise avec les données de base | 5 |
| Chaque fonctionnalité, uniquement si elle renvoie des données | 1 à 80 |
| Mode IA, même sans correspondance | +20 |
| Mode temps réel, pour chaque récupération en direct réussie | +10 |
Limite : 60 requêtes par minute.
Le coût réel d’une requête figure dans chaque réponse sous meta.request_credit_cost.
Ce qu’une requête a coûté figure dans meta.request_credit_cost, le solde restant dans meta.credits_remaining. Additionne les coûts au fur et à mesure, comme dans le script ci-dessus.
Avant chaque requête, l’API vérifie si ton solde couvre le prix le plus élevé possible. Sinon, l’API répond HTTP 402 et ne facture rien. Le script s’arrête alors.
Tu peux consulter ton solde et ta consommation à tout moment, gratuitement, via account.
Pièges fréquents
- Numéro de registre sans tribunal : si tes données indiquent seulement « HRB 6089 », l’API ne trouve aucune entreprise. Ajoute le tribunal du registre ou utilise nom et ville.
- Une clé, une requête : la même
Idempotency-Keyavec des paramètres différents renvoie HTTP 422. Pour une requête modifiée, utilise une nouvelle clé. - Format de la clé : jusqu’à 128 caractères parmi lettres, chiffres et
. _ : -sont autorisés, en commençant par une lettre ou un chiffre. L’API ignore une clé dans tout autre format. La requête s’exécute alors sans cette protection. - Délai d’attente : avec le mode temps réel ou de nombreuses fonctionnalités, une requête dure plus longtemps. Règle le délai d’attente de ton client sur au moins 120 secondes.