Monsum API Documentation

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://app.monsum.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://app.monsum.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://app.monsum.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://app.monsum.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.

Monsum API