Centro assistenza di Workiva

Questa guida spiega come importare le raccolte API di Workiva in Postman utilizzando le specifiche OpenAPI, configurando le variabili d'ambiente e convalidando le richieste end-to-end.

Prerequisiti

Prima di iniziare, assicuratevi di disporre di quanto segue:

• Postman installato (si consiglia la versione 10+)
• Un ID cliente valido di Workiva e un Segreto cliente
• Accesso ai file .yaml di Workiva OpenAPI tramite il portale per sviluppatori di Workiva
• Conoscenza dell'ambiente Workiva in cui si lavora: app, eu, o apac

Background

Le API di Workiva sono pubblicate in formato OpenAPI (.yaml). Queste specifiche possono essere importate direttamente in Postman, consentendo di velocizzare i flussi di sviluppo, test e integrazione senza dover costruire manualmente le richieste.

Passo 1: Importare la raccolta API di Workiva

1. Accedere alla pagina Workiva Platform Code Generation .
2. Scaricare il file OpenAPI .yaml. 
   
3. Aprire Postman, selezionare Importa e caricare il file scaricato. 
   
4. Confermare che in Postman appare una nuova raccolta intitolata Workiva API. 
   

Passo 2: Configurare l'ambiente

In Postman, aprire la scheda Environments e creare un nuovo ambiente. A scopo di test, questa guida utilizza un ambiente denominato <NomeWorkspace>_Workiva_API.

Raccomandazione: Utilizzare una convenzione di denominazione coerente come OrganizationName_WorkspaceName per distinguere chiaramente le variabili tra i diversi spazi di lavoro di Workiva.

Aggiungere le seguenti variabili utilizzando la colonna Valore corrente, quindi fare clic su Salva.

📘 Come usare le variabili d'ambiente in Postman

Passo 3: Configurare OAuth2 - Recuperare un token

1. Selezionare la raccolta Workiva API.
2. Impostare l'autorizzazione per utilizzare la variabile {{access_token}}.
3. Selezionare la scheda Scripts.

4. Aggiungere il seguente script alla sezione Pre-request. 

   Per 2026 le API della piattaforma, l'intestazione X-Version è richiesta su ogni richiesta. Questo script assicura che l'intestazione sia applicata in modo coerente all'intera raccolta, in linea con i requisiti di versionamento dell'API 2026 di Workiva.

   Nota: Questo requisito si applica attualmente solo alle API di piattaforma.

   // Aggiungere o aggiornare l'intestazione X-Version pm.request.headers.upsert({ key: "X-Version", value: pm.environment.get("api_version") });

   

    

5. Seleziona la scheda Variables.
6. Aggiorna la variabile baseUrl per utilizzare {{environment}} invece di un dominio codificato.

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

Aggiornato:
https://api.{{environment}}.wdesk.com/iam/v1

Passo 4: Salvare il token di accesso

1. Da Recupera un token, seleziona la scheda Scripts e aggiungi il codice sottostante alla sezione Post-request.

   pm.test("Il codice di stato è 200", function () { pm.response.to.have.status(200); }); pm.test("Salva il token di accesso nella variabile d'ambiente", function () { var jsonData = pm.response.json(); pm.environment.set("access_token", jsonData.access_token); });

   

2. Invia la richiesta. Dovresti ricevere una risposta 200 OK e il tuo access_token sarà salvato automaticamente.

Passo 5: Importare e configurare la raccolta API Wdata e Chains

1. Andate alla pagina Wdata Code Generation.
2. Scaricare il file .yaml e importarlo in Postman (Seguire la procedura descritta in Passo 1: Importare la raccolta API di Workiva). Nota: Il nome del file .yaml sarà probabilmente lo stesso della Workiva API Collection.
3. Nella raccolta Wdata :
   • Imposta Authorization Type su Bearer Token.

   • Usa {{access_token}} come valore del token.

     

   • Nella scheda Variabili, aggiorna la variabile baseUrl in modo che utilizzi {{environment}} invece di un dominio codificato. In questo modo è più facile passare da un ambiente all'altro come app, eu, o apac.
   • Assicurati che ogni richiesta sia impostata su Eredita auth dal genitore.
   • Ripetere gli stessi passi sopra descritti per la Chains API Collection, assicurandosi che le impostazioni di autorizzazione e la variabile baseUrl siano configurate allo stesso modo.

Risoluzione dei problemi

• Assicurati di fare riferimento all'ambiente corretto. Se la collezione ha come impostazione predefinita l'ambiente No, passa a l'ambiente specificato.
• Verifica che la variabile baseUrl sia coerente con le impostazioni dell'ambiente e della collezione.
• Assicurati di impostare la variabile di raccolta baseUrl per utilizzare {{environment}}; in caso contrario, le tue richieste potrebbero fallire.
• Se la richiesta restituisce una risposta 401 o vuota, ricontrollare che i valori di Client ID, Client Secret, API_version e Environment siano corretti.