From the Trenches: Chave de Integração e configurações para uso de API
Para utilizar a API da Docusign para uso próprio ou para integrar com sistemas externos, é comum precisar fornecer dados como Integration Key, RSA Key, Redirect URI e outros dados. Neste blog, iremos exemplificar como conseguir estes dados para você conseguir integrar e utilizar a API sem precisar entrar em contato com o suporte.
Chave de Integração (Integration Key/Client ID).
A chave de integração é sua chave única e exclusiva da sua conta. Ela deverá ser utilizada para realizar a conexão por API.
Esta mesma já foi chamada de Client ID, porém, foi renomeada para Chave de Integração. Caso uma documentação externa mencionar ClientID or Integration Key, saiba que é a mesma coisa que Chave de Integração.
Como gerar a chave de integração?
A Chave de Integração somente pode ser criada no nosso ambiente de Demonstração (Sandbox/Homologação).
Ou seja, caso você não tenha uma chave de integração na sua conta de Produção, você terá que criar uma no ambiente de demonstração. Este passo não pode ser pulado ou evitado.
Você pode criar uma conta gratuita em https://www.docusign.com/developers/sandbox, criar a chave e promovê-la para Produção. O passo a passo para criar são encontrados nesta documentação.
⚠️ Atenção! Para promover a chave você deve realizar o Go-Live.
Chaves RSA ou RSA Key (chaves secretas)
A chave RSA deverá ser criada dentro da configuração da sua chave de integração. Ou seja: você não pode criar uma sem ter uma chave de integração existente.
Estas chaves são necessárias para realizar a autenticação via API, visto que uma camada de segurança.
A Docusign limita 5 chaves RSA por chave de integração.
Para criar, você deve editar a sua chave de integração existente, ir para a seção de Integração de serviços e clicar na opção Gerar RSA.
Salve a chave pública e secreta em algum lugar seguro no seu servidor/máquina.
Salve a chave pública e secreta em algum lugar seguro no seu servidor/máquina.
Uri Base da Conta ou Base URL ou setBasePath
Estes dados estão relacionados com a localização do servidor onde sua conta está localizada. Como a Docusign possui mais de 5 servidores espalhados pelo globo, você deve fornecer o endereço correto da sua conta.
SDKs irão utilizar o método setBasePath, então se seu desenvolvedor mencionar este nome, saiba que é a mesma coisa que API Base URL ou URI Base da Conta.
Para pegar esta informação, acesse o menu Admin e vá para a página Aplicativos e chaves.
A URL estará informada no painel à direita como mostra a imagem abaixo:
Na imagem acima informa https://demo.docusign.net visto que as informações estão vindo do ambiente de demonstração. Em produção pode variar como informado nesta documentação (em inglês).
Conta API ou AccountID
Conta API ou AccountID é o ID (número único de identificação) da sua conta. Cada conta tem seu ID próprio e único.
Este dado é utilizado em quase todas chamadas API da Docusign e deve estar de acordo com o número da sua conta.
O número pode ser encontrado dentro da página Aplicativos e chaves ao centro do painel.
ID de usuário ou UserID
UserID ou ID de usuário é o identificador único de usuários dentro da Docusign. Toda vez que um usuário é criado na Docusign, ele recebe um ID único.
Para realizar chamadas API, é necessário fornecer o ID de usuário.
Você pode verificar o número de seus usuários na página Usuários. A página Aplicativos e chaves irá mostrar o ID de usuário do qual está logado na página, ou seja, irá mostrar o ID do seu usuário.
Ao utilizar SDKs, forneça somente o ID (GUID/UIID) e não o email.
Token (out Token JWT)
O Token é gerado durante a autenticação via API. A Docusign não fornece o Token para clientes, visto que ele é gerado por métodos de autenticação, e quem gera o Token, é o próprio cliente por SDK ou manualmente via requisição HTTP.
Basicamente, você irá utilizar dados como chave de integração, chave RSA, ID de usuário para gerar um token por métodos da Docusign e assim por diante utilizar este token para realizar chamadas API.
Caso você precise de Token, tenha em mente que ele é gerado pela pessoa que irá utilizar. Aplicações externas, tipo integrações, irão gerar o token internamente do lado deles para realizar as chamadas API.
No caso acima, você só deve garantir uma chave de integração, chave RSA e um ID de usuário e a integração deverá gerar o token internamente.
Redirect URI
Caso você necessite informar a URI de Redirecionamento, você deverá inserir uma URI de sua escolha (pode ser localhost ou até mesmo o endereço do Google) dentro das configurações da sua chave de integração.
Para adicionar, vá para a página Aplicativos e chaves, edite uma chave de integração e procure pela seção Configurações Adicionais e clique no botão Adicionar URI, como mostra a imagem abaixo:
Esta URI (URL) é utilizada no link do Consentimento de usuários. Após o usuário permitir acesso para a chave de integração, ele será redirecionado para URL inserida.
Este passo seria o último passo em integrações, porém, desenvolvedores ou membros do time de suporte podem exigir a URI cadastrada na chave de integração.
Mais detalhes sobre o uso dessa URI com consentimento de usuário, clique neste link (em inglês).
Conclusão e notas finais
Como mostrado acima, todas as informações necessárias para utilizar a API estão disponíveis dentro da plataforma.
Por mais que existam vários termos e variáveis, todas as informações são geradas na plataforma para uso direto.
Muitos desenvolvedores pedem somente os dados diretos com nomenclaturas que nem todo mundo conhece, porém, todas estão disponíveis para administradores da conta da Docusign.
Recursos Adicionais:
Publicações relacionadas
Confira as novidades do Docusign IAM ou comece a usar o eSignature grátis
