Enriquecer dados de clientes
Acrescente dados de empresas à sua lista de clientes.
Você tem uma lista de nomes de empresas, cidades ou números de registro e quer acrescentar dados oficiais de empresas a ela. Basta fetch-organization; você não precisa buscar antes.
Associar empresas
Envie uma requisição por cliente com o melhor dado que você tiver. Tribunal de registro e número de registro são o melhor, porque são únicos. Se você não os tiver, use o nome da empresa com forma jurídica e cidade. Nossa requisição de exemplo busca a Hetzner Online GmbH, Ansbach HRB 6089, por nome e cidade.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: SUA_CHAVE_DE_API" \ --data-urlencode 'q=Hetzner Online GmbH Gunzenhausen'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-organization", headers={"x-api-key": "SUA_CHAVE_DE_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": "SUA_CHAVE_DE_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}
Confira a resposta com os seus dados, por exemplo o código postal ou a cidade em address. Com nomes comuns, poderia vir de outro modo uma empresa homônima.
Guarde o entity_id junto ao seu cliente. Todas as consultas posteriores, documentos, Signals e monitores passam então por esse identificador.
ai_search=on-default) de forma seletiva para entradas imprecisas; ele custa 20 créditos a mais, mesmo sem correspondência.
Obter muitas empresas
fetch-organization permite 60 requisições por minuto. Envie as requisições de forma uniforme, uma após a outra. Com HTTP 429, espere os segundos de Retry-After. Se precisar de mais, o Enterprise oferece limites maiores, veja Preços.
Dê a cada requisição um Idempotency-Key, por exemplo o número do cliente. Se você a repetir com a mesma chave e os mesmos parâmetros em até 24 horas, ela não custa nada.
Com HTTP 408 (a requisição demorou demais), a API não cobra nada, nem o Modo IA. Num erro com status 500 ou superior, só o Modo IA é cobrado, se você o escolheu. Tente de novo mais tarde com o mesmo Idempotency-Key.
O script lê clientes.csv com as colunas id, name, city e register. A coluna register contém o número de registro com o tribunal, como Ansbach HRB 6089, ou nada. O script grava uma cópia com entity_id, tribunal de registro e número de registro e conta os créditos usados.
import csv import time import requests API = "https://handelsregister.ai/api/v1/fetch-organization" HEADERS = {"x-api-key": "SUA_CHAVE_DE_API", "Accept": "application/json"} PER_MINUTE = 60 # limite de fetch-organization def lookup(row): # Tribunal de registro mais número de registro é único; caso contrário, nome e cidade 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_registro", "numero_registro"]) writer.writeheader() for row in reader: response = lookup(row) if response.status_code == 402: print("Créditos insuficientes, execução interrompida") 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_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"Usados: {spent} créditos")
Uma segunda execução em até 24 horas não custa nada. A resposta então traz 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, um enriquecimento pronto para arquivos CSV, JSON e Excel.
Controlar os custos
Estime antes com a lista de preços: 5 créditos por empresa para os dados básicos, mais o preço de cada recurso. Os dados básicos custam a cada correspondência. Recursos sem dados não custam nada, então os custos reais muitas vezes são menores. Os acréscimos não são recursos: o Modo IA custa mesmo sem correspondência, o Tempo real a cada consulta bem-sucedida.
| O quê | Créditos |
|---|---|
| Perfil da empresa com os dados básicos | 5 |
| Cada recurso, só quando retorna dados | 1 a 80 |
| Modo IA, mesmo sem correspondência | +20 |
| Tempo real, a cada consulta ao vivo bem-sucedida | +10 |
Limite: 60 requisições por minuto.
Quanto uma requisição realmente custou está em toda resposta em meta.request_credit_cost.
Quanto uma requisição custou está em meta.request_credit_cost, o saldo restante em meta.credits_remaining. Some os custos à medida que avança, como no script acima.
Antes de cada requisição, a API verifica se o seu saldo cobre o maior preço possível. Se não cobrir, a API responde com HTTP 402 e não cobra nada. O script então para.
Você pode consultar seu saldo e uso a qualquer momento, de graça, por account.
Armadilhas comuns
- Número de registro sem tribunal: se os seus dados só dizem “HRB 6089”, a API não encontra nenhuma empresa. Acrescente o tribunal de registro ou use nome e cidade.
- Uma chave, uma requisição: o mesmo
Idempotency-Keycom parâmetros diferentes retorna HTTP 422. Para uma requisição alterada, use uma nova chave. - Formato da chave: são permitidos até 128 caracteres entre letras, dígitos e
. _ : -, começando com letra ou dígito. A API ignora uma chave em qualquer outro formato. A requisição então roda sem essa proteção. - Timeout: com Tempo real ou muitos recursos, uma requisição demora mais. Configure o timeout do seu cliente para pelo menos 120 segundos.