Conceptos básicos

El parámetro q de fetch-organization acepta tres tipos de entrada. Los ejemplos de esta página son solicitudes para Hetzner Online GmbH, Ansbach HRB 6089:

El número de registro solo no basta, porque cada tribunal registral asigna sus propios números. El orden, en cambio, es libre: en el ejemplo, HRB 6089 Ansbach encuentra la misma empresa.

Si la API no encuentra ninguna empresa, responde con 404 y no cobra nada. Para entradas imprecisas está el modo IA (ai_search=on-default): encuentra la empresa también a partir de partes del nombre y la investiga en la web. Cuesta 20 créditos adicionales, aunque no encuentre ninguna empresa. Para obtener varios candidatos a la vez, usa Búsqueda y exportación.

Cada perfil de empresa contiene los datos básicos, entre ellos nombre, forma jurídica, estado, inscripción registral, dirección, objeto social, sector, capital y reglas de representación. Todo lo demás lo pides como función (feature), por ejemplo related_persons para los administradores o financial_kpi para los KPI financieros.

Pasas varias funciones con un feature repetido o como lista: features=related_persons,financial_kpi. Cada función aparece en la respuesta bajo su propia clave. Solo publications se llama allí history.

La API ignora los nombres desconocidos sin mensaje de error, así que revisa la ortografía. Las funciones que tu plan no incluye se omiten y no se cobran.

Todas las funciones con sus precios están en fetch-organization, cada campo en el Catálogo de datos.

Las solicitudes de datos cuestan créditos. Para un perfil de empresa rigen estas reglas:

• El precio base de 5 créditos se aplica cuando la API devuelve una empresa.
• Una función solo cuesta créditos cuando devuelve datos en la respuesta. Una función vacía es gratis, también insolvency_publications sin entradas.
• Tiempo real y el modo IA no son funciones, sino recargos con reglas propias:
  • Tiempo real cuesta 10 créditos adicionales en cuanto la consulta en directo tiene éxito. También cuando no muestra nada nuevo.
  • El modo IA cuesta 20 créditos adicionales, aunque no encuentre ninguna empresa. El recargo solo se omite cuando la API interrumpe la solicitud con 408 porque tarda demasiado.
• Todos los demás errores no cuestan nada.

La regla de cada función está en Facturación, los precios en fetch-organization.

Un ejemplo: los datos básicos con related_persons y financial_kpi cuestan 5 + 2 + 1 = 8 créditos si ambas funciones devuelven datos.

Antes de cada solicitud, la API comprueba si tu saldo cubre el precio más alto posible. Si no, responde con 402 y no cobra nada. Lo que se cobró realmente está en meta.request_credit_cost, tu saldo después en meta.credits_remaining.

Recibes créditos como créditos iniciales, cada mes con una suscripción de créditos o una vez como créditos de recarga. Sin suscripción de créditos, los créditos iniciales y de recarga son válidos durante 30 días; con una suscripción activa no caducan. Todo lo demás está en Facturación.

Por defecto, el perfil de empresa viene de nuestra base de datos. Lo actual que es un dato depende de su fuente.

Mantenemos actualizados en nuestra base de datos los datos básicos, las personas y los anuncios registrales a partir del registro. Es rápido y basta para la mayoría de los usos.

Con Tiempo real (realtime_mode=handelsregister-default), la API obtiene en directo el Aktueller Abdruck (AD, extracto actual) del Handelsregister (Registro Mercantil) en el momento de tu solicitud y lo devuelve como JSON. Además recibes las personas inscritas actualmente en related_persons.current, sin pagar la función.

Si la consulta en directo funcionó lo indica _realtime_mode.status. Solo cobramos los 10 créditos de Tiempo real con success.

Si la consulta en directo falla, la API devuelve los datos guardados en nuestra base de datos. Lo reconoces en _realtime_mode.status, que entonces no es success. Tiempo real no se cobra en ese caso, como muestra también meta.request_credit_cost.

Tiempo real compensa cuando importa el estado de hoy. Por ejemplo, compruebas nuevos socios comerciales antes de firmar o ves quién puede representar a la empresa ahora mismo.

Buscamos cada día cuentas anuales recién publicadas. Sin embargo, las empresas tienen hasta doce meses después del cierre del ejercicio para publicarlas (§ 325 HGB), y muchas agotan el plazo. Algunas incumplen deliberadamente el plazo legal y publican aún más tarde.

Por eso, las cuentas más recientes suelen ser las del penúltimo año. Más en Actualidad.

Los tribunales de insolvencia suelen publicar sus anuncios el día de la resolución o poco después. Los obtienes con la función insolvency_publications, cada uno con tribunal, número de expediente y fecha.

La función news devuelve noticias de la web sobre la empresa, con título, fuente, fecha y enlace. Lo actuales que sean depende de cuándo se informó por última vez sobre la empresa. Para empresas pequeñas suele haber pocas noticias que encajen.

Muchos datos cambian con el tiempo. Por eso la API devuelve el estado actual y el historial uno junto a otro:

• current es el estado a día de hoy.
• history enumera cada estado inscrito con effective_from y effective_to. Si effective_to es null, el estado sigue vigente hoy.
• Las personas están en related_persons.current y related_persons.past, cada una con start_date y end_date.

Cada dato con historial procede de los registros y las publicaciones, por ejemplo del Chronologischer Abdruck (CD, extracto cronológico) del Handelsregister o de todas las cuentas anuales publicadas.

Así se ve en nuestro ejemplo para las reglas de representación de Hetzner Online GmbH. En la respuesta de ejemplo nombran al consejo de dirección hasta el 28 de julio de 2015 y a los administradores desde entonces:

La mayoría de las fechas vienen en el formato YYYY-MM-DD. Hasta dónde se remonta el historial se describe en Antigüedad e historial.

No todas las empresas tienen un valor para cada campo. La API lo muestra de dos maneras:

• null: no hay valor para este campo.
• []: la lista no tiene entradas, por ejemplo ningún anuncio de insolvencia.

Una función solicitada sin datos llega como null o [] y no cuesta nada.

En tu código, trata igual una clave ausente, null y [], porque algunos objetos vacíos llegan como []. Lee además los campos por su nombre, porque el orden de las claves no es fijo.

Si falta un valor, normalmente la empresa ni siquiera está obligada a publicarlo. Lo que exige la ley según forma jurídica y tamaño se describe en Disponibilidad de datos. Algunos datos los retenemos deliberadamente; llevan entonces redacted: true.

La API crece de forma aditiva. Los nuevos datos y funciones llegan como campos nuevos. Nunca eliminamos campos existentes, no los renombramos y no cambiamos ni su tipo ni su significado. Así cada versión sigue siendo compatible con la anterior.

Los cambios que romperían código existente solo llegan en una nueva versión de la API, por ejemplo en /v2. La versión actual funciona en /v1.

Por eso, haz que tu cliente ignore los campos desconocidos y trate los valores desconocidos como un caso general. Los campos y funciones nuevos aparecen en el Changelog.

Puedes usar Perfil de empresa, Documentos, Búsqueda y exportación y Signals con cualquier cuenta, incluso sin suscripción de créditos. Una suscripción de créditos trae créditos nuevos cada mes y desbloquea más datos:

La API omite sin error las funciones fuera de tu plan y no las cobra. Rechaza con 403 los perfiles de persona y los filtros de búsqueda fuera de tu plan, también sin coste. En Signals esto aplica a los temas que pides explícitamente; sin ellos, simplemente recibes todos los temas de tu plan.

Los precios y créditos de los planes están en la página de precios.