Workiva-ondersteuningscentrum

Deze handleiding leidt je door het proces van het importeren van Workiva API-collecties in Postman met behulp van OpenAPI-specificaties, het configureren van omgevingsvariabelen en het volledig valideren van verzoeken.

Voorwaarden

Voordat u begint, zorg ervoor dat u over het volgende beschikt:

• Postman geïnstalleerd (versie 10+ aanbevolen)
• Een geldige Workiva Client ID en Client Secret
• Toegang tot Workiva OpenAPI .yaml bestanden via de Workiva Developer Portal
• Een begrip van de Workiva-omgeving waarin u werkt: app, eu, of apac

Achtergrond

De Workiva API's worden gepubliceerd in OpenAPI-formaat (.yaml). Deze specificaties kunnen direct in Postman worden geïmporteerd, waardoor snellere ontwikkelings-, test- en integratieprocessen mogelijk zijn zonder dat handmatig verzoeken hoeven te worden samengesteld.

Stap 1: Importeer de Workiva API-collectie

1. Ga naar de pagina voor het genereren van Workiva-platformcode .
2. Download het OpenAPI .yaml bestand. 
   
3. Open Postman, selecteer Importen upload het gedownloade bestand. 
   
4. Bevestig dat er een nieuwe collectie met de titel Workiva API in Postman verschijnt. 
   

Stap 2: Stel je omgeving in

Open in Postman het tabblad Omgevingen en maak een nieuwe omgeving aan. Voor testdoeleinden maakt deze handleiding gebruik van een omgeving met de naam<WorkspaceName> _Workiva_API.

Aanbeveling : Gebruik een consistente naamgevingsconventie zoals Organisatienaam_Werkruimtenaam om variabelen in verschillende Workiva-werkruimtes duidelijk van elkaar te onderscheiden.

Voeg de volgende variabelen toe met behulp van de kolom Huidige waarde en klik vervolgens op Opslaan.

📘 Hoe gebruik je omgevingsvariabelen in Postman

Stap 3: OAuth2 configureren – Een token ophalen

1. Selecteer de Workiva API collectie.
2. Stel de autorisatie in om de {{access_token}} variabele te gebruiken.
3. Selecteer het tabblad Scripts.

4. Voeg het volgende script toe aan de Pre-request sectie. 

   Voor 2026 Platform API'sis de X-Version header vereist bij elk verzoek. Dit script zorgt ervoor dat de header consistent wordt toegepast op de gehele collectie, in overeenstemming met de API-versievereisten van Workiva voor 2026.

   Opmerking: Deze vereiste is momenteel alleen van toepassing op Platform API's.

   // Voeg de X-Version-header toe of werk deze bij pm.request.headers.upsert({ key: "X-Version", value: pm.environment.get("api_version") });

   

    

5. Selecteer het tabblad Variabelen.
6. Werk de variabele baseUrl bij zodat deze {{environment}} gebruikt in plaats van een vastgelegd domein.

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

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

Stap 4: Sla het toegangstoken op

1. Vanuit Een token ophalen, selecteer het tabblad Scripts en voeg de onderstaande code toe aan het gedeelte Post-verzoek.

   pm.test("Statuscode is 200", functie () { pm.respons.naar.hebben.status(200); }); pm.test("Sla toegangstoken op in omgevingsvariabele", functie () { var jsonData = pm.respons.json(); pm.omgeving.set("toegangstoken", jsonData.toegangstoken); });

   

2. Verzend het verzoek. Je zou een 200 OK reactie moeten ontvangen en je access_token wordt automatisch opgeslagen.

Stap 5: Importeer en configureer de Wdata- en Chains-API-verzameling

1. Ga naar de Wdata Code Generation pagina.
2. Download het .yaml bestand en importeer het in Postman (Volg de stappen beschreven in Stap 1: De Workiva API-collectie importeren). Opmerking: De .yaml bestandsnaam zal waarschijnlijk hetzelfde zijn als de Workiva API Collection.
3. In de Wdata collectie:
   • Stel het autorisatietype in op Bearer Token.

   • Gebruik {{access_token}} als de tokenwaarde.

     

   • In het tabblad Variabelen kunt u de variabele baseUrl bijwerken zodat deze {{environment}} gebruikt in plaats van een vastgelegd domein. Dit maakt het gemakkelijker om te schakelen tussen omgevingen zoals app, eu, of apac.
   • Zorg ervoor dat elk verzoek is ingesteld op Authenticatie overnemen van ouder.
   • Herhaal de bovenstaande stappen voor de Chains API Collectionen zorg ervoor dat de autorisatie-instellingen en de baseUrl variabele op dezelfde manier geconfigureerd zijn.

Probleemoplossing

• Zorg ervoor dat je naar de juiste Omgevingverwijst. Als de collectie standaard de omgeving 'Geen' gebruikt, wijzig deze dan naar uw opgegeven omgeving.
• Controleer of de variabele baseUrl consistent is in uw omgeving en collectie-instellingen.
• Zorg ervoor dat je de collectievariabele baseUrl instelt op {{environment}}; anders kunnen je verzoeken mislukken.
• Als uw verzoek een 401-fout of een lege reactie oplevert, controleer dan of uw Client ID, Client Secret, API_version en Environment-waarden correct zijn.