Guia de Conexão DocuSign 3.1¶

Visão Geral¶

Este guia descreve os requisitos do sistema e as instruções para conectar o Vinyl a um servidor de banco de dados Docusign Online como um pré-requisito para ser utilizado como um serviço em um aplicativo. Para conectar seus servidores, você deve ter o Vinyl 3.1 instalado.

Requisitos de Sistema¶

Servidor de Banco de Dados¶

Conta de desenvolvedor DocuSign

Navegador da Web do Cliente¶

• Chrome TM 60 ou mais recente

• Firefox 55 ou mais recente

• Safari 11.0.2 ou mais recente

• Carteiro v9.10 ou mais recente

Instruções de Conexão¶

Adquira Credenciais do DocuSign Sandbox¶

1. Faça login no DocuSign aqui: https://account-d.docusign.com/

2. Clique em Configurações no canto superior direito da página de aterrissagem

3. Na barra lateral esquerda, role para baixo até Integrações e clique em Aplicativos e Chaves

4. Crie um aplicativo clicando no botão ADICIONAR APLICATIVO E CHAVE DE INTEGRAÇÃO.

   

5. Digite o nome do aplicativo (este exemplo é Vinyl DocuSign)

6. Copie a chave de integração e armazene para a próxima etapa

   • Você também usará o ID da conta da API e o URI base da conta em etapas posteriores

7. Clique no botão + ADICIONAR CHAVE SECRETA em Autenticação e copie este valor, você precisa desta chave e não poderá visualizar a chave inteira posteriormente.

8. Role para baixo até Configurações adicionais e adicione este URI de redirecionamento: https://oauth.pstmn.io/v1/callback (Isso só é aplicável ao usar o Postman; se estiver usando outra ferramenta de desenvolvimento de API, consulte a documentação)

9. Clique em Salvar

10. Clique em Modelos no menu da barra superior

11. Clique em Novo no canto superior esquerdo para criar um novo modelo a ser usado durante a configuração da conexão

12. Dê um nome ao seu modelo e carregue um documento, clique em Avançar; opcionalmente, adicione áreas de assinatura ao documento e clique em Salvar.

13. Abaixo do nome do seu novo modelo, Clique em ID DO TEMPLATE, copie e salve este valor, você precisará dele em uma etapa posterior.

Adquira o Token de Atualização Usando o Postman¶

1. Crie uma nova solicitação POST com os seguintes parâmetros:

   • URL: https://account-d.docusign.com/oauth/token >/

   • Autorização: Autenticação Básica

     • Nome de usuário = Chave de integração da seção anterior

     • Senha = Chave secreta da seção anterior

   • Corpo: x-www-form-urlunencoded

     • Chave: grant_type

     • Valor: código_de_autorização

     • Chave: código

     • Valor: *você obterá este segundo valor na próxima etapa

2. Em um navegador da web acesse o seguinte site e substitua os valores que estão entre < e >, ou seja <value>.

   https://account-d.docusign.com/oauth/auth?response_type=code&scope=signatureextended&client_id=<Integration Key from DocuSign Sandbox>&state=a39fh23hnf23&redirect_uri=https://oauth.pstmn.io/v1/callback
   

3. Depois de pressionar Enter com o URI acima, copie o que está no campo URL e cole em algum lugar onde você possa ver o URL inteiro (é extremamente longo). Copie o valor depois de code= e antes de &state=, este é o seu valor de code, cole-o no valor da etapa 1 desta seção e clique em Enviar no Postman. **Esta etapa precisa ser realizada rapidamente, o token de atualização do navegador da web dura apenas cerca de 2 minutos. **

   

Configurar API de Token de Atualização no Vinyl¶

1. No menu Conectar, clique no link Conectar-se à sua empresa

2. Clique em Servidores de dados no lado esquerdo e clique em Criar

3. Configure o servidor da seguinte forma:

   • Nome: Nome reconhecível

   • Tipo: API REST

   • URL: https://account-d.docusign.com

   • Tipo de conteúdo da solicitação: Formulário

   • Tipo de conteúdo de resposta: JSON

   

4. Clique em Salvar.

Adicionar um Endpoint de API¶

1. Feche o pop-up Criar Servidor de Dados e clique no nome do Servidor que você acabou de criar na lista de servidores de dados.

2. No painel Endpoints no canto inferior esquerdo, clique em Criar

3. Adicione os seguintes detalhes:

   • Nome: Dê um nome ao seu endpoint

   • Endpoint: /oauth/token

   • Método: POST

