From the Trenches: Utilizando DocuSign API com Postman

•Publicado em 4 de nov. de 2024

Resumo•Leitura de 4 min

Aprenda como utilizar a API da Docusign com Postman usando a autenticação por JWT.

Criando a assertion em JWT
Criando o link de consentimento para chave de integração
Autenticando no Postman
Retornando dados de envelope

Tópicos relacionados

Criando a assertion em JWT

Criando o link de consentimento para chave de integração
Autenticando no Postman

Retornando dados de envelope

É comum utilizar APIs durante o desenvolvimento de aplicações, e a DocuSign oferece uma variedade de funcionalidades em sua API.

API pode ser utilizada por SDKs ou até mesmo realizando um método via cURL, porém seu uso também se estende a aplicações como Postman.

Neste artigo, iremos utilizar a API da DocuSign com Postman usando a autenticação por JWT. Antes de prosseguir com os passos abaixo, verifique se você possui os pontos abaixo:

Uma chave de integração criada no nosso ambiente de Demonstração
Acesso ao Postman

Criando a assertion em JWT

Antes de prosseguir com o uso das APIs, é necessário realizar a autenticação na DocuSign. A autenticação irá gerar um token, e esse token será utilizado nos headers da requisição para garantir que o seu usuário esteja logado em nosso sistema.

O token necessita da assertion em JWT. Os passos para criar a assertion encontra-se na nossa documentação How to get an access token with JWT Grant:

Acesse o site https://jwt.io/
Utilize o seguinte header:

{
  "alg": "RS256",
  "typ": "JWT"
}

No corpo (body), use o seguinte modelo.

{
  "iss": "<sua-chave-deintegração>",
  "sub": "<seu-id-de-usuario>",
  "aud": "account-d.docusign.com",
  "iat": <hora_atual_em_unix_epoch>,
  "exp": <hora_atual_em_unix_epoch+6000>,
  "scope": "signature impersonation"
}

As informações acima podem ser obtidas na página Aplicativos e Chaves (Apps and Keys).
Em "exp", você deve gerar a hora atual em Epoch e adicionar 6000. Este é o tempo de expiração do JWT.

Crie uma chave RSA dentro da sua chave de integração e utilize a chave Privada e Pública no campo Signature de https://jwt.io/. Se tudo estiver correto, a mensagem "Signature Verified" irá aparecer no final da página.
Salve o JWT em um bloco de notas.

Criando o link de consentimento para chave de integração

Para criar o link de consentimento para sua chave de integração, a URL deverá ter os seguintes dados:

A chave de integração
O tipo de consentimento (recomendamos impersonation e signature)
A URI de redirecionamento.

O modelo do link terá o seguinte formato:

https://account-d.docusign.com/oauth/auth?

response_type=code

&scope=SCOPES

&client_id=SUA_CHAVE_DE_INTEGRAÇÃO

&redirect_uri=URI_DE_REDIRECIONAMENTO

A URI de redirecionamento é configurada dentro da chave de integração, nas seção de configurações adicionais:

API Brasil Docusign

Neste exemplo, a URL será https://google.com e a URL com seus devidos dados se parecerá como o exemplo abaixo:

https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation&client_id=e7c1d6d1-8812-3c4f-b576-81fc1a4eb909&redirect_uri=https://google.com

Se as informações estiverem corretas, ao acessar a URL no browser, a tela seguinte irá aparecer. Clique em "Allow Access" para finalizar:

Doc is requesting access

Autenticando no Postman

Acesse Postman, e utilize o endereço https://account-d.docusign.com/oauth/token. Iremos utilizar um método do tipo POST. Na tabela body (corpo), selecione x-www-form-urlencoded, e adicione os seguintes parâmetros:

grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion: <jwt-assertion>

Demo docusign restapi

A requisição irá retornar o "access_token". Salve este token ou crie uma variável dentro do Postman para salvar este token automaticamente.

API docusign postman

Retornando dados de envelope

Crie uma nova requisição GET, porém, utilize a URL https://demo.docusign.net/restapi/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}.

Substitua as variáveis {{accountId}} pela ID de Conta API, encontrada dentro da página Aplicativos e chaves.

A variável {{envelopeId}} é o ID de envelope. Pode ser encontrada dentro da interface da DocuSign, no menu Acordos. Cada envelope enviado possui um ID único.

No header (cabeçalho) da requisição, adicione os seguintes campos:

Accept: application/json

Authorization: Bearer <access_token>

Atente-se que nesta requisição, iremos utilizar o token de acesso (access_token) retornado durante a autenticação.

A palavra "Bearer" deve vir antes do token, como mostra a imagem abaixo: