문서 다운로드
등기부 등본, 주주 명부, 정관을 파일로.
fetch-document는 Handelsregister(상업 등기부)에서 문서를 가져와 파일로 반환해요: PDF로, 또는 구조화 등기 내용은 XML로. 필요한 것은 회사의 entity_id뿐이에요. 회사 프로필 가져오기를 참고하세요.
문서 유형 선택
문서 유형은 다섯 가지예요. document_type에 표와 똑같이, 대소문자까지 맞춰 유형을 넘기세요.
| document_type | 문서 | 형식 | 대상 |
|---|---|---|---|
| AD | Aktueller Abdruck(현재 등본): 현재 유효한 모든 등기 | 등기된 모든 회사 | |
| CD | Chronologischer Abdruck(연대순 등본): 모든 등기를 시간순으로 | 등기된 모든 회사 | |
| SI | XJustiz 형식의 Strukturierter Registerinhalt(구조화 등기 내용), 기계 판독 가능 | XML | 등기된 모든 회사 |
| shareholders_list | Gesellschafterliste(주주 명부) | GmbH와 UG | |
| articles_of_association | Satzung 또는 Gesellschaftsvertrag(정관) | 자본회사와 협동조합 |
문서 가져오기
entity_id를 company_id로, 유형을 document_type으로 넘기세요. 응답은 JSON이 아니라 파일 자체예요. 예시 요청은 Hetzner Online GmbH, Ansbach HRB 6089의 Aktueller Abdruck를 저장해요.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode "company_id=94eb910fef13f94585c48c263fa446d4" \ --data-urlencode "document_type=AD" \ --fail-with-body --max-time 120 \ -o hetzner-ad.pdf
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-document", headers={"x-api-key": "YOUR_API_KEY"}, params={ "company_id": "94eb910fef13f94585c48c263fa446d4", "document_type": "AD", }, timeout=120, ) response.raise_for_status() with open("hetzner-ad.pdf", "wb") as file: file.write(response.content) print(response.headers["X-Credits-Charged"], "크레딧 차감됨")
import { writeFile } from "node:fs/promises"; const url = new URL("https://handelsregister.ai/api/v1/fetch-document"); url.searchParams.append("company_id", "94eb910fef13f94585c48c263fa446d4"); url.searchParams.append("document_type", "AD"); const response = await fetch(url, { headers: { "x-api-key": "YOUR_API_KEY" }, signal: AbortSignal.timeout(120_000), }); if (!response.ok) throw new Error(`HTTP ${response.status}`); await writeFile("hetzner-ad.pdf", Buffer.from(await response.arrayBuffer())); console.log(response.headers.get("x-credits-charged"), "크레딧 차감됨");
응답이 JSON이 아니므로 관련 정보는 헤더에 있어요:
| 필드 | 의미 |
|---|---|
| Content-Type |
application/pdf, 구조화 등기 내용은 application/xml. |
| Content-Disposition | entity_id, 유형, 문서를 등기부에서 가져온 날짜가 담긴 파일 이름. |
| X-Credits-Charged | 요청 비용. |
| X-Credits-Remaining | 요청 후 잔액. |
회사에 해당 문서가 없으면 비용 없이 HTTP 404를 받아요.
1{2 "error": "Document fetch failed",3 "message": "Document not available for this company. It may not exist or may become available later.",4 "meta": {5 "request_credit_cost": 0,6 "credits_remaining": 1457 }8}
백그라운드에서 가져오기
클라이언트가 그렇게 오래 기다릴 수 없다면 async=true를 설정하세요. 문서가 이미 있으면 바로 와요. 그렇지 않으면 API가 HTTP 202로 응답하고 Retry-After에 대기 시간을 초 단위로 알려 줘요. 예시에서는 SAP SE, Mannheim HRB 719915의 Chronologischer Abdruck를 가져와요.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode 'company_id=e3918174fb6c5d04e5e217e6ee4a6ffe' \ --data-urlencode 'document_type=CD' \ --data-urlencode 'async=true'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-document", headers={"x-api-key": "YOUR_API_KEY"}, params={ "company_id": "e3918174fb6c5d04e5e217e6ee4a6ffe", "document_type": "CD", "async": "true", }, ) data = response.json()
const url = new URL("https://handelsregister.ai/api/v1/fetch-document"); url.searchParams.append("company_id", "e3918174fb6c5d04e5e217e6ee4a6ffe"); url.searchParams.append("document_type", "CD"); url.searchParams.append("async", "true"); const response = await fetch(url, { headers: { "x-api-key": "YOUR_API_KEY" }, }); const data = await response.json();
1{2 "status": "processing",3 "meta": {4 "message": "The document is being retrieved. Repeat this request after Retry-After seconds to receive it.",5 "retry_after": 20,6 "request_credit_cost": 0,7 "credits_remaining": 1458 }9}
그 시간이 지난 뒤 같은 요청을 반복하면 파일이 HTTP 200으로 와요. 전달된 파일만 크레딧이 들고, 202 응답은 무료예요. 지금 여유 용량이 없으면 역시 Retry-After와 함께 HTTP 503을 받아요.
반복할 때마다 한도에 포함돼요. 그러니 짧은 간격으로 다시 묻지 말고 안내된 시간만큼 기다리세요.
비용과 한도
| 항목 | 크레딧 |
|---|---|
| 전달된 문서 1건 | 15 |
한도: 분당 5 요청. 검색, 문서, Signals는 분당 60 요청의 한도를 공유해요.
전달된 문서는 유형과 관계없이 각각 15 크레딧이에요. 각 문서를 등기부에서 가져오므로 fetch-document에는 별도의 더 낮은 한도 분당 5 요청이 있어요.
Idempotency-Key를 쓰면 요청이 끊긴 뒤 반복해도 문서 비용은 한 번만 내요. 자세한 내용은 한도에 있어요.
Retry-After와 함께 HTTP 504를 받아요. API는 과금하지 않아요. 몇 분 뒤 다시 시도하세요.
자주 하는 실수
- entity_id 대신 등기 번호:
company_id는 32자 entity_id만 받아요.Ansbach HRB 6089는 HTTP 400을 반환해요. - 다른 법적 형태의 주주 명부: GmbH와 UG에만 있어요. KG나 개인 상인은 HTTP 404를 받아요.
- 이미지 파일로 된 문서: 등기부에 TIFF로만 있는 문서는 API가 HTTP 415로 응답하고 과금하지 않아요.