4. Em seguida, você adicionará os seguintes parâmetros de endpoint clicando em Criar no painel Parâmetros de Endpoint no canto superior direito e adicionará os seguintes detalhes:

   • Parâmetro 1

     • Nome: Autorização

     • Tipo de dados: String

     • Valor do teste: Básico {Autorização do Carteiro}

       Este valor pode ser encontrado na aba Cabeçalhos no Postman após a chamada POST para recuperar o token de atualização. Será escrito básico seguido por um ID longo. (Talvez você precise procurar em cabeçalhos ocultos)

     • Tipo: Cabeçalho

     • Direção: Entrada

   • Parâmetro 2

     • Nome: grant_type

     • Tipo de dados: String

     • Valor de teste: refresh_token

     • Tipo: Consulta

     • Direção: Entrada

   • Parâmetro 3

     • Nome: update_token

     • Tipo de dados: String

     • Valor de teste: o token de atualização que você recuperou no Postman na etapa anterior

     • Tipo: Consulta

     • Direção: Entrada

   

5. Clique em Salvar

6. Clique em Testar conexão para obter o token de acesso para a próxima etapa

7. Adicione à entrada de amostra os parâmetros de consulta conforme a seguir:

   { "grant_type": "refresh_token", "refresh_token": "<refresh token from postman>"}
   

8. Clique em Importar

Configurar Vinyl para DocuSign¶

1. No menu Conectar, clique no link Conectar-se à sua empresa

2. Clique em Servidores de dados no lado esquerdo e clique em Criar

3. Configure o servidor da seguinte forma:

   • Nome: Nome reconhecível

   • Tipo: API REST

   • URL: https://demo.docusign.net/restapi (Isto é do DocuSign Sandbox, consulte a primeira seção)

   • Tipo de conteúdo da solicitação: JSON

   • Tipo de conteúdo de resposta: JSON

   

Adicionar um Endpoint de API para Modelo DocuSign¶

1. Feche o pop-up Criar Servidor de Dados e clique no nome do Servidor que você acabou de criar na lista de servidores de dados.

2. No painel Endpoints no canto inferior esquerdo, clique em Criar

3. Adicione os seguintes detalhes:

   • Nome: Dê um nome ao seu endpoint

   • Endpoint: /v2/accounts/<AccountID>/envelopes

   • Método: POST

4. Em seguida, você adicionará os seguintes parâmetros de endpoint clicando em Criar no painel Parâmetros de Endpoint no canto superior direito e adicionará os seguintes detalhes:

   • Parâmetro 1

     • Nome: ID da conta

     • Tipo de dados: String

     • Valor de teste: ID da conta API do DocuSign Sandbox (consulte a primeira seção)

     • Tipo: Consulta

     • Direção: Entrada

   • Parâmetro 2

     • Nome: Autorização

     • Tipo de dados: String

     • Valor de teste: Portador <Returned Access Token from the Token API>

     • Tipo: Cabeçalho

     • Direção: Entrada

   • Parâmetro 3

     • Nome: EmailBody

     • Tipo de dados: String

     • Valor de teste: Corpo Email de sua escolha, neste exemplo, "Um documento precisa ser assinado"

     • Tipo: Consulta

     • Direção: Entrada

   • Parâmetro 4

     • Nome: EmailAssunto

     • Tipo de dados: String

     • Valor do teste: Assunto Email de sua preferência, neste exemplo, "Assinatura"

     • Tipo: Consulta

     • Direção: Entrada

   • Parâmetro 5

     • Nome: status

     • Tipo de dados: String

     • Valor de teste: enviado

     • Tipo: Consulta

     • Direção: Entrada

   • Parâmetro 6

     • Nome: TemplateID

     • Tipo de dados: String

     • Valor de teste: o ID do modelo da primeira seção

     • Tipo: Consulta

     • Direção: Entrada

5. Clique em Testar conexão para garantir que os parâmetros foram inseridos corretamente e para visualizar os resultados do teste, o EnvelopeID será usado na próxima etapa.

6. Clique no botão Voltar no canto superior esquerdo para retornar ao Web Service para adicionar endpoint adicional

Adicione um Endpoint de API para Status do Documento¶

1. No painel Endpoints no canto inferior esquerdo, clique em Criar

2. Adicione os seguintes detalhes:

   • Nome: Dê um nome ao seu endpoint

   • Endpoint: /v2/accounts/<AccountID>/envelopes/<EnvelopeID>

   • Método: GET

