Aller au contenu principal

Envoyez votre première requête API

Ce guide utilise un projet de la Plateforme développeur et son environnement Sandbox déterministe. Il utilise le même processus d’authentification que la Production sans provoquer d’effets en production.

Avant de commencer​

Vous avez besoin :

  • d’un compte Alkax ayant accès à la Console développeur ;
  • d’un projet et de son environnement Sandbox ;
  • d’un identifiant Sandbox doté de la portée delivery:read pour le premier jeu de données de test ;
  • d’un backend ou d’un environnement serveur sécurisé ;
  • de l’URL de base de l’API : https://api.alkax.io.

Conservez les identifiants dans un gestionnaire de secrets et masquez-les dans les journaux de l’application.

Ouvrez https://alkax.io/developers, créez un projet et émettez un identifiant Sandbox depuis Credentials (Identifiants). Copiez le secret lorsqu’il s’affiche ; il ne pourra pas être récupéré ensuite.

Définir les variables de requête​

export ALKAX_API="https://api.alkax.io"
export ALKAX_API_KEY="ak_test_<key-id>.<secret>"

Envoyer une requête Sandbox déterministe​

Appelez un jeu de données de test versionné, utilisable sans risque en développement local et en intégration continue :

curl "$ALKAX_API/api/v1/sandbox/fixtures/valid-high-confidence" \
  --header "X-Alkax-Key: $ALKAX_API_KEY" \
  --header "Accept: application/json"

La réponse contient un résultat de test stable et un en-tête X-Request-Id. Utilisez cet identifiant pour retrouver la requête dans l’onglet Logs (Journaux) de la Console développeur.

Les autres jeux de données stables sont ambiguous, weak-access, not-found et conflicting-evidence. L’espace d’essai de la console peut exécuter les mêmes tests et générer des exemples curl, TypeScript, Python et C#.

Passer à un point de terminaison métier​

Émettez un identifiant doté uniquement de la portée nécessaire, puis appelez le point de terminaison avec le même en-tête X-Alkax-Key. Pour la confirmation par le destinataire avant expédition, suivez le guide Delivery Intelligence.

N’utilisez pas une clé Sandbox en Production. Lorsque l’intégration est prête, activez un abonnement payant et émettez un identifiant ak_live_ distinct depuis l’environnement Production.

Traiter la réponse​

  • Utilisez le statut HTTP comme résultat principal.
  • Conservez les identifiants stables, les codes d’erreur lisibles par machine et l’identifiant de requête.
  • Utilisez des identifiants permettant de réessayer sans doublon lorsque le guide l’exige.
  • Espacez les nouvelles tentatives après des réponses 429 ou des erreurs 5xx temporaires.
  • Ne renvoyez jamais une requête invalide sans la corriger.

Consultez Erreurs et nouvelles tentatives pour le modèle de réponse commun.

Pour continuer​

Réaliser une intégration fonctionnelle​

Après la première requête Sandbox, poursuivez avec l’intégration des livraisons et retours et les recettes de webhooks. Le jeu de données fournit un exemple d’adresse ; il ne crée pas d’expédition. Utilisez les API versionnées documentées et les parcours Sandbox pour tester un cycle de vie synthétique complet avant de passer en Production.