Aller au contenu

Explorer l'API avec Postman

La meilleure façon d’explorer l’API SIGN DE V2 est d’utiliser une application appelée Postman. Une alternative consiste à utiliser l’outil en ligne de commande Linux/Unix curl.

Ce guide utilise Postman pour fournir des exemples de toutes les opérations nécessaires à la configuration d’un TSS avec ses clients et transactions associés. Vous pouvez vérifier les détails de chaque requête et réponse, et tester facilement différents scénarios.

Qu’est-ce que Postman ?

Section intitulée « Qu’est-ce que Postman ? »

Postman est une application logicielle gratuite qui facilite l’exploration des API.

Une collection Postman et un environnement Postman fournissent un système de test qui inclut toute la configuration nécessaire pour une API particulière. Il suffit de charger ces deux fichiers dans Postman et vous êtes prêt à commencer à explorer et à tester.

Configuration

Section intitulée « Configuration »

  1. Télécharger Postman

    Téléchargez la version gratuite de Postman depuis postman.com/downloads.

    Il est disponible pour les trois principales plateformes : Linux, macOS et Windows. Il existe également une version web de Postman.

  2. Créer une clé API

    Avant de commencer avec Postman, vous devez créer une clé et un secret API via le fiskaly HUB.

    Création de clé API

  3. Télécharger votre environnement personnalisé

    Accédez à la page de démarrage rapide de l’API V2 et saisissez votre clé et votre secret API pour obtenir votre environnement Postman personnalisé.

    Télécharger l'environnement

Importation de l’environnement API V2

Section intitulée « Importation de l’environnement API V2 »

Pour explorer l’API SIGN DE V2 avec Postman, vous devez d’abord importer ses fichiers de configuration.

  1. Ouvrir la fenêtre d'importation de Postman

    Démarrez Postman et, depuis la fenêtre d’importation, sélectionnez Charger des fichiers.

    Fenêtre de chargement Postman

  2. Sélectionner les fichiers de collection et d'environnement

    Sélectionnez les fichiers de collection et d’environnement que vous avez téléchargés précédemment.

    Fenêtre d'importation Postman

  3. Vérifier votre espace de travail

    Vous devriez maintenant pouvoir voir 1 Collection et 1 Environnement dans l’espace de travail Postman.

    Vue de l'espace de travail Postman

  4. Sélectionner l'environnement

    Sélectionnez l’environnement SIGN DE API V2 dans le menu déroulant des environnements.

    Sélectionner l'environnement Postman

Exécution de la démo

Section intitulée « Exécution de la démo »

La Collection Postman API V2 comprend des exemples complets de chaque requête impliquée dans la configuration d’un environnement TSS, de l’authentification initiale jusqu’aux exports de données.

Vous pouvez exécuter ces requêtes en utilisant le Lanceur de collection de Postman.

  1. Ouvrir le Lanceur de collection

    Sélectionnez Collections, puis Scénario standard, puis cliquez sur le bouton Exécuter.

    Bouton Exécuter Postman

  2. Exécuter la collection

    Postman liste l’ensemble des requêtes à exécuter. Cliquez sur le bouton Exécuter SIGN DE API V2.

    Exécuter la collection Postman

  3. Vérifier les résultats

    Vous devriez voir un code de statut 200 du serveur pour chaque requête, indiquant que la requête a réussi.

    Résultats d'exécution Postman

    D’autres réponses possibles incluent 400 (problème avec la requête) ou 500 (problème avec le serveur).

La démonstration montre l’ordre des requêtes pour :

  • Authentification initiale de l’administrateur
  • Création et gestion d’un TSS
  • Création et gestion de clients
  • Transactions
  • Export des données du TSS

Les sections suivantes examinent ces requêtes plus en détail.

Comprendre les variables

Section intitulée « Comprendre les variables »