3. Em seguida, você adicionará os seguintes parâmetros de endpoint clicando em Criar no painel Parâmetros de Endpoint no canto superior direito e adicionará os seguintes detalhes:

   • Parâmetro 1

     • Nome: ID da conta

     • Tipo de dados: String

     • Valor de teste: ID da conta API do DocuSign Sandbox (consulte a primeira seção)

     • Tipo: Consulta

     • Direção: Entrada

   • Parâmetro 2

     • Nome: Autorização

     • Tipo de dados: String

     • Valor de teste: Portador <Returned Access Token from the Token API>

     • Tipo: Cabeçalho

     • Direção: Entrada

   • Parâmetro 3

     • Nome: EnvelopeID

     • Tipo de dados: String

     • Valor de teste: ID do envelope que foi retornado ao testar o endpoint anterior

     • Tipo: Consulta

     • Direção: Entrada

4. Clique em Testar conexão para garantir que os parâmetros foram inseridos corretamente e para visualizar os resultados do teste

Torne as Tabelas DocuSign Públicas para Uso Posterior¶

1. No Vinyl IDE, clique em Build Your Application

2. Clique em Data Storage Layer e em Web Services encontre a API DocuSign Rest que você criou na etapa anterior

3. Clique no ícone de engrenagem Tabelas

4. Para cada tabela, clique duas vezes na tabela e clique em Edge Case Settings

5. Em Acesso público, clique em Permitir leitura e Permitir gravação

6. Execute as mesmas etapas para a API REST do token DocuSign e quaisquer outros endpoints que você criou para informações do DocuSign.

Configurar Regras de Vinyl para DocuSign¶

Adicionar Colunas para Informações do DocuSign¶

1. No Vinyl IDE, clique em Build Your Application

2. Clique em Business Logic Layer e encontre a fonte de dados na qual deseja armazenar as informações do DocuSign

3. No painel Fonte de dados da camada comercial no lado direito, clique em Fontes de link e adicione a API REST DocuSign que você criou na etapa anterior *certifique-se de ter marcado as tabelas como Permitir leitura/gravação*

4. Clique no ícone Business Objects e encontre a tabela onde você gostaria de armazenar as configurações do DocuSign (este exemplo usará ParamDocusign)

5. Na tabela, crie as seguintes colunas:

   -DocusignBaseURL (NVarchar(50))

   • DocusignGrantType (NVarchar(50))

   • DocusignRefreshToken (NVarchar(-1))

   • DocusignClientIDSecretID (NVarchar(-1))

6. Após a criação das colunas, clique em Resultados e adicione valores às seguintes colunas:

   • DocusignBaseURL: o URL base da sandbox DocuSign

   • DocusignGrantType: o valor literal da string 'refresh_token'

   • DocusignRefreshToken: o parâmetro de endpoint refresh_token na API REST do Token (a primeira API REST que você criou)

   • DocusignClientIDSecretID: o parâmetro do endpoint de autorização na API REST do token

7. Você também pode adicionar outras colunas para editá-las na UI, como Corpo Email, Assunto Email e Função (estes são parâmetros do modelo DocuSign).

Criar Regra de Inserção XP para Inserir Credenciais na Chamada POST do Token¶

1. Na etapa anterior, navegue de volta para o App Workbench

2. No painel central, clique em Adicionar uma regra de negócios para criar um novo objeto de negócios.

3. Preencha os seguintes dados:

   • Nome: Tabela (Inserir token de acesso de atualização)

   • Objetivo: XP CRUD

   • Desmarque "Pular camada comercial"

   • Ação: Inserir

   • Fonte Data Fonte: Banco de dados onde está armazenada a tabela com as informações do DocuSign

   • Fonte de dados de destino: a primeira API REST que você criou para atualizar o token de acesso

   • Destino: Tabela da API Token de atualização (neste exemplo, Token)

   

4. No painel Tabelas, clique em +Tabelas e adicione a Tabela da fonte de dados de origem onde as informações do DocuSign estão sendo armazenadas. Neste caso, ParamDocusign.

5. Na aba colunas, encontre as colunas que você designou para armazenar o token de atualização, o ClientID/SecretID e o tipo de concessão, direcione-as para suas colunas correspondentes na tabela Token, conforme mostrado abaixo.

   

Crie uma Regra de Atualização XP para Atualizar o Token de Acesso¶

1. Na etapa anterior, navegue de volta para o App Workbench

