Télécharger des documents

Extraits du registre, listes des associés et statuts sous forme de fichiers.

fetch-document récupère un document du Handelsregister (registre du commerce) et le renvoie sous forme de fichier : en PDF, ou en XML pour le contenu structuré du registre. Il te suffit de l’entity_id de l’entreprise, voir Récupérer un profil d’entreprise.

Choisir le type de document

Il existe cinq types de documents. Tu passes le type dans document_type, écrit exactement comme dans le tableau, majuscules et minuscules comprises.

document_type
document_type	Document	Format	Pour
AD	Aktueller Abdruck (extrait actuel) : toutes les inscriptions en vigueur aujourd’hui	PDF	chaque entreprise inscrite
CD	Chronologischer Abdruck (extrait chronologique) : toutes les inscriptions par ordre chronologique	PDF	chaque entreprise inscrite
SI	Strukturierter Registerinhalt (contenu structuré du registre) au format XJustiz, lisible par machine	XML	chaque entreprise inscrite
shareholders_list	Gesellschafterliste (liste des associés)	PDF	GmbH et UG
articles_of_association	Satzung ou Gesellschaftsvertrag (statuts)	PDF	Sociétés de capitaux et coopératives

Récupérer un document

Passe l’entity_id comme company_id et le type comme document_type. La réponse est le fichier lui-même, pas du JSON. Notre requête d’exemple enregistre l’Aktueller Abdruck de Hetzner Online GmbH, Ansbach HRB 6089.

curl -G "https://handelsregister.ai/api/v1/fetch-document" \
  -H "x-api-key: TA_CLE_API" \
  --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": "TA_CLE_API"},
    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"], "crédits facturés")

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": "TA_CLE_API" },
  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"), "crédits facturés");

Comme la réponse n’est pas du JSON, les informations la concernant figurent dans les headers :

Champ
Champ	Signification
Content-Type	`application/pdf`, pour le contenu structuré du registre `application/xml`.
Content-Disposition	Le nom de fichier avec entity_id, type et le jour où le document provient du registre.
X-Credits-Charged	Ce que la requête a coûté.
X-Credits-Remaining	Ton solde ensuite.

Si le document n’existe pas pour l’entreprise, tu reçois HTTP 404 sans frais.

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 · Exemple de réponse pour la liste des associés d’un commerçant individuel

L’API récupère les documents au registre si nécessaire. Cela peut prendre jusqu’à deux minutes. Règle le délai d’attente de ton client sur au moins 120 secondes ou récupère le document en arrière-plan.

Récupérer en arrière-plan

Si ton client ne peut pas attendre aussi longtemps, définis async=true. Si le document est déjà disponible, il arrive tout de suite. Sinon, l’API répond HTTP 202 et indique le temps d’attente en secondes dans Retry-After. Dans l’exemple, nous récupérons le Chronologischer Abdruck de SAP SE, Mannheim HRB 719915.

curl -G "https://handelsregister.ai/api/v1/fetch-document" \
  -H "x-api-key: TA_CLE_API" \
  --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": "TA_CLE_API"},
    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": "TA_CLE_API" },
});
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 · Exemple de réponse pendant la récupération du Chronologischer Abdruck de SAP SE

Répète la même requête après ce délai, et le fichier arrive avec HTTP 200. Seul le fichier livré coûte des crédits ; la réponse 202 est gratuite. Si aucune capacité n’est libre pour le moment, tu reçois HTTP 503, également avec Retry-After.

Chaque répétition compte dans la limite. Attends donc le délai indiqué au lieu de redemander à intervalles courts.

Coûts et limites

Coûts et limites
Quoi	Crédits
Un document livré	15

Limite : 5 requêtes par minute. Recherche, documents et Signals partagent un quota de 60 requêtes par minute.

Chaque document livré coûte 15 crédits, quel que soit le type. Comme chaque document provient du registre, fetch-document a sa propre limite, plus basse, de 5 requêtes par minute.

Avec une Idempotency-Key, tu ne paies un document qu’une fois, même si tu répètes la requête après une interruption. Plus d’informations sous Limites.

Si le Handelsregister est injoignable pour le moment ou répond trop lentement, tu reçois HTTP 504 avec Retry-After. L’API ne facture rien. Réessaie après quelques minutes.

Pièges fréquents

Numéro de registre au lieu de l’entity_id : company_id n’accepte que l’entity_id de 32 caractères. Ansbach HRB 6089 renvoie HTTP 400.
Liste des associés pour d’autres formes juridiques : elle n’existe que pour la GmbH et l’UG. Pour une KG ou un commerçant individuel, tu reçois HTTP 404.
Documents sous forme d’images : si un document n’est disponible qu’en TIFF au registre, l’API répond HTTP 415 et ne facture rien.

Ensuite

fetch-document Paramètres, réponses et erreurs de l’endpoint. Documents Ce que contient chaque document. Récupérer un profil d’entreprise Trouver l’entity_id d’une entreprise. Limites Requêtes par minute et nouvelles tentatives sans double facturation.