Notions de base

Le paramètre q de fetch-organization accepte trois types de saisie. Les exemples de cette page sont des requêtes pour Hetzner Online GmbH, Ansbach HRB 6089 :

Le numéro de registre seul ne suffit pas, car chaque tribunal du registre attribue ses propres numéros. L’ordre, en revanche, est libre : dans l’exemple, HRB 6089 Ansbach trouve la même entreprise.

Si l’API ne trouve aucune entreprise, elle répond 404 et ne facture rien. Pour une saisie approximative, il y a le mode IA (ai_search=on-default) : il trouve l’entreprise même à partir de fragments du nom et fait des recherches sur le web. Il coûte 20 crédits supplémentaires, même s’il ne trouve aucune entreprise. Pour obtenir plusieurs candidats d’un coup, utilise Recherche & Export.

Chaque profil d’entreprise contient les données de base, notamment nom, forme juridique, statut, inscription au registre, adresse, objet, secteur, capital et règles de représentation. Tout le reste se demande sous forme de fonctionnalité, par exemple related_persons pour les dirigeants ou financial_kpi pour les indicateurs financiers.

Tu passes plusieurs fonctionnalités avec un feature répété ou sous forme de liste : features=related_persons,financial_kpi. Chaque fonctionnalité apparaît dans la réponse sous sa propre clé. Seule publications s’y appelle history.

L’API ignore les noms inconnus sans message d’erreur : vérifie donc l’orthographe. Les fonctionnalités que ton plan n’inclut pas sont omises et non facturées.

Toutes les fonctionnalités avec leurs prix figurent dans fetch-organization, chaque champ dans le Catalogue de données.

Les requêtes de données coûtent des crédits. Pour un profil d’entreprise, ces règles s’appliquent :

• Le prix de base de 5 crédits s’applique quand l’API renvoie une entreprise.
• Une fonctionnalité ne coûte des crédits que si elle renvoie des données dans la réponse. Une fonctionnalité vide est gratuite, y compris insolvency_publications sans entrées.
• Le mode temps réel et le mode IA ne sont pas des fonctionnalités mais des suppléments avec leurs propres règles :
  • Le mode temps réel coûte 10 crédits supplémentaires dès que la récupération en direct réussit. Cela vaut aussi quand elle ne montre rien de nouveau.
  • Le mode IA coûte 20 crédits supplémentaires, même s’il ne trouve aucune entreprise. Le supplément n’est supprimé que si l’API interrompt la requête avec 408 parce qu’elle dure trop longtemps.
• Toutes les autres erreurs ne coûtent rien.

La règle de chaque fonctionnalité figure dans Facturation, les prix dans fetch-organization.

Un exemple : les données de base avec related_persons et financial_kpi coûtent 5 + 2 + 1 = 8 crédits si les deux fonctionnalités renvoient des données.

Avant chaque requête, l’API vérifie si ton solde couvre le prix le plus élevé possible. Sinon, l’API répond 402 et ne facture rien. Ce qui a réellement été facturé figure dans meta.request_credit_cost, ton solde ensuite dans meta.credits_remaining.

Tu reçois des crédits comme crédits de départ, chaque mois avec un abonnement de crédits, ou ponctuellement comme crédits de recharge. Sans abonnement de crédits, les crédits de départ et de recharge sont valables 30 jours ; avec un abonnement actif, ils n’expirent pas. Tout le reste figure dans Facturation.

Par défaut, le profil d’entreprise provient de notre base de données. L’actualité d’une information dépend de sa source.

Nous tenons à jour dans notre base, à partir du registre, les données de base, les personnes et les publications du registre. C’est rapide et suffisant pour la plupart des usages.

Avec le mode temps réel (realtime_mode=handelsregister-default), l’API récupère en direct l’Aktueller Abdruck (AD, extrait actuel) du Handelsregister (registre du commerce) au moment de ta requête et le renvoie en JSON. Tu obtiens aussi les personnes actuellement inscrites dans related_persons.current, sans payer la fonctionnalité.

Le résultat de la récupération en direct figure dans _realtime_mode.status. Nous ne facturons les 10 crédits du mode temps réel qu’en cas de success.