2. No painel central, clique em Adicionar uma regra de negócios para criar um novo objeto de negócios.

3. Preencha os seguintes dados:

   • Nome: Tabela (Atualizar Token de Acesso de Atualização)

   • Objetivo: XP CRUD

   • Desmarque "Pular camada comercial"

   • Ação: Atualizar

   • Fonte Data Fonte: A primeira API REST que você criou para atualizar o token de acesso

   • Fonte de dados de destino: onde a tabela com informações do DocuSign está localizada

   • Target: Tabela onde as informações do DocuSign são armazenadas, ParamDocusign neste exemplo

   

4. No painel Tabelas, clique em Criar e adicione a Tabela com o token de acesso (este é o nome do endpoint que você criou na primeira API REST).

5. Clique em Todos para adicionar todas as colunas da tabela

6. Encontre a coluna chamada access_token e direcione-a para a coluna DocusignClientIDSecretID que você criou na tabela.

7. Adicione API Account ID a ParamDocusign como uma coluna e insira seu valor

8. Adicione API Account ID como parâmetro no Refresh Token Endpoint e insira seu valor

9. Na regra de atualização, defina o ID da conta da API do token de atualização para direcionar o AccountID do ParamDocusign na ligação de tipo e defina-o como PK. Isso tem o benefício adicional de que, se você decidir adicionar mais contas DocuSign ao aplicativo, isso ajudará a acomodar essa configuração.

   

Criar Agendamento para Executar Evento de Atualização de Token de Acesso¶

1. Como o token de acesso expira e precisa ser atualizado regularmente, adicione esta regra a um evento e crie um agendamento.

2. Crie o evento navegando até a camada Business Logic e no pop-up Events para ParamDocusign, clique em +Table Event.

   • Nome: RefreshToken

   • Atualizar Escopo: Linha

   Nota

   Certifique-se de que em Caso extremo o Tipo de execução esteja definido como Iniciar via agendamento com simultaneidade máxima: 1.

   

3. Em Ações, clique em Registrar Existente e adicione a regra CRUD criada anteriormente: Tabela (Atualizar Token de Acesso de Atualização).

4. Em seguida, navegue até Vinyl Monitor (no canto inferior esquerdo)  Agendas. Dê um nome ao seu agendamento e escolha a Aplicação onde será criado o evento que você criou para a regra. Deixe a Frequência como está em “Execução Periódica do Cronograma”. Em Informações de agendamento, defina a frequência de execução do agendamento; recomenda-se 4 horas.

   

   

Agora que você está atualizando seu token de acesso de acordo com uma programação, você pode manter uma conexão com sua API DocuSign. Crie outras regras XP CRUD conforme necessário para enviar ou recuperar informações da conta DocuSign conectada, como o status do documento e os endpoints do modelo criados na segunda API REST.

Alguns recursos podem incorrer em custos, como retornar um arquivo usando um webhook. Outra opção é usar o plugin HTTP retriever.

Promovendo Aplicação para Produção da DocuSign¶

Quando os endpoints e as regras CRUD que você criou estiverem funcionando de forma consistente, você estará pronto para promover este aplicativo para DocuSign Production. Para fazer isso, você precisará revisar a API no DocuSign. Para passar na revisão, você deve ter 20 chamadas de API bem-sucedidas em um único dia.

1. Navegue até o link DocuSign Sandbox na primeira etapa e clique em Admin e, em seguida, clique em Apps & Keys no menu do lado esquerdo

2. Em Aplicativos e chaves de integração encontre o aplicativo que você criou na primeira etapa e clique em Ações, selecione Iniciar revisão de entrada em operação e insira uma data com 20 ou mais chamadas de API bem-sucedidas

3. Um administrador do DocuSign revisará e autenticará manualmente a solicitação. Isso pode levar até 3 dias úteis.

4. Após a autenticação do Go-Live, as etapas anteriores precisarão ser repetidas com as credenciais do Production DocuSign. A Chave de Integração permanecerá inalterada, mas as demais credenciais serão diferentes e precisarão ser atualizadas no Postman e no Vinyl.

5. Alterações nas etapas acima:

   • No Postman, crie uma nova chamada GET com a URL: https://account.docusign.com/oauth/userinfo

   • Na resposta da chamada GET, copie o "base_uri" para utilizar nos POSTs, GETs e HTTP Retrieve URLs do ambiente de produção.

   • Ao criar a API Refresh Token para produção, o URL é https://account.docusign.com