Centro de suporte da Workiva

Este guia orienta você na importação de coleções da API da Workiva para o Postman usando especificações da OpenAPI, configurando variáveis de ambiente e validando solicitações de ponta a ponta.

Pré-requisitos

Antes de começar, verifique se você tem o seguinte:

• Postman instalado (recomenda-se a versão 10+)
• Um ID de cliente válido da Workiva e um segredo de cliente
• Acesso aos arquivos Workiva OpenAPI .yaml por meio do Workiva Developer Portal
• Compreensão do ambiente da Workiva em que você está trabalhando: app, eu, ou apac

Histórico

As APIs da Workiva são publicadas no formato OpenAPI (.yaml). Essas especificações podem ser importadas diretamente para o Postman, permitindo fluxos de trabalho de desenvolvimento, teste e integração mais rápidos, sem a necessidade de criar solicitações manualmente.

Etapa 1: Importar a coleção da API da Workiva

1. Navegue até a página Workiva Platform Code Generation .
2. Faça o download do arquivo OpenAPI .yaml. 
   
3. Abra Postman, selecione Import e faça o upload do arquivo baixado. 
   
4. Confirme se uma nova coleção intitulada Workiva API aparece no Postman. 
   

Etapa 2: configurar seu ambiente

No Postman, abra a guia Environments e crie um novo ambiente. Para fins de teste, este guia usa um ambiente chamado <WorkspaceName>_Workiva_API.

Recomendação: Use uma convenção de nomenclatura consistente, como OrganizationName_WorkspaceName para distinguir claramente as variáveis em diferentes espaços de trabalho da Workiva.

Adicione as seguintes variáveis usando a coluna Current Value e, em seguida, clique em Save.

📘 Como usar variáveis de ambiente no Postman

Etapa 3: Configurar o OAuth2 - Recuperar um token

1. Selecione a coleção Workiva API.
2. Defina a autorização para usar a variável {{access_token}}.
3. Selecione a guia Scripts.

4. Adicione o seguinte script à seção Pre-request. 

   Para 2026 APIs de plataforma, o cabeçalho X-Version é exigido em todas as solicitações. Esse script garante que o cabeçalho seja aplicado de forma consistente em toda a coleção, de acordo com os requisitos de controle de versão da API 2026 da Workiva.

   Observação: Atualmente, esse requisito se aplica apenas às APIs da plataforma.

   // Adicionar ou atualizar o cabeçalho X-Version pm.request.headers.upsert({ key: "X-Version", value: pm.environment.get("api_version") });

   

    

5. Selecione a guia Variables (Variáveis ).
6. Atualize a variável baseUrl para usar {{environment}} em vez de um domínio codificado.

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

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

Etapa 4: Salvar o token de acesso

1. Em Retrieve a token, selecione a guia Scripts e adicione o código abaixo à seção 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. Envie a solicitação. Você deve receber uma resposta 200 OK e seu access_token será salvo automaticamente.

Etapa 5: Importar e configurar a coleção da API Wdata e Chains

1. Acesse a página Wdata Code Generation.
2. Faça o download do arquivo .yaml e importe-o para o Postman (Siga as etapas descritas em Etapa 1: Importar a coleção da API da Workiva). Observação: O nome do arquivo .yaml provavelmente será o mesmo que Workiva API Collection.
3. Na coleção Wdata :
   • Defina o tipo de autorização como Bearer Token.

   • Use {{access_token}} como o valor do token.

     

   • Na guia Variables, atualize a variável baseUrl para usar {{environment}} em vez de um domínio codificado. Isso facilita a alternância entre ambientes, como app, eu, ou apac.
   • Certifique-se de que cada solicitação esteja definida como Inherit auth from parent.
   • Repita as mesmas etapas acima para a coleção Chains API Collection, garantindo que as configurações de autorização e a variável baseUrl sejam configuradas da mesma forma.

Solução de problemas

• Certifique-se de que você está fazendo referência ao ambiente correto. Se a coleção tiver como padrão o ambiente No, altere-a para e especifique o Environment.
• Confirme se a variável baseUrl é consistente nas configurações do ambiente e da coleção.
• Certifique-se de definir a variável de coleção baseUrl para usar {{environment}}; caso contrário, suas solicitações poderão falhar.
• Se sua solicitação retornar uma resposta 401 ou em branco, verifique novamente se os valores de Client ID, Client Secret, API_version e Environment estão corretos.