Een API voor bedrijfsgegevens kiezen: 8 criteria

1. De gedekte landen, in een gemeenschappelijk formaat

Maak een lijst van de landen van uw klanten en leveranciers, vandaag en over twee jaar. Controleer dan of elk land hetzelfde antwoordformaat heeft: een API die meerdere landen met verschillende formaten dekt, dwingt u evenveel integraties te schrijven.

Companies dekt Frankrijk, België, Zwitserland en het Verenigd Koninkrijk met hetzelfde formaat. Elk bedrijf heeft een globale identificatie, landcode en nationaal nummer: FR-552100554, BE-0417497106, CH-101374515, GB-00445790. Blokken die in een land niet bestaan, worden als niet beschikbaar aangegeven, zonder fout.

2. Identificatienummers en hun validatie

Een goede API accepteert nummers zoals uw gebruikers ze intypen (spaties, punten, voorvoegsels) en zegt precies wat er mis is: formaat, controlecijfer, bedrijf niet gevonden, bedrijf gesloten, nummers die niet overeenkomen.

Companies accepteert het SIREN, het SIRET, het Belgische ondernemingsnummer, het Zwitserse UID, het Britse bedrijfsnummer en Franse, Belgische en Zwitserse btw-nummers. De route GET /v2/validate controleert in één aanroep het formaat, het bestaan, de activiteit, de overeenstemming van de nummers en de registratie van het btw-nummer, en toont het resultaat van elke controle.

3. Actuele gegevens

Een fout dossier kost meer dan een ontbrekend: een verouderd adres, een opgeheven bedrijf dat als actief wordt getoond. Vraag hoe actualiteit zichtbaar wordt gemaakt en controleer enkele bedrijven die u goed kent.

Companies levert actuele gegevens, en de pagina Status van de dienst toont openbaar de toestand van de dienst en van de gegevens. Elk dossier vermeldt de status van het bedrijf (active, closed) en de einddatum als die er is.

4. Responstijd en volumes

In een formulier moet een suggestie aankomen terwijl de gebruiker typt. Bij bulkverwerking telt u de toegestane doorvoer en of aanroepen kunnen worden gegroepeerd.

Companies: autocomplete antwoordt in enkele milliseconden aan de serverzijde; het basisdossier weegt ongeveer 0,5 KB, en extra blokken worden alleen berekend wanneer erom wordt gevraagd. POST /v2/companies/batch leest tot 100 bedrijven in één aanroep, en ETag-headers vermijden dat een ongewijzigd dossier opnieuw wordt gelezen. De doorvoer loopt van 100 verzoeken per minuut (Free) tot 1.000 (Standard) en 10.000 (Pro), zonder maandelijks quotum.

5. De beschikbaarheidsgarantie (SLA)

Maak onderscheid tussen een streefdoel en een verbintenis: alleen een schriftelijke SLA, met een definitie van onbeschikbaarheid en compensatie, beschermt u. Controleer ook of er een openbare statuspagina bestaat, met de incidentgeschiedenis.

Companies publiceert zijn service level agreement: 99,9% maandelijkse beschikbaarheid gegarandeerd met het Pro-abonnement, met een tegoed van 10 tot 50% van het maandabonnement als de verbintenis niet wordt nagekomen; hetzelfde streefdoel van 99,9%, zonder tegoed, met Standard; een inspanningsverbintenis met het gratis abonnement. Een minuut telt als onbeschikbaar wanneer de dienst serverfouten geeft of niet binnen 10 seconden antwoordt. De pagina Status van de dienst toont de status en de incidentgeschiedenis.

6. Duidelijke prijzen en een gratis abonnement

Een prijs per credit of per geraadpleegd dossier is moeilijk te voorspellen naarmate het gebruik groeit. Kijk wat er gebeurt bij tien keer uw huidige volume, en of u dankzij een gratis abonnement kunt testen zonder bankkaart.

