Passer au contenu principal

​
Apercu

L’idempotence garantit que faire la meme requete API plusieurs fois produit le meme resultat. C’est crucial pour des integrations fiables, surtout lorsque des problemes reseau causent des echecs de requete.

​
Comment ca Fonctionne

Incluez un en-tete Idempotency-Key avec une valeur unique pour chaque requete logique : 
curl -X POST https://api.txcloud.io/v1/identity/verify \
  -H "Authorization: Bearer $TXCLOUD_API_KEY" \
  -H "Idempotency-Key: user_123_verification_tentative_1" \
  -H "Content-Type: application/json" \
  -d '{"document_front": "...", "country": "MA"}'
Si vous envoyez la meme requete avec la meme Idempotency-Key :
  • Premiere requete : Traitee normalement, resultat stocke
  • Requetes suivantes : Retournent le resultat en cache immediatement

​
Utiliser les Cles d’Idempotence

import { v4 as uuidv4 } from 'uuid';

// Generer une cle unique pour chaque operation logique
const idempotencyKey = `verify_${userId}_${Date.now()}`;

const verification = await txcloud.identity.verify({
  document_front: documentBase64,
  country: 'MA'
}, {
  idempotencyKey: idempotencyKey
});

​
Directives pour les Cles

​
Format de Cle

ExigenceExemple
Longueur10-255 caracteres
CaracteresAlphanumeriques, tirets, underscores
UniciteDoit etre unique par type de requete
Bons exemples :
  • user_123_verify_2025-01-15T10:30:00Z
  • order_456_payment_tentative_1
  • 550e8400-e29b-41d4-a716-446655440000

​
Expiration des Cles

Les cles d’idempotence sont stockees pendant 24 heures. Apres expiration :
  • La meme cle peut etre reutilisee
  • La requete sera traitee comme nouvelle

​
Portee des Cles

Les cles sont limitees a :
  • Votre cle API
  • L’endpoint appele
Cela signifie que la meme cle peut etre utilisee sur differents endpoints sans conflit.

​
Pattern de Re-essai Securise

Implementez une logique de re-essai avec l’idempotence : 
async function safeRequest(fn, maxRetries = 3) {
  // Generer la cle une fois pour tous les re-essais
  const idempotencyKey = uuidv4();

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn(idempotencyKey);
    } catch (error) {
      // Sur de reessayer avec la meme cle
      if (isRetryable(error) && attempt < maxRetries - 1) {
        await sleep(1000 * Math.pow(2, attempt));
        continue;
      }
      throw error;
    }
  }
}

// Utilisation
const verification = await safeRequest((key) =>
  txcloud.identity.verify({
    document_front: doc,
    country: 'MA'
  }, { idempotencyKey: key })
);

​
En-tetes de Reponse

Lorsqu’une reponse en cache est retournee, TXCloud inclut : 
HTTP/1.1 200 OK
Idempotency-Key: abc123
Idempotent-Replayed: true
X-Request-Id: req_original_123
En-teteDescription
Idempotent-Replayedtrue si la reponse etait en cache
X-Request-IdID de la requete originale

​
Gerer les Conflits

Si vous envoyez la meme cle avec des corps de requete differents, vous obtiendrez une erreur : 
{
  "error": {
    "code": "idempotency_key_conflict",
    "message": "Cle d'idempotence deja utilisee avec des parametres de requete differents",
    "type": "invalid_request_error"
  }
}
Utilisez toujours une nouvelle cle d’idempotence pour chaque requete unique. Reutiliser des cles avec des parametres differents est une erreur.

​
Endpoints Supportant l’Idempotence

EndpointSupporte l’Idempotence
POST /identity/verifyOui
POST /identity/sessionsOui
POST /transactions/scoreOui
POST /lending/assessOui
POST /kyb/verifyOui
POST /watchlist/screenOui
GET endpointsDeja idempotent
DELETE endpointsDeja idempotent

​
Bonnes Pratiques

Generez les cles d’idempotence dans votre application, pas dans TXCloud. Cela garantit que les re-essais utilisent la meme cle.
Rendez les cles significatives pour le debogage :
// Bon : inclut le contexte
const key = `user_${userId}_verify_${timestamp}`;

// Moins utile : aleatoire seulement
const key = uuid();
Journalisez les cles d’idempotence avec vos requetes pour le depannage.
Chaque operation logique doit avoir sa propre cle :
// Faux : meme cle pour differentes operations
const key = `user_${userId}`;
await verify(key);
await assess(key); // Conflit!

// Correct : cle unique par operation
await verify(`user_${userId}_verify_1`);
await assess(`user_${userId}_assess_1`);

​
Exemple : Traitement de Paiement

Un cas d’utilisation courant pour l’idempotence est le traitement des paiements : 
async function processPayment(userId, amount, orderId) {
  // Utilisez orderId pour garantir que le paiement n'est traite qu'une fois
  const idempotencyKey = `payment_${orderId}`;

  // Meme si ceci est appele plusieurs fois (ex: double-clic utilisateur)
  // le paiement ne sera traite qu'une seule fois
  const score = await txcloud.transactions.score({
    transaction_id: orderId,
    amount: amount,
    currency: 'MAD',
    sender: { user_id: userId }
  }, {
    idempotencyKey: idempotencyKey
  });

  return score;
}

// Sur d'appeler plusieurs fois
await processPayment('user_123', 1000, 'order_456');
await processPayment('user_123', 1000, 'order_456'); // Retourne le cache

Reference API

En savoir plus sur la gestion des requetes dans la Reference API