Node SDK

A API a partir de JavaScript e TypeScript.

O Node SDK oferece um cliente para JavaScript e TypeScript, com definições de tipos para requisições e respostas. Ele repete erros temporários por conta própria e transforma respostas de erro em classes de erro específicas.

Instalar

Instale o pacote handelsregister com npm.

Terminal

npm install handelsregister
export HANDELSREGISTER_API_KEY=SUA_CHAVE_DE_API

O quê
O quê	Valor
Pacote	`handelsregister`
Versão atual	0.7.0
Node.js	22.13 ou mais recente
TypeScript	Definições de tipos incluídas
Licença	AGPL-3.0
Código-fonte	github.com/Handelsregister-AI/handelsregister-js

O SDK lê sua chave de API da variável de ambiente HANDELSREGISTER_API_KEY. Você também pode passá-la ao criar o cliente. Um bearer token vai por HANDELSREGISTER_BEARER_TOKEN ou bearerToken. A chave sempre vai no header, nunca na URL.

Primeira requisição

fetchOrganization obtém um perfil de empresa e retorna a resposta da API como objeto. O parâmetro q aceita um nome, tribunal de registro com número de registro ou um 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);

A resposta é a mesma de fetch-organization. Aqui está um trecho:

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 · Trecho da nossa resposta de exemplo para a Hetzner Online GmbH, Ansbach HRB 6089, só dados básicos

Você solicita mais dados com features, o Modo IA com aiSearch: true e o Tempo real com realtimeMode: true. Todos os recursos estão listados em fetch-organization.

JavaScript

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

Durante uma hora, o cliente responde requisições idênticas a partir do cache, sem novos créditos. Requisições com Tempo real sempre vão para a API. Defina cacheEnabled: false para desativar o cache.

Tratar erros

Toda resposta de erro da API vira um erro com classe própria. Todos herdam de HandelsregisterError e trazem statusCode, a resposta em response e os custos em meta.

Exceção
Exceção	Status	Significado
AuthenticationError	401	Chave de API ausente ou inválida.
InsufficientCreditsError	402	Seu saldo não é suficiente para esta requisição.
SubscriptionRequiredError	403	A requisição precisa de um plano superior. `requiredPlans` indica os planos adequados.
NotFoundError	404	Nenhuma empresa ou pessoa correspondente encontrada.
RequestTimeoutError	408	O registro não respondeu a tempo. Nada foi cobrado.
RequestValidationError	400, 422	Um parâmetro tem um valor inválido.
RateLimitError	429	Requisições demais por minuto.
ServerError	5xx	A fonte de dados está indisponível ou sobrecarregada no momento. Tente de novo mais 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('Nenhuma empresa correspondente encontrada');
  } else if (error instanceof InsufficientCreditsError) {
    console.log('Créditos insuficientes:', error.meta);
  } else if (error instanceof RequestTimeoutError) {
    console.log('O registro não está respondendo agora, tente de novo mais tarde');
  } else if (error instanceof HandelsregisterError) {
    console.log('Erro:', error.statusCode, error.message);
  } else {
    throw error;
  }
}

Em erros de rede, status 429 e erros de servidor, o SDK repete por conta própria, com até três tentativas no total. Se a API enviar um tempo de espera em Retry-After, ele o respeita.

Por padrão, o cliente espera 90 segundos por uma resposta. Para Tempo real, perfis de pessoas e documentos, recomendamos pelo menos 120 segundos, ou seja, timeout: 120000.

Linha de comando

O pacote vem com o programa handelsregister. Ele obtém perfis de empresas, perfis de pessoas e documentos, busca empresas e enriquece arquivos.

Terminal

# Perfil da empresa sem Modo IA, só com KPIs financeiros
npx handelsregister fetch "Hetzner Online GmbH" --no-ai-search --feature financial_kpi

# Salvar a lista de sócios como PDF
npx handelsregister document "Hetzner Online GmbH" --type shareholders_list --output hetzner.pdf

Sem outras opções, handelsregister fetch ativa o Modo IA. Uma requisição então custa 25 créditos em vez de 5, mesmo sem recursos. Com --no-ai-search, você faz a requisição sem Modo IA.

handelsregister document primeiro identifica a empresa por um perfil de empresa sem Modo IA. Por isso, 5 créditos se somam aos 15 créditos do documento.

Referência

A referência completa com todos os métodos está no README do repositório. O SDK cobre a API inteira:

Perfis de empresas com todos os recursos, também como classe Company
Perfis de pessoas, também como classe Person
Busca & Exportação com filtros, ordenação e paginação automática
Documentos como arquivos
Signals, Monitoramento e endpoints de webhook, com verificação da assinatura do webhook
Conta, saldo, uso e chaves de API
Enriquecimento de arquivos CSV, JSON e Excel inteiros

O SDK é licenciado sob AGPL-3.0. O código-fonte está no GitHub e o pacote no npm.

fetch-organization Todos os parâmetros, recursos e campos do perfil da empresa. Python SDK A mesma API a partir do Python.