Λήψη εγγράφων

Αποσπάσματα μητρώου, λίστες εταίρων και καταστατικά ως αρχεία.

Το fetch-document ανακτά ένα έγγραφο από το Handelsregister (εμπορικό μητρώο) και το επιστρέφει ως αρχείο: ως PDF, ή ως XML για το δομημένο περιεχόμενο μητρώου. Χρειάζεσαι μόνο το entity_id της εταιρείας, βλ. Ανάκτηση προφίλ εταιρείας.

Επιλογή τύπου εγγράφου

Υπάρχουν πέντε τύποι εγγράφων. Περνάς τον τύπο στο document_type, γραμμένο ακριβώς όπως στον πίνακα, με κεφαλαία και πεζά.

document_type
document_type	Έγγραφο	Μορφή	Για
AD	Aktueller Abdruck (τρέχον απόσπασμα): όλες οι εγγραφές που ισχύουν σήμερα	PDF	κάθε εγγεγραμμένη εταιρεία
CD	Chronologischer Abdruck (χρονολογικό απόσπασμα): όλες οι εγγραφές με χρονολογική σειρά	PDF	κάθε εγγεγραμμένη εταιρεία
SI	Strukturierter Registerinhalt (δομημένο περιεχόμενο μητρώου) στη μορφή XJustiz, μηχαναγνώσιμο	XML	κάθε εγγεγραμμένη εταιρεία
shareholders_list	Gesellschafterliste (λίστα εταίρων)	PDF	GmbH και UG
articles_of_association	Satzung ή Gesellschaftsvertrag (καταστατικό)	PDF	Κεφαλαιουχικές εταιρείες και συνεταιρισμοί

Ανάκτηση εγγράφου

Πέρασε το entity_id ως company_id και τον τύπο ως document_type. Η απάντηση είναι το ίδιο το αρχείο, όχι JSON. Το παράδειγμα αιτήματός μας αποθηκεύει τον Aktueller Abdruck της Hetzner Online GmbH, Ansbach HRB 6089.

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, οι πληροφορίες γι’ αυτήν βρίσκονται στα headers:

Πεδίο
Πεδίο	Σημασία
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}

404 · Παράδειγμα απάντησης για τη λίστα εταίρων ενός ατομικού εμπόρου

Το API ανακτά τα έγγραφα από το μητρώο όταν χρειάζεται. Αυτό μπορεί να διαρκέσει έως δύο λεπτά. Όρισε το timeout του client σου σε τουλάχιστον 120 δευτερόλεπτα ή ανάκτησε το έγγραφο στο παρασκήνιο.

Ανάκτηση στο παρασκήνιο

Αν ο client σου δεν μπορεί να περιμένει τόσο, όρισε async=true. Αν το έγγραφο είναι ήδη διαθέσιμο, έρχεται αμέσως. Διαφορετικά το API απαντά με HTTP 202 και δίνει τον χρόνο αναμονής σε δευτερόλεπτα στο Retry-After. Στο παράδειγμα ανακτούμε τον Chronologischer Abdruck της SAP SE, Mannheim HRB 719915.

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}

202 · Παράδειγμα απάντησης ενώ ανακτάται ο Chronologischer Abdruck της SAP SE

Επανάλαβε το ίδιο αίτημα μετά από αυτόν τον χρόνο, και το αρχείο έρχεται με HTTP 200. Μόνο το αρχείο που παραδίδεται κοστίζει πιστώσεις· η απάντηση 202 είναι δωρεάν. Αν δεν υπάρχει ελεύθερη χωρητικότητα αυτή τη στιγμή, λαμβάνεις HTTP 503, επίσης με Retry-After.

Κάθε επανάληψη μετράει στο όριο. Γι’ αυτό περίμενε τον χρόνο που δίνεται αντί να ρωτάς ξανά σε σύντομα διαστήματα.

Κόστος και όρια

Κόστος και όρια
Τι	Πιστώσεις
Ένα έγγραφο που παραδόθηκε	15

Όριο: 5 αιτήματα ανά λεπτό. Η αναζήτηση, τα έγγραφα και τα Signals μοιράζονται ένα όριο 60 αιτημάτων ανά λεπτό.

Κάθε έγγραφο που παραδίδεται κοστίζει 15 πιστώσεις, ανεξάρτητα από τον τύπο. Επειδή κάθε έγγραφο έρχεται από το μητρώο, το fetch-document έχει δικό του, χαμηλότερο όριο 5 αιτήματα ανά λεπτό.

Με ένα Idempotency-Key, πληρώνεις για ένα έγγραφο μόνο μία φορά, ακόμη και αν επαναλάβεις το αίτημα αφού διακόπηκε. Περισσότερα στα Όρια.

Αν το Handelsregister δεν είναι προσβάσιμο αυτή τη στιγμή ή απαντά πολύ αργά, λαμβάνεις HTTP 504 με Retry-After. Το API δεν χρεώνει τίποτα. Δοκίμασε ξανά μετά από λίγα λεπτά.

Συνήθεις παγίδες

Αριθμός μητρώου αντί για entity_id: Το company_id δέχεται μόνο το entity_id των 32 χαρακτήρων. Το Ansbach HRB 6089 επιστρέφει HTTP 400.
Λίστα εταίρων για άλλες νομικές μορφές: Υπάρχει μόνο για GmbH και UG. Για μια KG ή έναν ατομικό έμπορο, λαμβάνεις HTTP 404.
Έγγραφα ως αρχεία εικόνας: Αν ένα έγγραφο είναι διαθέσιμο στο μητρώο μόνο ως TIFF, το API απαντά με HTTP 415 και δεν χρεώνει τίποτα.

Συνέχεια

fetch-document Παράμετροι, απαντήσεις και σφάλματα του endpoint. Έγγραφα Τι περιέχει κάθε έγγραφο. Ανάκτηση προφίλ εταιρείας Εύρεση του entity_id μιας εταιρείας. Όρια Αιτήματα ανά λεπτό και επανάληψη χωρίς διπλή χρέωση.