Synchroniser des entreprises néerlandaises dans Exact Online

Où atterrissent les données

Une relation Exact Online est un Account sous crm/Accounts, propre à chaque administration :

POST https://start.exactonline.nl/api/v1/{division}/crm/Accounts

Les champs qu’une recherche permet de renseigner :

Ce numéro de rue est la première source d’erreurs. Nous renvoyons street, houseNumber et houseNumberAddition séparément, alors qu’Exact attend une seule ligne. Concaténez dans cet ordre et conservez aussi les éléments séparés dans votre propre base, sinon vous ne pourrez plus jamais faire de rapprochement fiable sur le numéro de rue.

Le point d’intégration, c’est votre script

Il n’existe aucun connecteur entre nous et Exact. Ce que vous construisez est un petit intergiciel, dans le langage de votre choix, en quatre étapes :

1. Un numéro KvK arrive, depuis un formulaire, votre CRM ou un fichier d’import.
2. GET /v1/lookup/{kvkNumber}?enrich=true de notre côté, en vérifiant isActive.
3. Une détection de doublon dans Exact, avec un filtre OData sur le numéro KvK.
4. POST si le compte est absent, PUT sur le GUID existant s’il est présent.

L’étape 3 est celle que l’on saute, et c’est précisément pourquoi les administrations Exact se remplissent de relations en double :

GET /api/v1/{division}/crm/Accounts?$filter=ChamberOfCommerce eq '68750110'&$select=ID,Name
Authorization: Bearer {exact_access_token}
Accept: application/json

Aucun résultat : on crée.

{
  "Name": "Acme B.V.",
  "ChamberOfCommerce": "68750110",
  "VATNumber": "NL123456789B01",
  "AddressLine1": "Keizersgracht 123",
  "Postcode": "1015 CJ",
  "City": "Amsterdam",
  "Country": "NL"
}

Pour charger des milliers de comptes d’un coup, voir l’article détaillé : enrichissement par lots des données d’entreprises néerlandaises.

D’où vient le numéro KvK

Exact est la destination, pas la source. Quelque part en amont, une personne choisit une entreprise. Trois situations se rencontrent en pratique, avec chacune des conséquences différentes pour votre synchronisation :

• Un formulaire d’inscription sur votre propre site. Branchez le widget sur le champ KvK : le visiteur cherche par nom et vous recevez un numéro choisi, non ressaisi.
• Votre CRM. Le numéro a été validé à la capture du prospect, la synchronisation vers Exact n’est donc qu’une étape de copie. C’est la variante la plus sereine, car la détection de doublons a déjà eu lieu plus haut dans la chaîne.
• Un fichier d’import fourni par un comptable ou issu d’un ancien système. Ici, la normalisation est l’étape zéro, pas un luxe : cette colonne contient forcément du texte, des espaces et des cellules vides.

Si vous n’avez qu’un nom d’entreprise, ajoutez d’abord une étape de recherche avec GET /v1/search?.... Elle renvoie des candidats avec leur numéro KvK, et une personne en choisit un. Sélectionner automatiquement le premier résultat pour un nom comme « Van der Berg Holding » donne systématiquement le mauvais compte, et un mauvais compte dans votre comptabilité ne se révèle qu’à la première facture.

Ce qui casse réellement en production

Les jetons de rafraîchissement rotatifs. Exact utilise des jetons d’accès de courte durée et un jeton de rafraîchissement remplacé à chaque utilisation. Si deux processus rafraîchissent en même temps, l’un gagne et l’autre est déconnecté définitivement. Stockez les jetons de façon centralisée, rafraîchissez sous verrou et enregistrez le nouveau jeton de rafraîchissement avant de l’utiliser. C’est la cause la plus fréquente d’une intégration Exact morte le lundi matin.

Les numéros KvK sans leur zéro initial. Les anciens numéros KvK commencent par un zéro. Faites passer les données par Excel ou une colonne numérique et 01234567 devient 1234567 : votre filtre OData ne trouve plus rien. Complétez toujours à huit chiffres par la gauche avant de chercher ou d’écrire.

Des valeurs ChamberOfCommerce polluées par l’historique. Comme Exact ne valide pas ce champ, il contient de tout : des numéros avec des points, des espaces, préfixés de « KVK », et parfois un numéro d’établissement à 12 chiffres. Votre détection de doublons à filtre exact rate ces enregistrements et crée une seconde relation. Normalisez d’abord : ne gardez que les chiffres, complétez à huit par la gauche, et nettoyez le désordre existant lors d’une passe unique.

Les limites de débit des deux côtés pendant un import. Exact comptabilise par minute et par jour et l’indique dans les en-têtes X-RateLimit de chaque réponse. De notre côté, il existe aussi une limite par minute. En important des milliers de relations, vous butez sur la plus lente des deux. Lisez les en-têtes d’Exact plutôt que de réessayer à l’aveugle, et utilisez POST /v1/lookup/batch chez nous pour que les recherches ne soient pas le goulot d’étranglement.

Une entreprise qui n’existe plus. Sur NOT_FOUND, l’immatriculation a été radiée. Ne créez pas de relation, et ne supprimez pas non plus automatiquement une relation existante : des factures et des écritures comptables en dépendent. Signalez-la dans votre propre système et laissez une personne décider.