Baixar documentos
Extratos do registro, listas de sócios e contratos sociais como arquivos.
fetch-document obtém um documento do Handelsregister (registro comercial) e o retorna como arquivo: em PDF, ou em XML para o conteúdo estruturado do registro. Basta o entity_id da empresa, veja Obter um perfil de empresa.
Escolher o tipo de documento
Existem cinco tipos de documento. Você passa o tipo em document_type, escrito exatamente como na tabela, incluindo maiúsculas e minúsculas.
| document_type | Documento | Formato | Para |
|---|---|---|---|
| AD | Aktueller Abdruck (extrato atual): todos os registros válidos hoje | toda empresa registrada | |
| CD | Chronologischer Abdruck (extrato cronológico): todos os registros em ordem cronológica | toda empresa registrada | |
| SI | Strukturierter Registerinhalt (conteúdo estruturado do registro) no formato XJustiz, legível por máquina | XML | toda empresa registrada |
| shareholders_list | Gesellschafterliste (lista de sócios) | GmbH e UG | |
| articles_of_association | Satzung ou Gesellschaftsvertrag (estatuto ou contrato social) | Sociedades de capital e cooperativas |
Obter um documento
Passe o entity_id como company_id e o tipo como document_type. A resposta é o próprio arquivo, não JSON. Nossa requisição de exemplo salva o Aktueller Abdruck da Hetzner Online GmbH, Ansbach HRB 6089.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: SUA_CHAVE_DE_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": "SUA_CHAVE_DE_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": "SUA_CHAVE_DE_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 a resposta não é JSON, os detalhes sobre ela estão nos headers:
| Campo | Significado |
|---|---|
| Content-Type |
application/pdf, para o conteúdo estruturado do registro application/xml. |
| Content-Disposition | O nome do arquivo com entity_id, tipo e o dia em que o documento veio do registro. |
| X-Credits-Charged | Quanto a requisição custou. |
| X-Credits-Remaining | O seu saldo depois. |
Se o documento não existe para a empresa, você recebe HTTP 404 sem custo.
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}
Obter em segundo plano
Se o seu cliente não pode esperar tanto, defina async=true. Se o documento já estiver disponível, ele vem na hora. Caso contrário, a API responde com HTTP 202 e informa o tempo de espera em segundos em Retry-After. No exemplo, obtemos o Chronologischer Abdruck da SAP SE, Mannheim HRB 719915.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: SUA_CHAVE_DE_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": "SUA_CHAVE_DE_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": "SUA_CHAVE_DE_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}
Repita a mesma requisição depois desse tempo, e o arquivo vem com HTTP 200. Só o arquivo entregue custa créditos; a resposta 202 é grátis. Se não houver capacidade livre no momento, você recebe HTTP 503, também com Retry-After.
Cada repetição conta para o limite. Por isso, espere o tempo informado em vez de perguntar de novo em intervalos curtos.
Custos e limites
| O quê | Créditos |
|---|---|
| Um documento entregue | 15 |
Limite: 5 requisições por minuto. Busca, documentos e Signals compartilham uma cota de 60 requisições por minuto.
Cada documento entregue custa 15 créditos, seja qual for o tipo. Como cada documento vem do registro, fetch-document tem um limite próprio e menor, de 5 requisições por minuto.
Com um Idempotency-Key, você paga por um documento só uma vez, mesmo que repita a requisição depois de uma interrupção. Mais em Limites.
Retry-After. A API não cobra nada. Tente de novo depois de alguns minutos.
Armadilhas comuns
- Número de registro em vez de entity_id:
company_idsó aceita o entity_id de 32 caracteres.Ansbach HRB 6089retorna HTTP 400. - Lista de sócios para outras formas jurídicas: ela só existe para GmbH e UG. Para uma KG ou um empresário individual, você recebe HTTP 404.
- Documentos como arquivos de imagem: se um documento só estiver disponível como TIFF no registro, a API responde com HTTP 415 e não cobra nada.