Grundkonzepte

Authentifizierung

Alle API-Anfragen müssen ein gültiges Session-Token im Authorization-Header enthalten. Dieses Token kann über den Login-Endpoint bezogen werden und bleibt 24 Stunden gültig. Es empfiehlt sich, den Login-Aufruf erst dann auszulösen, wenn die eigentliche Anfrage eine 401-Unauthorized-Antwort zurückgibt. Dieser Ansatz vereinfacht die Token-Verwaltung, da ein neues Token nur bei Bedarf angefordert wird.

Feeds

Statusänderungen treten bei Vereinbarungen, Rechnungen und Transaktionen wesentlich häufiger auf als bei einmaligen Zahlungen. Da kein Ereignis verpasst werden soll und mehrere Webhooks aufgrund von Netzwerklatenz möglicherweise nicht in der richtigen Reihenfolge eintreffen, stellt Twikey "Feeds" oder Warteschlangen bereit, die im Wesentlichen eine Liste von Ereignissen darstellen, die noch nicht empfangen wurden.

Jeder Datenfeed (oder Ereignis-Warteschlange) enthält die letzte Sequenznummer (X-LAST), die es Clients ermöglicht, ab einem bestimmten Punkt im Ereignisstrom fortzufahren (über den Request-Header X-RESUME-AFTER). Dieser Mechanismus ist besonders nützlich für die Fehlerbehandlung oder beim Wiederverbinden nach einer Unterbrechung (und auch sehr hilfreich beim Testen).

Den Feed so lange lesen, bis keine Einträge mehr vorhanden sind. Der entscheidende Punkt ist, bis keine weiteren Updates verfügbar sind zu lesen. Dies stellt sicher, dass jedes Update ordnungsgemäß verarbeitet wird und nichts verloren geht.

Es ist zu vermeiden, dass mehrere Clients im Netzwerk gleichzeitig auf denselben Feed mit demselben API-Schlüssel zugreifen, da dies zu Race Conditions und inkonsistenten Daten führen kann. Falls gleichzeitiger Zugriff erforderlich ist, kommen folgende Ansätze in Betracht:

  • Separate API-Schlüssel verwenden: Jedem Client einen eigenen API-Schlüssel zuweisen. Zusätzliche Schlüssel können über das Twikey-Einstellungsmenü generiert werden.
  • Ein Master-Client-Muster implementieren: Einen einzelnen Client als Master bestimmen, der den Feed abruft. Andere Clients lesen die Daten aus einem gemeinsamen Datenspeicher, der vom Master verwaltet wird.

Da Sicherheit bei Zahlungen essenziell ist, hat Twikey entschieden, keine Details über Zahlungen in Webhooks weiterzugeben, sondern diese nur in Anfragen bereitzustellen, die von der Integrationsseite ausgehen. Twikey erlaubt spezifische "Detail"-Aufrufe zu einem Objekt, aber da diese nur eine Momentaufnahme des Objekts zu diesem Zeitpunkt darstellen (und sich das Objekt möglicherweise bereits geändert hat, bevor es verarbeitet wurde), wurden Rate-Limits eingeführt, um deren Verwendung einzuschränken.

Include-Parameter Einige Feeds unterstützen include-Parameter, um zusätzliche Details in der Antwort anzufordern. Die verfügbaren Includes variieren je Feed und sind in der API-Referenz dokumentiert. Standardmäßig liefern Feeds eine kompakte Antwort, um die Nutzlast zu minimieren.

Webhooks vs Polling

Twikey unterstützt zwei Arten von Integrationen.

Bei einer Push-Fetch-Architektur benachrichtigt Twikey über ein Ereignis mittels eines Webhooks. Dieser Webhook kann als Auslöser verwendet werden, um alle Ereignisse aus dem Feed (oder der Warteschlange) abzurufen und die internen Systeme zu aktualisieren.

Hinweis: Webhooks dienen ausschließlich als Benachrichtigungen und müssen entsprechend behandelt werden. Um doppelte Zustellungen aufgrund von Timeouts oder Wiederholungen zu vermeiden, ist sicherzustellen, dass jegliche interne Geschäftslogik asynchron verarbeitet wird.

Die Alternative ist eine Pull-Architektur, bei der Clients periodisch Updates von Twikey abrufen, um den aktuellen Stand innerhalb von Twikey zu erhalten. Diese Architektur eignet sich für Situationen, in denen keine eingehenden Webhooks erlaubt sind. Der Nachteil ist jedoch, dass es eine Verzögerung zwischen dem Zeitpunkt des Ereignisses in Twikey und dem Empfang des Ereignisses gibt.

Hybride Lösungen, bei denen Webhooks mit wiederkehrenden Pull-Abrufen kombiniert werden, sind selbstverständlich ebenfalls möglich.

Idempotenzschlüssel

Wenn eine Anfrage aufgrund eines Netzwerkproblems fehlschlägt, ist möglicherweise unklar, ob die Anfrage den Server erreicht hat oder nicht. Eine Wiederholung ohne Vorsichtsmaßnahmen könnte zu doppelten Operationen führen. Idempotenzschlüssel lösen dieses Problem, indem sie garantieren, dass eine Anfrage mit demselben Schlüssel nur einmal verarbeitet wird.

Twikey unterstützt den Standard-Idempotenz-Header für Erstellungs-Endpoints von Transaktionen, Erstattungen und Abonnements.

Idempotency-Key: "your unique reference"

Funktionsweise:

  • Erste Anfrage: wird normal verarbeitet. Die Antwort wird gespeichert und mit dem Schlüssel verknüpft.
  • Doppelte Anfrage während der Verarbeitung: gibt 409 Conflict zurück, was darauf hinweist, dass die ursprüngliche Anfrage noch verarbeitet wird.
  • Doppelte Anfrage nach Abschluss: gibt die ursprüngliche Antwort zurück (gleicher HTTP-Statuscode und Body), unabhängig davon, ob die ursprüngliche Anfrage erfolgreich war oder fehlgeschlagen ist.

Ein Idempotenzschlüssel kann pro Endpoint nur einmal verwendet werden. Nachdem eine Antwort für einen bestimmten Schlüssel zurückgegeben wurde, liefert jede nachfolgende Anfrage mit demselben Schlüssel diese gespeicherte Antwort zurück.

Schlüssel-Ablauf: Idempotenzschlüssel laufen nach 24 Stunden ab. Nach dem Ablauf kann derselbe Schlüssel wiederverwendet werden.

Viele Twikey-Operationen sind bereits implizit idempotent. Beispielsweise hat das mehrfache Stornieren desselben Mandats keine negativen Auswirkungen.

Fehlerbehandlung

API-Fehler fallen in zwei Hauptkategorien:

  1. Client-Fehler (HTTP 400):

    Diese treten aufgrund von Problemen in der Anfrage auf und werden über eine 400-Bad-Request-Antwort kommuniziert. Ein ApiError-Header wird mit weiteren Details zum Problem beigefügt. Die Fehlermeldung ist basierend auf dem Accept-Language-Header lokalisiert. Wenn dieser Header nicht angegeben ist, wird die Meldung standardmäßig auf Englisch zurückgegeben.

  2. Server-Fehler (HTTP 500):

    Diese weisen auf einen internen Fehler auf Twikey-Seite hin. Obwohl selten, deuten sie auf einen unerwarteten Ausfall in der API hin. In den meisten Fällen ist das Twikey-Team bereits über solche Vorfälle informiert, wenn sie auftreten.