Arricchire i dati dei clienti
Aggiungi dati aziendali alla tua lista clienti.
Hai una lista di nomi di aziende, città o numeri di registro e vuoi aggiungerle dati aziendali ufficiali. Ti basta fetch-organization; non serve cercare prima.
Abbinare le aziende
Invia una richiesta per cliente con il dato migliore che hai. Tribunale del registro e numero di registro sono i migliori, perché univoci. Se non li hai, usa il nome dell’azienda con forma giuridica e città. La nostra richiesta di esempio cerca Hetzner Online GmbH, Ansbach HRB 6089, per nome e città.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: LA_TUA_CHIAVE_API" \ --data-urlencode 'q=Hetzner Online GmbH Gunzenhausen'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-organization", headers={"x-api-key": "LA_TUA_CHIAVE_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": "LA_TUA_CHIAVE_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}
Confronta la risposta con i tuoi dati, ad esempio il codice postale o la città in address. Con nomi comuni potrebbe altrimenti tornare un’azienda omonima.
Salva l’entity_id presso il tuo cliente. Tutti i recuperi successivi, documenti, Signals e monitor girano poi su questo identificativo.
ai_search=on-default) in modo mirato per le voci imprecise; costa 20 crediti in più, anche senza risultato.
Recuperare molte aziende
fetch-organization consente 60 richieste al minuto. Invia le richieste in modo uniforme, una dopo l’altra. Con HTTP 429 aspetta i secondi indicati in Retry-After. Se ti serve di più, Enterprise offre limiti più alti, vedi Prezzi.
Dai a ogni richiesta un Idempotency-Key, ad esempio il numero cliente. Se la ripeti con la stessa chiave e gli stessi parametri entro 24 ore, non costa nulla.
Con HTTP 408 (la richiesta è durata troppo) l’API non addebita nulla, nemmeno la Modalità AI. Con un errore di stato 500 o superiore viene addebitata solo la Modalità AI, se l’hai scelta. Riprova più tardi con lo stesso Idempotency-Key.
Lo script legge clienti.csv con le colonne id, name, city e register. La colonna register contiene il numero di registro con il suo tribunale, come Ansbach HRB 6089, oppure niente. Lo script scrive una copia con entity_id, tribunale del registro e numero di registro e conta i crediti consumati.
import csv import time import requests API = "https://handelsregister.ai/api/v1/fetch-organization" HEADERS = {"x-api-key": "LA_TUA_CHIAVE_API", "Accept": "application/json"} PER_MINUTE = 60 # limite di fetch-organization def lookup(row): # Tribunale del registro più numero di registro è univoco; altrimenti nome e città q = row["register"] or f'{row["name"]} {row["city"]}' headers = {**HEADERS, "Idempotency-Key": f'cliente-{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("clienti.csv", newline="") as source, open("clienti_arricchiti.csv", "w", newline="") as target: reader = csv.DictReader(source) writer = csv.DictWriter(target, fieldnames=reader.fieldnames + ["entity_id", "tribunale_registro", "numero_registro"]) writer.writeheader() for row in reader: response = lookup(row) if response.status_code == 402: print("Crediti insufficienti, esecuzione interrotta") 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["tribunale_registro"] = registration.get("court") row["numero_registro"] = f'{registration.get("register_type")} {registration.get("register_number")}' writer.writerow(row) time.sleep(60 / PER_MINUTE) print(f"Consumati: {spent} crediti")
Una seconda esecuzione entro 24 ore non costa nulla. La risposta riporta allora Idempotency-Status: replayed e 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 arricchimento pronto per file CSV, JSON ed Excel.
Tenere d’occhio i costi
Stima in anticipo con il listino prezzi: 5 crediti per azienda per i dati di base, più il prezzo di ogni feature. I dati di base costano a ogni abbinamento. Le feature senza dati non costano nulla, quindi i costi effettivi sono spesso più bassi. I supplementi non sono feature: la Modalità AI costa anche senza risultato, Tempo reale a ogni recupero riuscito.
| Cosa | Crediti |
|---|---|
| Profilo aziendale con i dati di base | 5 |
| Ogni feature, solo se restituisce dati | da 1 a 80 |
| Modalità AI, anche senza risultato | +20 |
| Tempo reale, per ogni recupero in diretta riuscito | +10 |
Limite: 60 richieste al minuto.
Quanto è costata davvero una richiesta lo trovi in ogni risposta in meta.request_credit_cost.
Quanto è costata una richiesta è in meta.request_credit_cost, il saldo rimanente in meta.credits_remaining. Somma i costi man mano, come nello script sopra.
Prima di ogni richiesta l’API controlla se il tuo saldo copre il prezzo più alto possibile. Se non lo copre, risponde con HTTP 402 e non addebita nulla. Lo script allora si ferma.
Saldo e consumo li puoi controllare in qualsiasi momento gratuitamente tramite account.
Errori frequenti
- Numero di registro senza tribunale: Se i tuoi dati riportano solo “HRB 6089”, l’API non trova alcuna azienda. Aggiungi il tribunale del registro o usa nome e città.
- Una chiave, una richiesta: Lo stesso
Idempotency-Keycon parametri diversi restituisce HTTP 422. Per una richiesta modificata usa una nuova chiave. - Formato della chiave: Sono ammessi fino a 128 caratteri tra lettere, cifre e
. _ : -, iniziando con una lettera o una cifra. L’API ignora una chiave in qualsiasi altro formato. La richiesta gira allora senza questa protezione. - Timeout: Con Tempo reale o molte feature una richiesta dura di più. Imposta il timeout del tuo client ad almeno 120 secondi.