Companies heeft drie abonnementen met een vaste prijs, gepubliceerd op de pagina met prijzen: Free voor € 0, Standard voor € 19 excl. btw per maand, Pro voor € 129 excl. btw per maand, met 20% korting bij jaarlijkse facturering. Geen enkel abonnement heeft een maandelijks quotum: de limieten gelden voor de doorvoer per minuut. Het gratis abonnement, zonder bankkaart, geeft toegang tot elke route.

7. Documentatie, testen en fouten

Open de documentatie voordat u tekent: elke route hoort haar parameters, een voorbeeldverzoek en -antwoord en de lijst van haar fouten te hebben. Stabiele foutcodes en een hulpmiddel om zonder code te testen besparen dagen integratie.

Companies documenteert elke route met haar parameters, een voorbeeld en haar fouten, en levert een OpenAPI-specificatie. De demo op de startpagina bevraagt de API zonder account; de Tester in uw klantomgeving verstuurt elk verzoek met uw account. Alle fouten hebben hetzelfde formaat, met een stabiele code (invalid_identifier, rate_limit_exceeded…) en een link naar de documentatie; de headers X-RateLimit-Remaining en Retry-After tonen de resterende doorvoer en de wachttijd.

8. AVG en hosting in Europa

Vraag waar de gegevens passeren en worden opgeslagen, wat er van uw verzoeken wordt bewaard en wie de subverwerkers zijn. Voor een Europese softwareleverancier is dat vaak een eis van uw eigen klanten.

Companies wordt uitgegeven door een Frans bedrijf. De API draait op een server in Frankrijk, en de accountdatabase wordt gehost in de Europese Unie, in Frankfurt. Het verzoeklogboek bewaart de datum, het pad, de status en de duur, nooit de inhoud van de antwoorden. Bij bestandsverrijking verlaat alleen de kolom met identificatienummers uw computer. Het privacybeleid somt de verwerkingen, bewaartermijnen en subverwerkers op.

Bonus: opvolging van wijzigingen

Een bedrijf controleren op de dag van de aanmelding is niet genoeg: het kan stoppen, verhuizen of in een insolventieprocedure terechtkomen. Een API die u op wijzigingen wijst, bespaart u het regelmatig opnieuw lezen van al uw dossiers.

Companies bevat opvolging in elk abonnement: 2 bedrijven met het gratis account, 1.000 met Standard, 10.000 met Pro. Elke wijziging (status, naam, adres, activiteit, insolventiesignaal, bekendmaking, sancties) wordt een gebeurtenis, verstuurd naar een ondertekende webhook en per e-mail, en gedurende 90 dagen leesbaar met GET /v2/events. Het artikel Controleren of een Frans bedrijf in liquidatie is toont een toepassing.

Voer de test uit in één aanroep

De eenvoudigste manier om te vergelijken is hetzelfde verzoek uit te voeren op een bedrijf dat u kent. Met Companies, een Belgisch dossier met adres, btw-nummer en signalen:

curl "https://companies.jsonpage.com/v2/companies/BE-0417497106?include=address,vat,signals" \
  -H "X-API-Key: $COMPANIES_API_KEY"

Maak een gratis account aan om uw sleutel te krijgen, en ga daarna het bovenstaande raster door op uw eigen gevallen. Antwoorden op vragen over abonnementen en beschikbaarheid staan in de FAQ.

Verder lezen

• SIRENWat is een SIREN-nummer en hoe vindt u hetHet formaat van 9 cijfers, wie er een krijgt, waar het staat en hoe u het SIREN van een bedrijf op naam vindt.
• BTWFrans btw-nummer: formaat en controleDe Franse, Belgische en Zwitserse formaten, de vermeldingen op de factuur en de controle vóór het factureren.
• INSOLVENTIEPROCEDURESControleren of een Frans bedrijf in liquidatie isLiquidation, redressement en sauvegarde uitgelegd, de signalen om op te letten en meldingen over uw klanten en leveranciers.