고객 데이터 보강

고객 목록에 회사 데이터를 더하세요.

1

회사 매칭

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'q=Hetzner Online GmbH Gunzenhausen'
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}
200 · 예시 응답: 이름과 도시로 매칭(발췌)
API가 회사를 찾지 못하면 HTTP 404를 받아요. AI 모드가 없으면 비용이 들지 않아요. 그 고객을 검토 대상으로 표시하세요. 모호한 항목에만 골라서 AI 모드(ai_search=on-default)를 쓰세요. 일치 결과가 없어도 20 크레딧가 추가로 들어요.
2

여러 회사 가져오기

Python 스크립트
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} 크레딧")
1{2  "entity_id": "94eb910fef13f94585c48c263fa446d4",3  "name": "Hetzner Online GmbH",4  "meta": {5    "request_credit_cost": 0,6    "credits_remaining": 1457  }8}
200 · 예시 응답: 같은 Idempotency-Key로 반복한 요청(발췌)
Python SDK에는 CSV, JSON, Excel 파일을 위한 준비된 보강 기능 enrich가 있어요.
3

비용 관리

비용과 한도
항목 크레딧
기본 데이터가 포함된 회사 프로필 5
각 기능, 데이터를 반환할 때만 1~80
AI 모드, 일치 결과가 없어도 +20
실시간 모드, 실시간 조회가 성공할 때마다 +10

한도: 분당 60 요청. 요청에 실제로 든 비용은 모든 응답의 meta.request_credit_cost에 있어요.

자주 하는 실수

다음