Monsum API

Schnittstelle für Ihre Projekte und Apps!

Grundlagen

Einführung

Die Monsum 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 Monsum Benutzer (E-Mail Adresse) und den API-Key des betreffenden Monsum 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 Monsum 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.
  • Bei der Eingabe mehrerer IDs bei einem der _.get Calls sieht die Struktur des Array aus wie folgt: JSON - "INVOICE_ID":["id1", "id2"] // XML - id1id2

Limitierungen

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

support@monsum.com
© 2016 FastBill GmbH