Dokumentation / Beispiele

API BCE Beispiele: Aufrufe in cURL, JavaScript und Python

Beispiele für die API BCE zum Kopieren: Unternehmensdaten, Suche nach Name oder Adresse, USt-Prüfung über VIES und NACE-Codes, in cURL, JavaScript und Python.

Copy-paste recipes for the most common tasks. Every call is authenticated (see Authentication).

Fetch an enterprise#

curl https://companybelgium.be/api/v2/enterprise/1033.022.383 \
  -H "X-API-Key: $API_BCE_KEY" \
  -H "X-API-Secret: $API_BCE_SECRET"

Search by company name#

curl "https://companybelgium.be/api/v2/denominations?q=espero&limit=5" \
  -H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET"

Search by address#

curl "https://companybelgium.be/api/v2/search/address?postalCode=1080&street=Colonne" \
  -H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET"

Validate an EU VAT number#

curl "https://companybelgium.be/api/v2/vat/BE1033022383" \
  -H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET"

Search NACE activity codes#

curl "https://companybelgium.be/api/v2/naces?q=programmation&version=2008&limit=10" \
  -H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET"
ℹ️

Prefer to explore interactively? Open the API Playground and fire real requests from your browser.

Beispiele der API BCE zu Abläufen kombinieren#

Einzelne Aufrufe sind selten das Ziel. Erst ihre Kombination ergibt einen nützlichen Ablauf. Die Beispiele oben decken deshalb die Bausteine ab: Datensatz, Namenssuche, Adresssuche, USt-Prüfung und NACE-Suche. Im Folgenden sehen Sie, wie Teams diese Bausteine verbinden.

Kundenanlage im CRM

Zuerst tippt der Nutzer einen Namen ein. Ihr Formular ruft dabei /denominations ab, sobald zwei Zeichen vorliegen. Danach wählt der Nutzer einen Treffer, und Sie laden den vollständigen Datensatz über /enterprise/{num}. Schließlich übernehmen Sie Sitz, Rechtsform und Tätigkeiten in das CRM. So entstehen saubere Stammdaten ohne Tippfehler.

Rechnung an einen EU-Kunden

Vor dem Versand prüfen Sie die USt-Nummer über /vat/{vatNumber}. Ist isValid wahr, speichern Sie zusätzlich requestDate als Nachweis. Ist die Nummer ungültig, stoppen Sie den Versand und informieren die Buchhaltung.

Marktanalyse nach Tätigkeit

Sie suchen zuerst passende NACE-Codes über /naces. Danach ordnen Sie Ihre Kunden über deren Tätigkeiten diesen Codes zu. Außerdem finden Sie über /search/address alle Unternehmen an einer Adresse.

Beispiele sicher übernehmen#

  • Ersetzen Sie die Umgebungsvariablen durch Ihre eigenen Werte, nie durch fest codierte Schlüssel.
  • Prüfen Sie den HTTP-Status, bevor Sie data lesen.
  • Kodieren Sie Suchbegriffe korrekt in der URL, besonders Umlaute und Leerzeichen.
  • Testen Sie jedes Beispiel zuerst gegen https://api-bce.be/test/v2.
  • Ergänzen Sie eine Wiederholung bei 429 und 5xx, bevor Sie live gehen.

Die Beispiele verwenden absichtlich das Unternehmen des Herausgebers. Für Ihre Tests eignen sich dagegen die fiktiven Nummern aus dem Testmodus besser. Sie liefern nämlich stabile, vorhersehbare Antworten.

Von Beispielen zum Produktivcode#

Die Beispiele zeigen einzelne Aufrufe ohne Fehlerbehandlung. Für den Livebetrieb ergänzen Sie deshalb drei Dinge. Zuerst eine Zeitüberschreitung, damit ein hängender Aufruf Ihren Dienst nicht blockiert. Dann eine Wiederholung mit Backoff für 429 und 5xx. Schließlich ein Protokoll mit Endpunkt, Status und Dauer. Mit diesen Ergänzungen wird aus einem Beispiel ein verlässlicher Baustein.

Fassen Sie außerdem alle Aufrufe in einer gemeinsamen Funktion zusammen. Die Header stehen dann nur an einer Stelle.

Bewahren Sie außerdem die Antworten der Beispiele als Testdaten auf. So prüfen Sie Ihren Parser offline und ohne Kontingent. Aktualisieren Sie diese Dateien jedoch, sobald das Änderungsprotokoll neue Felder meldet.

Prüfen Sie zudem, ob ein Beispiel einen bestimmten Tarif voraussetzt. Jahresabschlüsse und Organe stehen zum Beispiel nur mit API Pro zur Verfügung.

Häufige Fragen zu den Beispielen der API BCE#

Gibt es ein offizielles SDK für die API BCE?

Die Dokumentation beschreibt kein offizielles SDK. Sie können jedoch aus der OpenAPI-Spezifikation einen typisierten Client erzeugen.

Kann ich die Beispiele ohne Schlüssel ausführen?

Im API-Playground ja, mit dem Demo-Schlüssel. In Ihrem eigenen Code brauchen Sie dagegen einen Test- oder Live-Schlüssel.

Warum enthalten manche Beispielwerte drei Punkte?

Werte, die nicht sicher feststehen, sind als ... notiert. Die echte Antwort enthält an dieser Stelle die tatsächlichen Daten.