FastBill API

Schnittstelle für Ihre Projekte und Apps!

Grundlagen

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

Allgemeine Service-URL:

https://my.fastbill.com/api/1.0/api.php

Jeder Request wird SSL-verschlüsselt übertragen


Authentifizierung

Login in eigenen Acccount

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

Login im Namen eines Nutzers

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:

  • HTTP-Verb
  • Authentifizierung
  • Content-Type

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:

  • FBAPI: Hauptknoten, beinhaltet alle XML-Angaben (bei JSON Format nicht benötigt!)
  • SERVICE: Der Dienstname, der auf dem Server angesprochen werden soll
  • LIMIT: Parameter zur Begrenzung der Anzahl der Elemente bei Abfrage einer Liste (Standard 10)
  • OFFSET: Parameter zur Festlegung des ersten Elements bei Abfrage einer Liste
  • FILTER: Parameter zur Adressierung / Filterung der betreffenden Ressourcen
  • DATA: Daten, die für die gewünschte Action übermittelt werden sollen
  • REQUEST: zurückgelieferte, wiederholte Eingabedaten
  • RESPONSE: zurückgelieferte Ressourcen-Daten
  • ERRORS: zurückgelieferte Fehlermeldungen

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:

  • SERVICE: Der Dienstname (z.B. customer, user, invoice, product) wird in Kleinbuchstaben geschrieben. Gefolgt von einem Punkt und dem Methodennamen (get, create, update, delete).
  • Bei der Response werden alle Angaben des Requests (LIMIT,OFFSET,FILTER, DATA) weiterhin mitgeführt und durch die Rückgaben (RESPONSE, ERRORS) ergänzt.

Limitierungen

Zur Sicherheit vor ungeplanten Lastspitzen oder ungewollten Endlosschleifen wird die Anzahl der API-Zugriffe pro Benutzer auf 1000 pro Minute begrenzt.

Die maximale Anzahl von Elementen beim Abruf einer Liste beträgt 100, unabhängig vom gewählten „LIMIT“-Wert.

support@fastbill.com
© 2016 FastBill GmbH