Portail de support Workiva

Ce guide vous accompagne dans l'importation des collections Workiva API dans Postman en utilisant les spécifications OpenAPI, en configurant les variables d'environnement et en validant les requêtes d'un bout à l'autre.

Conditions préalables

Avant de commencer, assurez-vous que vous disposez des éléments suivants :

• Postman installé (version 10+ recommandée)
• Un identifiant client Workiva valide et Secret client
• Accès aux fichiers Workiva OpenAPI .yaml via le Workiva Developer Portal
• Une compréhension de l'environnement Workiva dans lequel vous travaillez : app, eu, ou apac

Arrière-plan

Les API de Workiva sont publiées au format OpenAPI (.yaml). Ces spécifications peuvent être importées directement dans Postman, ce qui permet d'accélérer les processus de développement, de test et d'intégration sans avoir à construire manuellement des requêtes.

Étape 1 : Importer la collection Workiva API

1. Naviguez jusqu'à la page Workiva Platform Code Generation .
2. Téléchargez le fichier OpenAPI .yaml. 
   
3. Ouvrez Postman, sélectionnez Import, et téléchargez le fichier téléchargé. 
   
4. Confirmez qu'une nouvelle collection intitulée Workiva API apparaît dans Postman. 
   

Etape 2 : Configurer votre environnement

Dans Postman, ouvrez l'onglet Environments et créez un nouvel environnement. A des fins de test, ce guide utilise un environnement nommé <WorkspaceName>_Workiva_API.

Recommandation : Utilisez une convention de dénomination cohérente telle que OrganizationName_WorkspaceName pour distinguer clairement les variables dans les différents espaces de travail Workiva.

Ajoutez les variables suivantes en utilisant la colonne Current Value, puis cliquez sur Save.

📘 Comment utiliser les variables d'environnement dans Postman

Étape 3 : Configurer OAuth2 - Récupérer un jeton

1. Sélectionnez la collection Workiva API.
2. Définir l'autorisation pour utiliser la variable {{access_token}}.
3. Sélectionnez l'onglet Scripts.

4. Ajoutez le script suivant à la section Pre-request. 

   Pour 2026 Platform APIs, l'en-tête X-Version est requis pour chaque requête. Ce script garantit que l'en-tête est appliqué de manière cohérente à l'ensemble de la collection, conformément aux exigences de versionnement de l'API 2026 de Workiva.

   Note : Cette exigence ne s'applique actuellement qu'aux API de plate-forme.

   // Ajouter ou mettre à jour l'en-tête X-Version pm.request.headers.upsert({ key : "X-Version", value : pm.environment.get("api_version") }) ;

   

    

5. Sélectionnez l’onglet Variables.
6. Mettez à jour la variable baseUrl pour utiliser {{environment}} au lieu d’un domaine codé en dur.

Original :
https ://api.app.wdesk.com/iam/v1

Mise à jour :
https ://api.{{environment}}.wdesk.com/iam/v1

Étape 4 : Enregistrer le jeton d'accès

1. À partir de Retrieve a token, sélectionnez l’onglet Scripts et ajoutez le code ci-dessous à la section Post-request.

   pm.test("Status code is 200", function () { pm.response.to.have.status(200) ; }) ; pm.test("Save access token to environment variable", function () { var jsonData = pm.response.json() ; pm.environment.set("access_token", jsonData.access_token) ; }) ;

   

2. Envoyez la demande. Vous devriez recevoir une réponse 200 OK et votre access_token sera sauvegardé automatiquement.

Étape 5 : Importer et configurer la collection d'API Wdata et Chains

1. Allez à la page Wdata Code Generation.
2. Téléchargez le fichier .yaml et importez-le dans Postman (Suivez les étapes décrites dans Step 1 : Import the Workiva API Collection). Remarque : Le nom de fichier .yaml sera probablement le même que celui de Workiva API Collection.
3. Dans la collection Wdata :
   • Définissez le type d’autorisation sur Bearer Token.

   • Utilisez {{access_token}} comme valeur symbolique.

     

   • Dans l’onglet Variables, mettez à jour la variable baseUrl pour utiliser {{environment}} au lieu d’un domaine codé en dur. Cela facilite le passage entre des environnements tels que app, eu, ou apac.
   • Assurez-vous que chaque requête est définie sur Inherit auth from parent.
   • Répétez les mêmes étapes ci-dessus pour la collection Chains API Collection, en vous assurant que les paramètres d'autorisation et la variable baseUrl sont configurés de la même manière.

Dépannage

• Assurez-vous de référencer le bon environnement Environnement. Si la collection est définie par défaut sur son environnement No, passez à l’environnement que vous avez spécifié.
• Confirmez que la variable baseUrl est cohérente dans les paramètres de votre environnement et de votre collection.
• Assurez-vous que la variable de collection baseUrl utilise {{environment}} ; dans le cas contraire, vos requêtes risquent d’échouer.
• Si votre demande renvoie une réponse 401 ou vide, vérifiez à nouveau que les valeurs de l'identifiant du client, du secret du client, de la version de l'API et de l'environnement sont correctes.