Enriquecer datos de clientes
Añade datos de empresa a tu lista de clientes.
Tienes una lista de nombres de empresa, ciudades o números de registro y quieres añadirle datos oficiales de empresa. Solo necesitas fetch-organization; no hace falta buscar antes.
Asignar empresas
Envía una solicitud por cliente con el mejor dato que tengas. Tribunal registral y número de registro son lo mejor, porque son únicos. Si no los tienes, usa el nombre de la empresa con forma jurídica y ciudad. Nuestra solicitud de ejemplo busca Hetzner Online GmbH, Ansbach HRB 6089, por nombre y ciudad.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: TU_CLAVE_API" \ --data-urlencode 'q=Hetzner Online GmbH Gunzenhausen'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-organization", headers={"x-api-key": "TU_CLAVE_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": "TU_CLAVE_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}
Compara la respuesta con tus datos, por ejemplo el código postal o la ciudad en address. Con nombres frecuentes podría devolverse si no una empresa homónima.
Guarda la entity_id junto a tu cliente. Todas las consultas posteriores, documentos, Signals y monitores funcionan entonces con este identificador.
ai_search=on-default) de forma selectiva para entradas imprecisas; cuesta 20 créditos adicionales, incluso sin coincidencia.
Obtener muchas empresas
fetch-organization permite 60 solicitudes por minuto. Envía las solicitudes de forma uniforme, una tras otra. Con HTTP 429, espera los segundos de Retry-After. Si necesitas más, Enterprise ofrece límites más altos, consulta Precios.
Da a cada solicitud un Idempotency-Key, por ejemplo el número de cliente. Si la repites con la misma clave y los mismos parámetros en 24 horas, no cuesta nada.
Con HTTP 408 (la solicitud tardó demasiado), la API no cobra nada, ni siquiera el modo IA. Con un error de estado 500 o superior, solo se cobra el modo IA, si lo elegiste. Vuelve a intentarlo más tarde con el mismo Idempotency-Key.
El script lee clientes.csv con las columnas id, name, city y register. La columna register contiene el número de registro con su tribunal, como Ansbach HRB 6089, o nada. El script escribe una copia con entity_id, tribunal registral y número de registro y cuenta los créditos consumidos.
import csv import time import requests API = "https://handelsregister.ai/api/v1/fetch-organization" HEADERS = {"x-api-key": "TU_CLAVE_API", "Accept": "application/json"} PER_MINUTE = 60 # límite de fetch-organization def lookup(row): # Tribunal registral más número de registro es único; si no, nombre y ciudad 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("clientes.csv", newline="") as source, open("clientes_enriquecidos.csv", "w", newline="") as target: reader = csv.DictReader(source) writer = csv.DictWriter(target, fieldnames=reader.fieldnames + ["entity_id", "tribunal_registral", "numero_registro"]) writer.writeheader() for row in reader: response = lookup(row) if response.status_code == 402: print("Créditos insuficientes, ejecución detenida") 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_registral"] = 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"Consumidos: {spent} créditos")
Una segunda ejecución en 24 horas no cuesta nada. La respuesta lleva entonces Idempotency-Status: replayed y 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 enriquecimiento listo para archivos CSV, JSON y Excel.
Controlar los costes
Estima de antemano con la lista de precios: 5 créditos por empresa para los datos básicos, más el precio de cada función. Los datos básicos cuestan con cada coincidencia. Las funciones sin datos no cuestan nada, así que los costes reales suelen ser menores. Los recargos no son funciones: el modo IA cuesta incluso sin coincidencia, Tiempo real con cada consulta correcta.
| Qué | Créditos |
|---|---|
| Perfil de empresa con los datos básicos | 5 |
| Cada función, solo si devuelve datos | 1 a 80 |
| Modo IA, incluso sin coincidencia | +20 |
| Tiempo real, por cada consulta en directo correcta | +10 |
Límite: 60 solicitudes por minuto.
Lo que costó realmente una solicitud aparece en cada respuesta en meta.request_credit_cost.
Lo que costó una solicitud está en meta.request_credit_cost, el saldo restante en meta.credits_remaining. Suma los costes sobre la marcha, como en el script de arriba.
Antes de cada solicitud, la API comprueba si tu saldo cubre el precio más alto posible. Si no, responde con HTTP 402 y no cobra nada. El script se detiene entonces.
Puedes consultar tu saldo y consumo en cualquier momento, gratis, mediante account.
Errores frecuentes
- Número de registro sin tribunal: Si tus datos solo dicen “HRB 6089”, la API no encuentra ninguna empresa. Añade el tribunal registral o usa nombre y ciudad.
- Una clave, una solicitud: El mismo
Idempotency-Keycon parámetros distintos devuelve HTTP 422. Para una solicitud modificada, usa una clave nueva. - Formato de la clave: Se permiten hasta 128 caracteres de letras, dígitos y
. _ : -, empezando por una letra o un dígito. La API ignora una clave con cualquier otro formato. La solicitud se ejecuta entonces sin esta protección. - Timeout: Con Tiempo real o muchas funciones, una solicitud tarda más. Configura el timeout de tu cliente en al menos 120 segundos.