Descargar documentos

Extractos del registro, listas de socios y estatutos como archivos.

fetch-document obtiene un documento del Handelsregister (Registro Mercantil) y lo devuelve como archivo: como PDF, o como XML para el contenido estructurado del registro. Solo necesitas la entity_id de la empresa, consulta Obtener un perfil de empresa.

Elegir el tipo de documento

Hay cinco tipos de documento. Pasas el tipo en document_type, escrito exactamente como en la tabla, con mayúsculas y minúsculas.

document_type
document_type	Documento	Formato	Para
AD	Aktueller Abdruck (extracto actual): todas las inscripciones vigentes hoy	PDF	toda empresa inscrita
CD	Chronologischer Abdruck (extracto cronológico): todas las inscripciones en orden cronológico	PDF	toda empresa inscrita
SI	Strukturierter Registerinhalt (contenido estructurado del registro) en formato XJustiz, legible por máquina	XML	toda empresa inscrita
shareholders_list	Gesellschafterliste (lista de socios)	PDF	GmbH y UG
articles_of_association	Satzung o Gesellschaftsvertrag (estatutos)	PDF	Sociedades de capital y cooperativas

Obtener un documento

Pasa la entity_id como company_id y el tipo como document_type. La respuesta es el propio archivo, no JSON. Nuestra solicitud de ejemplo guarda el Aktueller Abdruck de Hetzner Online GmbH, Ansbach HRB 6089.

curl -G "https://handelsregister.ai/api/v1/fetch-document" \
  -H "x-api-key: TU_CLAVE_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": "TU_CLAVE_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éditos cobrados")

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": "TU_CLAVE_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éditos cobrados");

Como la respuesta no es JSON, los datos sobre ella están en los headers:

Campo
Campo	Significado
Content-Type	`application/pdf`, para el contenido estructurado del registro `application/xml`.
Content-Disposition	El nombre del archivo con entity_id, tipo y el día en que el documento salió del registro.
X-Credits-Charged	Lo que costó la solicitud.
X-Credits-Remaining	Tu saldo después.

Si el documento no existe para la empresa, recibes HTTP 404 sin coste.

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 · Respuesta de ejemplo para la lista de socios de un comerciante individual

La API obtiene los documentos del registro cuando hace falta. Esto puede tardar hasta dos minutos. Configura el timeout de tu cliente en al menos 120 segundos u obtén el documento en segundo plano.

Obtener en segundo plano

Si tu cliente no puede esperar tanto, usa async=true. Si el documento ya está disponible, llega al momento. Si no, la API responde con HTTP 202 e indica el tiempo de espera en segundos en Retry-After. En el ejemplo obtenemos el Chronologischer Abdruck de SAP SE, Mannheim HRB 719915.

curl -G "https://handelsregister.ai/api/v1/fetch-document" \
  -H "x-api-key: TU_CLAVE_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": "TU_CLAVE_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": "TU_CLAVE_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 · Respuesta de ejemplo mientras se obtiene el Chronologischer Abdruck de SAP SE

Repite la misma solicitud pasado ese tiempo y el archivo llegará con HTTP 200. Solo el archivo entregado cuesta créditos; la respuesta 202 es gratis. Si ahora mismo no hay capacidad libre, recibes HTTP 503, también con Retry-After.

Cada repetición cuenta para el límite. Así que espera el tiempo indicado en lugar de volver a preguntar a intervalos cortos.

Costes y límites

Costes y límites
Qué	Créditos
Un documento entregado	15

Límite: 5 solicitudes por minuto. Búsqueda, documentos y Signals comparten una cuota de 60 solicitudes por minuto.

Cada documento entregado cuesta 15 créditos, sea del tipo que sea. Como cada documento viene del registro, fetch-document tiene su propio límite, más bajo, de 5 solicitudes por minuto.

Con un Idempotency-Key pagas un documento solo una vez, aunque repitas la solicitud después de que se cortara. Más en Límites.

Si el Handelsregister no está accesible en este momento o responde demasiado lento, recibes HTTP 504 con Retry-After. La API no cobra nada. Vuelve a intentarlo pasados unos minutos.

Errores frecuentes

Número de registro en lugar de entity_id: company_id solo acepta la entity_id de 32 caracteres. Ansbach HRB 6089 devuelve HTTP 400.
Lista de socios para otras formas jurídicas: Solo existe para GmbH y UG. Para una KG o un comerciante individual recibes HTTP 404.
Documentos como imágenes: Si un documento solo está disponible como TIFF en el registro, la API responde con HTTP 415 y no cobra nada.

fetch-document Parámetros, respuestas y errores del endpoint. Documentos Qué contiene cada documento. Obtener un perfil de empresa Encontrar la entity_id de una empresa. Límites Solicitudes por minuto y reintentos sin cobro doble.