Node SDK
JavaScript와 TypeScript용 API.
Node SDK는 요청과 응답의 타입 정의를 갖춘 JavaScript와 TypeScript용 클라이언트를 제공해요. 일시적인 오류는 알아서 재시도하고, 오류 응답은 전용 오류 클래스로 바꿔요.
설치
npm으로 handelsregister 패키지를 설치하세요.
npm install handelsregister export HANDELSREGISTER_API_KEY=YOUR_API_KEY
| 항목 | 값 |
|---|---|
| 패키지 |
handelsregister |
| 현재 버전 | 0.7.0 |
| Node.js | 22.13 이상 |
| TypeScript | 타입 정의 포함 |
| 라이선스 | AGPL-3.0 |
| 소스 코드 | github.com/Handelsregister-AI/handelsregister-js |
SDK는 환경 변수 HANDELSREGISTER_API_KEY에서 API 키를 읽어요. 클라이언트를 만들 때 넘길 수도 있어요. Bearer 토큰은 HANDELSREGISTER_BEARER_TOKEN 또는 bearerToken으로 넘겨요. 키는 항상 헤더로 보내고, URL에는 절대 넣지 않아요.
첫 요청
fetchOrganization은 회사 프로필을 가져와 API 응답을 객체로 반환해요. q 파라미터는 이름, 등기 법원과 등기 번호, 또는 entity_id를 받아요.
import { Handelsregister } from 'handelsregister'; const client = new Handelsregister({ apiKey: process.env.HANDELSREGISTER_API_KEY }); const company = await client.fetchOrganization({ q: 'Hetzner Online GmbH' }); console.log(company.entity_id, company.name); console.log(company.registration); // { court: 'Ansbach', register_type: 'HRB', register_number: '6089' } console.log(company.meta.request_credit_cost);
응답은 fetch-organization과 같아요. 발췌:
1{2 "entity_id": "94eb910fef13f94585c48c263fa446d4",3 "name": "Hetzner Online GmbH",4 "status": "ACTIVE",5 "legal_form": "GmbH",6 "registration": {7 "court": "Ansbach",8 "register_type": "HRB",9 "register_number": "6089"10 },11 "meta": {12 "request_credit_cost": 5,13 "credits_remaining": 14514 }15}
features로 더 많은 데이터를, aiSearch: true로 AI 모드를, realtimeMode: true로 실시간 모드를 요청해요. 모든 기능은 fetch-organization에 있어요.
const company = await client.fetchOrganization({ q: 'Ansbach HRB 6089', features: ['financial_kpi', 'related_persons'], });
cacheEnabled: false를 설정하세요.
오류 처리
API의 모든 오류 응답은 고유한 클래스의 오류가 돼요. 모두 HandelsregisterError를 상속하고 statusCode, response의 응답, meta의 비용을 담아요.
| 예외 | 상태 | 의미 |
|---|---|---|
| AuthenticationError | 401 | API 키가 없거나 유효하지 않아요. |
| InsufficientCreditsError | 402 | 잔액이 이 요청에 부족해요. |
| SubscriptionRequiredError | 403 |
요청에 더 높은 플랜이 필요해요. requiredPlans에 맞는 플랜이 나와요. |
| NotFoundError | 404 | 일치하는 회사나 인물을 찾지 못했어요. |
| RequestTimeoutError | 408 | 등기부가 제때 응답하지 않았어요. 과금되지 않았어요. |
| RequestValidationError | 400, 422 | 파라미터 값이 유효하지 않아요. |
| RateLimitError | 429 | 분당 요청이 너무 많아요. |
| ServerError | 5xx | 데이터 소스를 지금 쓸 수 없거나 과부하 상태예요. 나중에 다시 시도하세요. |
import { Handelsregister, HandelsregisterError, InsufficientCreditsError, NotFoundError, RequestTimeoutError, } from 'handelsregister'; const client = new Handelsregister({ timeout: 120000 }); try { const company = await client.fetchOrganization({ q: 'Hetzner Online GmbH', realtimeMode: true, }); } catch (error) { if (error instanceof NotFoundError) { console.log('일치하는 회사를 찾지 못했어요'); } else if (error instanceof InsufficientCreditsError) { console.log('크레딧 부족:', error.meta); } else if (error instanceof RequestTimeoutError) { console.log('등기부가 지금 응답하지 않아요. 나중에 다시 시도하세요'); } else if (error instanceof HandelsregisterError) { console.log('오류:', error.statusCode, error.message); } else { throw error; } }
네트워크 오류, 상태 429, 서버 오류에서는 SDK가 알아서 재시도하며, 총 최대 세 번 시도해요. API가 Retry-After로 대기 시간을 보내면 그대로 따라요.
기본적으로 클라이언트는 응답을 90초 기다려요. 실시간 모드, 인물 프로필, 문서는 최소 120초, 즉 timeout: 120000를 권장해요.
명령줄
패키지에는 handelsregister 프로그램이 들어 있어요. 회사 프로필, 인물 프로필, 문서를 가져오고, 회사를 검색하고, 파일을 보강해요.
# AI 모드 없이, 재무 KPI만 포함한 회사 프로필 npx handelsregister fetch "Hetzner Online GmbH" --no-ai-search --feature financial_kpi # 주주 명부(Gesellschafterliste)를 PDF로 저장 npx handelsregister document "Hetzner Online GmbH" --type shareholders_list --output hetzner.pdf
handelsregister fetch는 AI 모드를 켜요. 그러면 기능이 없어도 요청 비용이 5 대신 25 크레딧이에요. --no-ai-search로 AI 모드 없이 요청하세요.
handelsregister document는 먼저 AI 모드 없는 회사 프로필로 회사를 찾아요. 그래서 문서의 15 크레딧에 5 크레딧이 더해져요.