Grundlagen

Authentifizierung

Für die Authentifizierung wird der API-Schlüssel benötigt, den jeder MOCO-Nutzer in seinem Profil > Integrationen findet. Dieser Schlüssel muss in jedem Aufruf als sogenannter Authorization-Header enthalten sein. 

curl -X GET \
  'https://{domain}.mocoapp.com/api/v1/projects.json' \
  -H 'Authorization: Token token={api-key}'

API-Schlüssel via API

Es besteht auch die Möglichkeit, den API-Schlüssel direkt über die API abzufragen. Dies ist der einzige Aufruf, bei dem der Authorization-Header nicht übergeben wird. Stattdessen ist die Übermittlung von E-Mail und Passwort notwendig:

curl -X POST \
  https://{domain}.mocoapp.com/api/v1/session \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'email=max@muster.de&password=meinpasswort'

Die Antwort lautet wie folgt:

{
    "api_key": "3783278b83d83f3caa339393",
    "user_id": 12345678
}

Rate Limiting

Als sicheres Limit können 15 Abfragen innerhalb von 15 Sekunden angenommen werden. Anschliessend wird mit einem 429 (Too Many Requests) Status Code geantwortet.

Pagination

Die Antworten werden seitenweise (pagination) zurückgegeben. In der Regel sind 100 Einträge pro Anfrage enthalten. Über Header-Felder kann die Anzahl der Seiten abgefragt werden. Die URLs für die nächsten Seiten sind im Link-Header definiert:
  • X-Page – 3
  • X-Per-Page – 100
  • X-Total – 415
  • Link – <https://{domain}.mocoapp.com/api/v1/projects.json?page=4>; rel="next"

Folgendes Beispiel zeigt den Link-Header bei Abfrage der 3. Ergebnisseite:

Link: <https://{domain}.mocoapp.com/api/v1/projects.json?page=4>; rel="next"
Falls kein Link-Header mit rel="next" vorhanden ist, befindet man sich auf der letzten Seite.

Sortierung

Die Sortierung kann über den Parameter sort_by gesteuert werden und besteht aus dem Feldnamen und optional der Sortierreihenfolge (Standard: aufsteigend). Alle möglichen Sortierfelder sind in den jeweiligen Bereichen aufgelistet.

Beispiele:

sort_by=title
sort_by=date desc

Eigene Felder

MOCO unterstützt eigene Felder auf vielen Ressourcen. Diese sind auch über die API lesend und schreibend über das Attribut custom_properties verfügbar.

"custom_properties": {
    "UID": "123-UID-456",
    "Branche": "Automotive"
},

Die Parameter werden so übergeben, wie sie benannt sind:

curl -X POST \
  https://{domain}.mocoapp.com/api/v1/customers \
  -H 'authorization: Token token={api-key}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'name=Beispiel AG&currency=CHF&custom_properties[Branche]=Automotive'

Alle Werte werden als "String" übergeben, ausser für die "Mehrfachauswahl" wird ein Array erwartet:

curl -X POST \
  https://{domain}.mocoapp.com/api/v1/customers \
  -H 'authorization: Token token={api-key}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'custom_properties[Branchen][]=Automotive&custom_properties[Branchen][]=Banking'

  • Einzeilige Eingabe – "Automotive"
  • Mehrzeilige Eingabe – "Ein mehrzeiliger Inhalt..."
  • Link – "https://www..."
  • Ja/Nein – "0", "1" (0 = Nein, 1 = Ja)
  • Einfachauswahl – "Wert"
  • Mehrfachauswahl – "Wert"
ACHTUNG: Wenn eigene Felder beschrieben werden, müssen alle bestehenden Felder übermittelt werden, da sonst die nicht übermittelten entfernt werden.

Webhooks (BETA)

Mithilfe von Webhooks können Integrationen in nahezu Echtzeit realisiert werden.  Ereignisse in MOCO werden dazu abonniert. Wenn eines dieser Ereignisse ausgelöst wird, sendet MOCO einen HTTPS-POST-Payload an die konfigurierte URL des Webhooks inkl. Signatur des Payloads (mus. So kann MOCO als Absender verifiziert werden. Zusätzliche Header-Angaben erlauben die Zuordnung des Payloads.

  • Payload via HTTPS-POST
  • Objekt via X-Moco-Target – (Activity, Customer, Project, ...)
  • Ereignis via X-Moco-Event – (create, update, delete, archive, ...)
  • Signatur via X-Moco-Signature
  • Der Empfänger muss innerhalb von 10 Sekunden bestätigen!

Folgendes Beispiel zeigen die Header bei einem neuen Zeiteintrag:

X-Moco-Target: Activity
X-Moco-Event: create
X-Moco-Signature: f457bffc50e9b63f455ab107c55f2f61956550aa5525c2cfe07f574014bd8a9e

TIPP: Für die Entwicklung hilft https://requestb.in – hier können temporäre HTTPS-URLs generiert und ankommende Daten analysiert werden.

ACHTUNG: Die Funktion ist noch in der Beta-Phase. Aktuell stehen die Zeiteinträge (Activity) mit den Ereignissen (create, update, delete) zur Verfügung. Für das Setup uns direkt in der App kontaktieren.

Mehr zu API...
30 Tage gratis

Account sofort startbereit. Voller Funktionsumfang. Ohne Zahlungsangaben.