Schnittstelle für Ihre Projekte und Apps!
Einführung
Die FastBill API ist als XML/JSON Webservice angelegt, bei dem alle Ressourcen über eine zentrale URL angesprochen werden. Alle API Anfragen werden als POST Requests mit XML oder JSON formatiertem Body an die Service-URL gesendet. Diese Dokumentation beschreibt die Kommunikation im XML Format
https://my.fastbill.com/api/1.0/api.php
Jeder Request wird SSL-verschlüsselt übertragen
Authentifizierung
Die Standard-Authentifizierung geschieht über den bestehenden FastBill Benutzer (E-Mail Adresse) und den API-Key des betreffenden FastBill-Kontos. So erhalten Nutzer einen einfachen Zugang in den eigenen Account.
API-Zugriffe sind zustandslos, d.h. es werden keine Sitzungen gespeichert. Bei jedem Request müssen die E-Mail Adresse und der API- Key übermittelt werden.
Die Authentifizierung wird mithilfe der HTTP Basic Authentification durchgeführt:
curl -v -X POST \
-u {E-Mail-Adresse}:{API-Key} \
-H 'Content-Type: application/xml' \
-d '{xml body}' \
https://my.fastbill.com/api/1.0/api.php
Für Anbieter von Add-Ons oder Mobile Apps ist es möglich, die Authentifizierung auf Basis der E-Mail Adresse und Passworts des aktuellen Nutzers durchzuführen. Diese externen Tools erhalten separate „Add-On Zugangsdaten“ (eigene E-Mail Adresse und API-Key), zur Authentifizierung des Services, müssen jedoch separat die Zugangsdaten des Nutzers an die FastBill API übermitteln.
API-Zugriffe sind zustandslos, d.h. es werden keine Sitzungen gespeichert. Bei jedem Request müssen die Zugangsdaten des Add-Ons sowie diejenigen des Nutzers übermittelt werden.
Die Authentifizierung wird mithilfe der HTTP Basic Authentification sowie zusätzlicher HTTP Header-Informationen durchgeführt:
curl -v -X POST \
-u {E-Mail-Adresse}:{API-Key} \
-H 'X-Username: {E-Mail Adresse des Benutzers}'\
-H 'X-Password: {Passwort des Benutzers}' \
-H 'Content-Type: application/xml' \
-d '{xml body}' \
https://my.fastbill.com/api/1.0/api.php
Struktur eines Requests
Der Header beinhaltet immer:
Beispiel:
curl -v -X POST \
-u {E-Mail-Adresse}:{API-Key} \
-H 'Content-Type: application/xml' \
-d '{xml body}' \
https://my.fastbill.com/api/1.0/api.php
Der Body eines Requests / einer Response folgt stets demselben Schema. Folgende Bestandteile bilden den Rahmen:
Beispiel für erfolgreiches Abrufen der Daten eines Kunden:
Request
<?xml version="1.0" encoding="utf-8"?> <FBAPI> <SERVICE>customer.get</SERVICE> <FILTER> <CUSTOMER_ID>5376</CUSTOMER_ID> </FILTER> </FBAPI>
Response
<?xml version="1.0" encoding="utf-8"?> <FBAPI> <REQUEST> <SERVICE>customer.get</SERVICE> <FILTER> <CUSTOMER_ID>5376</CUSTOMER_ID> </FILTER> </REQUEST> <RESPONSE> <CUSTOMERS> <CUSTOMER> ... </CUSTOMER> </CUSTOMERS> </RESPONSE> </FBAPI>
Beispiel für fehlerhaftes Anlegen eines Kunden:
Request
<?xml version="1.0" encoding="utf-8"?> <FBAPI> <SERVICE>customer.create</SERVICE> <DATA> ... </DATA> </FBAPI>
Response
<?xml version="1.0" encoding="utf-8"?> <FBAPI> <REQUEST> <SERVICE>customer.create</SERVICE> <DATA> ... </DATA> </REQUEST> <RESPONSE> <ERRORS> <ERROR> ... </ERROR> </ERRORS> </RESPONSE> </FBAPI>
Weitere Hinweise:
Limitierungen
Die maximale Anzahl der API-Zugriffe pro Account (API-Calls) ist abhängig von dem gewählten Tarif:
Die maximale Anzahl von Elementen beim Abruf einer Liste beträgt 100, unabhängig vom gewählten „LIMIT“-Wert.
Webhooks: die Verwendung von Webhooks wird nur in den Tarifen Pro und Premium unterstützt.