Concepts de base

Authentification

Toutes les requetes API doivent inclure un jeton de session valide dans l'en-tete Authorization. Ce jeton peut etre obtenu via le endpoint de connexion et reste valide pendant 24 heures. Il est recommande de declencher l'appel de connexion lorsque la requete reelle retourne une reponse 401 Unauthorized. Cette approche simplifie la gestion des jetons en ne demandant un nouveau jeton que lorsque cela est necessaire.

Feeds

Les changements de statut sont beaucoup plus frequents pour les accords, les factures et les transactions que pour les paiements ponctuels classiques. Afin de ne manquer aucun evenement et etant donne que plusieurs webhooks peuvent ne pas arriver dans le bon ordre en raison de la latence du reseau, Twikey fournit des "feeds" ou files d'attente, qui sont en fait une liste d'evenements non encore recus.

Chaque feed de donnees (ou file d'evenements) inclut le dernier numero de sequence (X-LAST) qui permet aux clients de reprendre a partir d'un point specifique dans le flux d'evenements (via l'en-tete de requete X-RESUME-AFTER). Ce mecanisme est particulierement utile pour la recuperation apres erreur ou lors d'une reconnexion apres une interruption (et est egalement tres pratique lors des tests).

Il est essentiel de continuer a lire le feed jusqu'a ce qu'il ne reste plus d'entrees. La partie cruciale etant jusqu'a ce qu'aucune autre mise a jour ne soit disponible. Cela garantit que chaque mise a jour est correctement traitee et que rien n'est manque.

Il faut eviter que plusieurs clients dans le reseau accedent au meme feed simultanement avec la meme cle API, car cela peut entrainer des conditions de concurrence et des donnees incoherentes. Si un acces concurrent est necessaire, les approches suivantes peuvent etre envisagees :

Utiliser des cles API separees : attribuer une cle API unique a chaque client. Des cles supplementaires peuvent etre generees depuis le menu des parametres Twikey.
Implementer un modele maitre-client : designer un seul client comme maitre pour recuperer le feed. Les autres clients peuvent lire les donnees depuis un datastore partage gere par le maitre.

La securite etant essentielle pour les paiements, Twikey a decide de ne pas transmettre les details des paiements dans les webhooks, mais uniquement de les fournir dans les requetes provenant de l'integration. Des appels "detail" specifiques sur un objet sont disponibles, mais comme ils ne representent qu'un instantane de l'objet a ce moment-la (et que l'objet peut avoir deja change au moment du traitement), des limites de debit ont ete ajoutees pour eviter leur utilisation abusive.

Parametres d'inclusion Certains feeds prennent en charge des parametres include pour demander des details supplementaires dans la reponse. Les inclusions disponibles varient selon le feed et sont documentees dans la reference API. Par defaut, les feeds retournent une reponse compacte pour minimiser la taille de la charge utile.

Webhooks vs Polling

Deux types d'integrations sont pris en charge.

Avec une architecture push-fetch, Twikey notifie d'un evenement via un webhook. Ce webhook peut etre utilise comme declencheur pour recuperer tous les evenements du feed (ou de la file d'attente) et mettre a jour les systemes internes.

Note : Les webhooks servent uniquement de notifications et doivent etre traites en consequence. Pour eviter les livraisons en double dues aux delais d'expiration ou aux tentatives, il est essentiel de s'assurer que toute logique metier interne soit traitee de maniere asynchrone.

L'alternative est une architecture pull, ou les clients interrogent periodiquement Twikey pour obtenir les dernieres mises a jour. Cette architecture convient aux situations ou aucun webhook entrant n'est autorise. Cependant, l'inconvenient est qu'il y a un delai entre le moment ou un evenement se produit dans Twikey et le moment ou l'evenement est recu.

Des solutions hybrides combinant des hooks avec des interrogations recurrentes sont evidemment aussi possibles.

Clés d'idempotence

Lorsqu'une requete echoue en raison d'un probleme reseau, il peut etre difficile de savoir si la requete a atteint le serveur ou non. Reessayer sans precaution pourrait entrainer des operations en double. Les cles d'idempotence resolvent ce probleme en garantissant qu'une requete avec la meme cle n'est traitee qu'une seule fois.

Twikey prend en charge l'en-tete d'idempotence standard pour les endpoints de creation de transactions, de remboursements et d'abonnements.

Idempotency-Key: "your unique reference"

Fonctionnement :

Premiere requete : traitee normalement. La reponse est stockee et liee a la cle.
Requete en double pendant le traitement : retourne 409 Conflict, indiquant que la requete originale est toujours en cours de traitement.
Requete en double apres achevement : retourne la reponse originale (meme code de statut HTTP et corps), que la requete originale ait reussi ou echoue.

Une cle d'idempotence ne peut etre utilisee qu'une seule fois par endpoint. Apres qu'une reponse a ete retournee pour une cle donnee, toute requete subsequente avec la meme cle retourne cette reponse stockee.

Expiration des cles : Les cles d'idempotence expirent apres 24 heures. Apres expiration, la meme cle peut etre reutilisee.

A noter que de nombreuses operations Twikey sont deja implicitement idempotentes. Par exemple, annuler le meme mandat plusieurs fois n'a aucun effet indesirable.

Gestion des erreurs

Les erreurs API se repartissent en deux categories principales :

Erreurs client (HTTP 400) :
Celles-ci surviennent en raison de problemes dans la requete et sont communiquees via une reponse 400 Bad Request. Un en-tete ApiError sera inclus avec plus de details sur le probleme. Le message d'erreur est localise en fonction de l'en-tete Accept-Language. Si cet en-tete n'est pas fourni, le message est par defaut en anglais.
Erreurs serveur (HTTP 500) :
Celles-ci indiquent une erreur interne cote serveur. Bien que rares, elles suggerent une defaillance inattendue dans l'API. Dans la plupart des cas, l'equipe Twikey est deja informee de ces incidents lorsqu'ils se produisent.