Postman stocke les valeurs importantes de l’API dans des variables. Les variables peuvent être réutilisées dans différentes requêtes. Si vous modifiez la valeur d’une variable, la nouvelle valeur est utilisée dans toutes ces requêtes.

Lorsque vous importez pour la première fois l’environnement SIGN DE API V2, il ne contient que trois variables :

VariableDescription
baseUrlL’URL de base de l’API
api_keyVotre clé API
api_secretVotre secret API

Variables d'environnement Postman

Vous pouvez voir comment une variable est utilisée dans une requête d’authentification. Postman substitue la variable {{baseUrl}} par la valeur stockée dans l’environnement SIGN DE API V2 :

https://kassensichv-middleware.fiskaly.com/api/v2

Ainsi, une requête d’authentification est en réalité envoyée via POST à :

https://kassensichv-middleware.fiskaly.com/api/v2/auth

Variables dans la requête

Effectuer des requêtes

Section intitulée « Effectuer des requêtes »

Faisons une requête d’authentification. Il s’agit d’une requête POST envoyée à {{baseUrl}}/auth.

Capture d'écran de requête Postman

Le corps de la requête utilise des variables d’environnement :

{
  "api_key": "{{api_key}}",
  "api_secret": "{{api_secret}}"
}

Postman reçoit la réponse suivante du serveur (le 200 OK en vert indique le succès) :

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "access_token_claims": {
    "env": "TEST",
    "organization_id": "0bd118a1-eed7-4065-9e6b-710ab3aaf445"
  },
  "access_token_expires_in": 600,
  "access_token_expires_at": 1626678863,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token_expires_in": 600,
  "refresh_token_expires_at": 1626678863
}

Nous obtenons un jeton d’accès et un jeton de rafraîchissement. Postman stocke les nouvelles valeurs dans des variables, qui sont ensuite utilisées dans les requêtes suivantes.

De même, vous pouvez voir l’en-tête et le corps, et vérifier la réponse du serveur, pour toutes les autres requêtes de cette collection.

Génération de code

Section intitulée « Génération de code »

Postman peut générer le code pertinent pour effectuer des requêtes dans une variété de langages de programmation.

Dans cet exemple, nous allons générer la requête d’authentification appropriée pour curl.

  1. Exécuter la requête d'authentification

    Réexécutez la requête d’authentification depuis la collection.

    Génération de code Étape 1

  2. Ouvrir la barre latérale des extraits de code

    Cliquez sur l’icône Code dans la barre latérale droite.

    Icône Code Postman

  3. Sélectionner votre langage

    La barre latérale des extraits de code s’affiche. curl devrait être sélectionné par défaut ; sinon, utilisez le menu déroulant pour le sélectionner.

    Sélectionner curl dans Postman

  4. Copier et utiliser le code généré

    Vous pouvez maintenant voir les commandes curl qui correspondent à cette requête Postman. Exécutez-les dans un terminal pour vous authentifier.

    Curl dans le terminal

Référence croisée avec le HUB

Section intitulée « Référence croisée avec le HUB »

Les requêtes de gestion TSS et Client effectuées depuis Postman peuvent être visualisées dans le fiskaly HUB.

Immédiatement après la création d’une nouvelle organisation, le HUB indique qu’il n’y a pas de Clients, TSS, Transactions ou Exports.

HUB vide

Après avoir envoyé une requête d’authentification suivie d’une requête de Création TSS depuis la collection Postman, actualisez la vue HUB et vous verrez le nouveau TSS listé.

HUB avec TSS

D’autres opérations Postman pour gérer TSS et Clients se reflètent également dans le HUB. Le fiskaly HUB offre une vue d’ensemble plus simple de votre organisation et peut gérer directement TSS et Clients.

Pages associées

Section intitulée « Pages associées »

Guide pour les nouveaux clients

Guide complet de configuration de l'API

Manuel HUB

Gestion des organisations, TSS et clients

Gestion des erreurs

Meilleures pratiques pour les délais d'attente et la récupération des erreurs

Was this page helpful?