Node SDK

La API desde JavaScript y TypeScript.

El Node SDK ofrece un cliente para JavaScript y TypeScript, con definiciones de tipos para solicitudes y respuestas. Reintenta por sí mismo los errores temporales y convierte las respuestas de error en clases de error propias.

Instalar

Instala el paquete handelsregister con npm.

Terminal

npm install handelsregister
export HANDELSREGISTER_API_KEY=TU_CLAVE_API

Qué
Qué	Valor
Paquete	`handelsregister`
Versión actual	0.7.0
Node.js	22.13 o posterior
TypeScript	Definiciones de tipos incluidas
Licencia	AGPL-3.0
Código fuente	github.com/Handelsregister-AI/handelsregister-js

El SDK lee tu clave API de la variable de entorno HANDELSREGISTER_API_KEY. También puedes pasarla al crear el cliente. Un bearer token va mediante HANDELSREGISTER_BEARER_TOKEN o bearerToken. La clave se envía siempre en el header, nunca en la URL.

Primera solicitud

fetchOrganization obtiene un perfil de empresa y devuelve la respuesta de la API como objeto. El parámetro q acepta un nombre, tribunal registral con número de registro o una entity_id.

JavaScript

import { Handelsregister } from 'handelsregister';

const client = new Handelsregister({ apiKey: process.env.HANDELSREGISTER_API_KEY });

const empresa = await client.fetchOrganization({ q: 'Hetzner Online GmbH' });
console.log(empresa.entity_id, empresa.name);
console.log(empresa.registration); // { court: 'Ansbach', register_type: 'HRB', register_number: '6089' }
console.log(empresa.meta.request_credit_cost);

La respuesta es la misma que con fetch-organization. Aquí un fragmento:

1{2  "entity_id": "94eb910fef13f94585c48c263fa446d4",3  "name": "Hetzner Online GmbH",4  "status": "ACTIVE",5  "legal_form": "GmbH",6  "registration": {7    "court": "Ansbach",8    "register_type": "HRB",9    "register_number": "6089"10  },11  "meta": {12    "request_credit_cost": 5,13    "credits_remaining": 14514  }15}

200 · Fragmento de nuestra respuesta de ejemplo para Hetzner Online GmbH, Ansbach HRB 6089, solo datos básicos

Pides más datos con features, el modo IA con aiSearch: true y Tiempo real con realtimeMode: true. Todas las funciones están en fetch-organization.

JavaScript

const empresa = await client.fetchOrganization({
  q: 'Ansbach HRB 6089',
  features: ['financial_kpi', 'related_persons'],
});

Durante una hora, el cliente responde a solicitudes idénticas desde su caché, sin créditos nuevos. Las solicitudes con Tiempo real van siempre a la API. Usa cacheEnabled: false para desactivar la caché.

Gestionar errores

Cada respuesta de error de la API se convierte en un error con su propia clase. Todas heredan de HandelsregisterError y llevan statusCode, la respuesta en response y los costes en meta.

Excepción
Excepción	Estado	Significado
AuthenticationError	401	Clave API ausente o no válida.
InsufficientCreditsError	402	Tu saldo no alcanza para esta solicitud.
SubscriptionRequiredError	403	La solicitud necesita un plan superior. `requiredPlans` nombra los planes adecuados.
NotFoundError	404	No se encontró ninguna empresa o persona que encaje.
RequestTimeoutError	408	El registro no respondió a tiempo. No se cobró nada.
RequestValidationError	400, 422	Un parámetro tiene un valor no válido.
RateLimitError	429	Demasiadas solicitudes por minuto.
ServerError	5xx	La fuente de datos no está disponible o está sobrecargada ahora mismo. Vuelve a intentarlo más tarde.

JavaScript

import {
  Handelsregister,
  HandelsregisterError,
  InsufficientCreditsError,
  NotFoundError,
  RequestTimeoutError,
} from 'handelsregister';

const client = new Handelsregister({ timeout: 120000 });

try {
  const empresa = await client.fetchOrganization({
    q: 'Hetzner Online GmbH',
    realtimeMode: true,
  });
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('No se encontró ninguna empresa coincidente');
  } else if (error instanceof InsufficientCreditsError) {
    console.log('Créditos insuficientes:', error.meta);
  } else if (error instanceof RequestTimeoutError) {
    console.log('El registro no responde ahora mismo, inténtalo más tarde');
  } else if (error instanceof HandelsregisterError) {
    console.log('Error:', error.statusCode, error.message);
  } else {
    throw error;
  }
}

Con errores de red, el estado 429 y errores de servidor, el SDK reintenta por sí mismo, con hasta tres intentos en total. Si la API envía un tiempo de espera en Retry-After, lo respeta.

Por defecto, el cliente espera 90 segundos una respuesta. Para Tiempo real, perfiles de persona y documentos recomendamos al menos 120 segundos, es decir, timeout: 120000.

Línea de comandos

El paquete incluye el programa handelsregister. Obtiene perfiles de empresa, perfiles de persona y documentos, busca empresas y enriquece archivos.

Terminal

# Perfil de empresa sin modo IA, solo con KPI financieros
npx handelsregister fetch "Hetzner Online GmbH" --no-ai-search --feature financial_kpi

# Guardar la lista de socios como PDF
npx handelsregister document "Hetzner Online GmbH" --type shareholders_list --output hetzner.pdf

Sin más opciones, handelsregister fetch activa el modo IA. Una solicitud cuesta entonces 25 créditos en lugar de 5, incluso sin funciones. Con --no-ai-search, pides sin modo IA.

handelsregister document busca primero la empresa mediante un perfil de empresa sin modo IA. Por eso se suman 5 créditos a los 15 créditos del documento.

Referencia

La referencia completa con todos los métodos está en el README del repositorio. El SDK cubre toda la API:

Perfiles de empresa con todas las funciones, también como clase Company
Perfiles de persona, también como clase Person
Búsqueda y exportación con filtros, ordenación y paginación automática
Documentos como archivos
Signals, Monitoring y endpoints de webhook, con verificación de la firma de los webhooks
Cuenta, saldo, consumo y claves API
Enriquecimiento de archivos CSV, JSON y Excel completos

El SDK tiene licencia AGPL-3.0. El código fuente está en GitHub y el paquete en npm.

fetch-organization Todos los parámetros, funciones y campos del perfil de empresa. Python SDK La misma API desde Python.