Blog

Requêtes API Async

L’API Async vous permet d’envoyer des requêtes asynchrones à notre plateforme, vous permettant d’effectuer des opérations sans attendre leur completion. Cette fonctionnalité puissante peut améliorer considérablement les performances et l’expérience utilisateur de votre intégration.

Qu’est-ce que l’API Async ?

Au lieu d’attendre que chaque requête API se termine avant de passer à la suivante (requêtes synchrones), l’API Async vous permet d’envoyer une requête et de recevoir un accusé de réception immédiat. L’opération réelle se déroule en arrière-plan, et vous serez notifié une fois qu’elle sera terminée.

Pensez-y comme au dépôt d’un colis à la poste : vous obtenez immédiatement un numéro de suivi et pouvez vaquer à vos occupations, puis vous recevez une notification lorsque le colis est livré.

Quand devriez-vous utiliser l’API Async ?

L’API Async est idéale pour plusieurs scénarios :

Opérations Non-Critiques

Lorsque vous n’avez pas besoin du résultat immédiatement, l’API Async permet à votre application de rester réactive pendant que les opérations se terminent en arrière-plan.

Exemple : Mise à jour des données clients après une importation par lot où les mises à jour peuvent se produire au fil du temps sans bloquer votre application.

Amélioration de l’Expérience Utilisateur

Les opérations de longue durée peuvent provoquer des délais d’attente ou laisser les utilisateurs en attente. L’API Async vous permet d’accuser réception des actions utilisateur immédiatement et de les notifier lorsque l’opération est terminée.

Exemple : Un utilisateur ajoute plusieurs lignes de ventes, l’interface peut réagir plus rapidement et notifier l’utilisateur lors de la complétion, sans que ça paraisse « lent ».

Opérations Supportées

L’API Async fonctionne avec toutes les opérations de mutation :

  • POST – Création de nouvelles ressources
  • PUT – Remplacement de ressources existantes
  • PATCH – Mise à jour de ressources existantes
  • DELETE – Suppression de ressources

Comment utiliser l’API Async

Effectuer une Requête Async

Envoyez votre requête à l’endpoint /open-api/v3/async avec les informations suivantes :

Endpoint : POST /open-api/v3/async

Corps de la Requête :

{
  "requestPath": "/open-api/v3/invoice_lines",
  "method": "POST",
  "callbackUrl": "https://your-app.com/webhooks/async-callback",
  "body": {
    "number": 1,
    "price": 1.99,
    "invoice": "/open-api/v3/invoices/366"
  }
}

Paramètres :

  • requestPath :  L’endpoint API que vous souhaitez appeler
  • method :  La méthode HTTP (POST, PUT, PATCH ou DELETE)
  • callbackUrl :  L’URL où vous souhaitez recevoir la notification de completion
  • body :  Les données pour votre requête (identiques à celles que vous enverriez à l’endpoint régulier)

Comprendre la Réponse

Vous recevrez immédiatement une réponse 202 Accepted avec un ID de promesse :

{
  "@context": {
    "@vocab": "https://demo.example.com/open-api/v3/docs.jsonld#",
    "hydra": "http://www.w3.org/ns/hydra/core#",
    "promiseId": "AsyncRequestOutput/promiseId"
  },
  "@type": "AsyncRequestOutput",
  "@id": "/open-api/v3/.well-known/genid/9e66c4c9d984f0c2b1c7",
  "promiseId": "2025112805182211670-6929d95ea3a5b-promise.log"
}

Le promiseId est votre numéro de suivi. Conservez-le pour vérifier le statut ou le faire correspondre avec les notifications de callback.

Vérifier le Statut de la Requête

Vous pouvez vérifier votre requête asynchrone à tout moment en utilisant l’ID de promesse :

Endpoint : GET /open-api/v3/promises/{promiseId}

Cela retourne le statut actuel de votre requête, incluant :

  • Si elle est en attente, terminée ou échouée
  • Les messages d’erreur si la requête a échoué
  • Les données de résultat lorsqu’elle est terminée avec succès

Recevoir les Notifications lorsque la requête est terminée

Lorsque votre requête asynchrone se termine (avec succès ou avec une erreur), une notification est envoyée à votre callbackUrl. Cette notification contient le résultat de votre opération, vous permettant de mettre à jour votre application en conséquence.

La charge utile de la notification est signée avec un jeton JWT, vous permettant de vérifier son authenticité avant traitement.

Bonnes Pratiques

  1. Toujours fournir une URL de callback : Bien que vous puissiez interroger le statut, les callbacks fournissent le mécanisme de notification le plus efficace.
  2. Implémenter l’idempotence : Si un callback n’atteint pas votre serveur, vous pourriez le recevoir plusieurs fois. Concevez votre gestionnaire de callback pour gérer les notifications en double de manière élégante.
  3. Vérifier les signatures des callbacks : Vérifiez toujours la signature JWT des notifications de callback pour vous assurer qu’elles sont authentiques.
  4. Stocker les IDs de promesse : Gardez une trace des IDs de promesse dans votre base de données afin de pouvoir corréler les callbacks avec les requêtes originales.
  5. Gérer les erreurs avec élégance : Vérifiez les notifications de callback pour les erreurs et implémentez une logique de nouvelle tentative ou de repli appropriée.
  6. Utiliser pour les scénarios appropriés : N’utilisez pas les requêtes asynchrones lorsque vous avez besoin de résultats immédiats pour le retour utilisateur ou les opérations suivantes.

Résumé

L’API Async est un outil puissant pour construire des intégrations performantes et évolutives. En permettant aux opérations de se terminer en arrière-plan, vous pouvez :

  • Garder votre application réactive
  • Gérer les flux de données à haut volume
  • Améliorer l’expérience utilisateur globale

Commencez par identifier les opérations dans votre intégration qui ne nécessitent pas de résultats immédiats, et envisagez de les migrer vers l’API Async pour améliorer l’expérience utilisateur.