Si la récupération en direct échoue, l’API renvoie les données enregistrées dans notre base. Tu le reconnais à _realtime_mode.status, qui n’est alors pas success. Le mode temps réel n’est alors pas facturé, comme le montre aussi meta.request_credit_cost.

Le mode temps réel vaut la peine quand l’état du jour compte. Par exemple, tu vérifies de nouveaux partenaires commerciaux avant de signer, ou vois qui peut représenter l’entreprise en ce moment.

Nous recherchons chaque jour les comptes annuels nouvellement publiés. Les entreprises disposent toutefois de douze mois après la clôture de l’exercice pour les publier (§ 325 HGB), et beaucoup utilisent tout le délai. Certaines dépassent délibérément le délai légal et publient encore plus tard.

Les derniers comptes portent donc souvent sur l’avant-dernière année. Plus d’informations dans Actualité.

Les tribunaux d’insolvabilité publient généralement leurs avis le jour de la décision ou peu après. Tu les obtiens via la fonctionnalité insolvency_publications, chacun avec tribunal, numéro de dossier et date.

La fonctionnalité news renvoie des actualités sur l’entreprise issues du web, avec titre, source, date et lien. Leur actualité dépend de la date à laquelle on a parlé de l’entreprise pour la dernière fois. Pour les petites entreprises, il y a souvent peu d’articles correspondants.

De nombreuses informations changent avec le temps. L’API renvoie donc l’état actuel et l’historique côte à côte :

• current est l’état à ce jour.
• history liste chaque état inscrit avec effective_from et effective_to. Si effective_to vaut null, l’état est encore valable aujourd’hui.
• Les personnes figurent dans related_persons.current et related_persons.past, chacune avec start_date et end_date.

Chaque information avec historique provient des registres et des publications, par exemple du Chronologischer Abdruck (CD, extrait chronologique) du Handelsregister ou de l’ensemble des comptes annuels publiés.

Voici ce que cela donne dans notre exemple pour les règles de représentation de Hetzner Online GmbH. Dans l’exemple de réponse, elles désignent le directoire jusqu’au 28 juillet 2015, puis les gérants :

La plupart des dates sont au format YYYY-MM-DD. Jusqu’où remonte l’historique est décrit dans Ancienneté et historique.

Toutes les entreprises n’ont pas une valeur pour chaque champ. L’API l’indique de deux façons :

• null : il n’y a pas de valeur pour ce champ.
• [] : la liste n’a pas d’entrées, par exemple aucune publication d’insolvabilité.

Une fonctionnalité demandée sans données arrive sous forme de null ou [] et ne coûte rien.

Dans ton code, traite de la même façon une clé absente, null et [], car certains objets vides arrivent sous forme de []. Lis aussi les champs par leur nom, car l’ordre des clés n’est pas fixe.

Si une valeur manque, l’entreprise n’est généralement pas tenue de la publier. Ce que la loi exige selon la forme juridique et la taille est décrit dans Disponibilité des données. Nous retenons délibérément certaines informations ; elles portent alors redacted: true.

L’API évolue de manière additive. Les nouvelles données et fonctionnalités arrivent sous forme de nouveaux champs. Nous ne supprimons jamais de champs existants, nous ne les renommons pas et nous ne changeons ni leur type ni leur signification. Chaque version reste ainsi rétrocompatible.

Les changements qui casseraient du code existant n’arrivent que dans une nouvelle version de l’API, par exemple sous /v2. La version actuelle tourne sous /v1.

Fais donc en sorte que ton client ignore les champs inconnus et traite les valeurs inconnues comme un cas général. Les nouveaux champs et fonctionnalités sont listés dans le Changelog.

Tu peux utiliser Profil d’entreprise, Documents, Recherche & Export et Signals avec chaque compte, même sans abonnement de crédits. Un abonnement de crédits apporte de nouveaux crédits chaque mois et débloque davantage de données :

L’API omet sans erreur les fonctionnalités hors de ton plan et ne les facture pas. Elle refuse avec 403 les profils de personne et les filtres de recherche hors de ton plan, également sans frais. Pour Signals, cela vaut pour les thèmes que tu demandes explicitement ; sinon, tu obtiens simplement tous les thèmes de ton plan.

Les prix et crédits des plans figurent sur la page des tarifs.