고객 데이터 보강
고객 목록에 회사 데이터를 더하세요.
회사명, 도시 또는 등기 번호 목록이 있고 여기에 공식 회사 데이터를 더하고 싶어요. fetch-organization만 있으면 되고, 먼저 검색할 필요가 없어요.
회사 매칭
고객마다 가진 정보 중 가장 좋은 것으로 요청을 하나씩 보내세요. 등기 법원과 등기 번호는 고유하므로 가장 좋아요. 없다면 법적 형태와 도시를 포함한 회사명을 쓰세요. 예시 요청은 이름과 도시로 Hetzner Online GmbH, Ansbach HRB 6089를 조회해요.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode 'q=Hetzner Online GmbH Gunzenhausen'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-organization", headers={"x-api-key": "YOUR_API_KEY"}, 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": "YOUR_API_KEY" }, }); 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}
응답을 내 데이터와 대조하세요. 예: address의 우편번호나 도시. 흔한 이름이면 같은 이름의 다른 회사가 올 수도 있어요.
entity_id를 고객과 함께 저장하세요. 이후 모든 조회, 문서, Signals, 모니터가 이 식별자로 동작해요.
ai_search=on-default)를 쓰세요. 일치 결과가 없어도 20 크레딧가 추가로 들어요.
여러 회사 가져오기
fetch-organization은 분당 60 요청을 허용해요. 요청을 고르게, 차례로 보내세요. HTTP 429가 오면 Retry-After의 초만큼 기다리세요. 더 필요하면 Enterprise가 더 높은 한도를 제공해요. 가격을 참고하세요.
각 요청에 Idempotency-Key를 주세요. 예: 고객 번호. 24시간 안에 같은 키와 같은 파라미터로 반복하면 비용이 들지 않아요.
HTTP 408(요청이 너무 오래 걸림)에서는 AI 모드를 포함해 아무것도 과금하지 않아요. 상태 500 이상의 오류에서는 선택한 경우 AI 모드만 과금돼요. 같은 Idempotency-Key로 나중에 다시 시도하세요.
스크립트는 id, name, city, register 열이 있는 customers.csv를 읽어요. register 열에는 Ansbach HRB 6089처럼 법원이 포함된 등기 번호가 있거나 비어 있어요. 스크립트는 entity_id, 등기 법원, 등기 번호가 추가된 사본을 쓰고 사용한 크레딧을 세요.
import csv import time import requests API = "https://handelsregister.ai/api/v1/fetch-organization" HEADERS = {"x-api-key": "YOUR_API_KEY", "Accept": "application/json"} PER_MINUTE = 60 # fetch-organization의 한도 def lookup(row): # 등기 법원과 등기 번호가 함께 있으면 고유, 없으면 이름과 도시 q = row["register"] or f'{row["name"]} {row["city"]}' headers = {**HEADERS, "Idempotency-Key": f'customer-{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("customers.csv", newline="") as source, open("customers_enriched.csv", "w", newline="") as target: reader = csv.DictReader(source) writer = csv.DictWriter(target, fieldnames=reader.fieldnames + ["entity_id", "register_court", "register_number"]) writer.writeheader() for row in reader: response = lookup(row) if response.status_code == 402: print("크레딧이 부족하여 실행을 중단했어요") 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["register_court"] = registration.get("court") row["register_number"] = f'{registration.get("register_type")} {registration.get("register_number")}' writer.writerow(row) time.sleep(60 / PER_MINUTE) print(f"사용: {spent} 크레딧")
24시간 안의 두 번째 실행은 비용이 들지 않아요. 이때 응답에는 Idempotency-Status: replayed와 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가 있어요.
비용 관리
가격표로 미리 추산하세요: 기본 데이터는 회사당 5 크레딧, 여기에 각 기능의 가격. 기본 데이터는 매칭될 때마다 과금돼요. 데이터가 없는 기능은 무료이므로 실제 비용은 대개 더 낮아요. 추가 요금은 기능이 아니에요: AI 모드는 일치 결과가 없어도, 실시간 모드는 조회가 성공할 때마다 과금돼요.
| 항목 | 크레딧 |
|---|---|
| 기본 데이터가 포함된 회사 프로필 | 5 |
| 각 기능, 데이터를 반환할 때만 | 1~80 |
| AI 모드, 일치 결과가 없어도 | +20 |
| 실시간 모드, 실시간 조회가 성공할 때마다 | +10 |
한도: 분당 60 요청.
요청에 실제로 든 비용은 모든 응답의 meta.request_credit_cost에 있어요.
요청 비용은 meta.request_credit_cost에, 남은 잔액은 meta.credits_remaining에 있어요. 위 스크립트처럼 진행하면서 비용을 합산하세요.
각 요청 전에 API는 잔액이 가능한 최고 가격을 감당하는지 확인해요. 그렇지 않으면 HTTP 402로 응답하고 과금하지 않아요. 그러면 스크립트가 멈춰요.
잔액과 사용량은 account로 언제든 무료로 확인할 수 있어요.
자주 하는 실수
- 법원 없는 등기 번호: 데이터에 “HRB 6089”만 있으면 API는 회사를 찾지 못해요. 등기 법원을 추가하거나 이름과 도시를 쓰세요.
- 키 하나에 요청 하나: 같은
Idempotency-Key를 다른 파라미터로 쓰면 HTTP 422가 반환돼요. 바뀐 요청에는 새 키를 쓰세요. - 키 형식: 문자, 숫자,
. _ : -로 이루어진 최대 128자, 문자나 숫자로 시작해야 해요. 다른 형식의 키는 API가 무시해요. 그러면 요청은 이 보호 없이 실행돼요. - 타임아웃: 실시간 모드나 많은 기능을 쓰면 요청이 더 오래 걸려요. 클라이언트 타임아웃을 최소 120초로 설정하세요.