Guia de Conexão DocuSign¶

Visão Geral¶

Este guia descreve os requisitos do sistema e as instruções para conectar App Builder para um servidor de banco de dados Docusign Online como pré-requisito para ser utilizado como um serviço em um aplicativo.

Requisitos do 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

• Postman v9.10 ou mais recente

Instruções de Conexão¶

Adquira Credenciais do Sandbox do DocuSign¶

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 é App Builder 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á visualizá-la inteira mais tarde.

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

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 MODELO, copie e salve este valor, você precisará dele em uma etapa posterior.

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

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: authorization_code

     • 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. Após 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 (ele é extremamente longo). Copie o valor depois de code= e antes de &state=, este é o seu valor code, cole-o no Valor da etapa 1 nesta seção e clique em Enviar no Postman. **Esta etapa precisa ser feita rapidamente, o token de atualização do navegador da web dura apenas cerca de 2 minutos. **

   

Configurar API de Token de Atualização em App Builder¶

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

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

3. Configure o servidor da seguinte maneira:

   • 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 da 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 de teste: Básico {Autorização do Postman}

       Este valor pode ser encontrado na aba Headers no Postman após a chamada POST para recuperar o token de atualização. Ele dirá basic seguido por um ID longo. (Você pode ter que 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: refresh_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 da seguinte forma:

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

8. Clique em Importar

Configurar App Builder para DocuSign¶

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

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

3. Configure o servidor da seguinte maneira:

   • Nome: Nome reconhecível

   • Tipo: API REST

   • URL: https://demo.docusign.net/restapi (Isto é do DocuSign Sandbox, referência à primeira seção)

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

   • Tipo de conteúdo de resposta: JSON

   

Adicionar um Endpoint de API para o 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: AccountID

     • Tipo de dados: String

     • Valor de teste: ID da conta da API do DocuSign Sandbox (referência à 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 de teste: Assunto Email de sua escolha, 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 Serviço da Web para adicionar um endpoint adicional

Adicionar 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: AccountID

     • Tipo de dados: String

     • Valor de teste: ID da conta da API do DocuSign Sandbox (referência à 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

Tornar as Tabelas do DocuSign Públicas para Uso Posterior¶

1. Do App Builder IDE, clique em Criar seu aplicativo

2. Clique em Camada de armazenamento de dados e em Serviços da Web 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 DocuSign Token e quaisquer outros endpoints que você criou para as informações do DocuSign.

Configurar App Builder regras para DocuSign¶

Adicionar Colunas para Informações do DocuSign¶

1. Do App Builder IDE, clique em Criar seu aplicativo

2. Clique em Camada de lógica de negócios e encontre a fonte de dados na qual deseja armazenar as informações do DocuSign

3. No painel Fonte de dados da camada de negócios, no lado direito, clique em Vincular fontes e adicione a API REST do 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á o ParamDocusign)

5. Na tabela, crie as seguintes colunas:

   • URLDocusignBase (NVarchar(50))

   • Tipo de concessão Docusign (NVarchar(50))

   • Token de atualização do Docusign (NVarchar(-1))

   • DocusignClientIDSecretID (NVarchar(-1))

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

   • DocusignBaseURL: A URL base da sandbox do 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 de endpoint de autorização na API REST do token

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

Crie uma Regra de Inserção XP para Inserir Credenciais na Chamada de Postagem do Token¶

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

2. No painel do meio, clique em Adicionar uma regra comercial para criar um novo objeto comercial.

3. Preencha os seguintes detalhes:

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

   • Objetivo: XP CRUD

   • Desmarque "Ignorar camada de negócios"

   • Ação: Inserir

   • Data de origem 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 de Token de atualização (neste exemplo, Token)

   

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

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

   

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

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

2. No painel do meio, clique em Adicionar uma regra comercial para criar um novo objeto comercial.

3. Preencha os seguintes detalhes:

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

   • Objetivo: XP CRUD

   • Desmarque "Ignorar camada de negócios"

   • Ação: Atualizar

   • Data de origem Fonte: A primeira API REST que você criou para atualizar o Access Token

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

   • Alvo: 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 ao ParamDocusign como uma coluna e insira seu valor

8. Adicione API Account ID como um 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 Alvo do AccountID do ParamDocusign na vinculaçã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.

   

Crie uma Programação para Executar o Evento de Atualização do Token de Acesso¶

1. Como o Access Token expira e precisa ser atualizado regularmente, adicione esta regra a um evento e crie uma programação.

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

   • Nome: RefreshToken

   • Escopo de atualização: Linha

   Nota

   Certifique-se de que em Edge case 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é App Builder monitor (no canto inferior esquerdo)  Agendamentos. Nomeie seu agendamento e escolha o Aplicativo onde o evento que você criou para a regra é criado. Deixe a Frequência como está em "Execução Periódica do Agendamento". Em Informações de Agendamento, defina a frequência para o agendamento ser executado, 4 horas é o recomendado.

   

   

Agora que você está atualizando seu token de acesso em um cronograma, 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 os endpoints Document Status e Template criados na segunda API REST.

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

Promoção de Aplicação para Produção DocuSign¶

Quando os endpoints e as regras CRUD que você criou estiverem funcionando consistentemente, você estará pronto para promover este aplicativo para o DocuSign Production. Para fazer isso, você precisará ter a API revisada 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 do DocuSign Sandbox na primeira etapa e clique em Admin, depois clique em Aplicativos e chaves 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, depois 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 DocuSign de produção. A chave de integração permanecerá inalterada, mas as outras credenciais serão diferentes e precisarão ser atualizadas no Postman e App Builder.

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 usar nos POSTs, GETs e URLs de recuperação HTTP para o ambiente de produção.

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