Cange
Integrações

Como configurar a integração do Cange com a DocuSign

13 de novembro de 202617 min de leitura0 visualizações
#Integração#Automação#Configuração

A integração nativa com a DocuSign faz uma automação do Cange pegar um anexo do cartão, criar um envelope na DocuSign com os signatários definidos nos campos do fluxo e, quando todos assinam, salvar o PDF assinado de volta em um campo de anexo do cartão. Neste manual você vai configurar essa integração do zero: primeiro na DocuSign, depois no Cange, e vai testar o ciclo completo.

O trabalho tem duas partes:

  • Na DocuSign: você cria um app de integração e obtém três valores, a Integration Key, o User ID e a chave privada RSA.
  • No Cange: você cria a conexão com esses valores, autoriza o acesso uma única vez e configura a automação.

Como a integração funciona

  1. O Cange se conecta à DocuSign em nome de um usuário da sua conta DocuSign, usando o método de autenticação JWT. Esse usuário é o remetente de todos os envelopes: o nome e o e-mail dele aparecem para os signatários.
  2. Quando a automação roda, o Cange envia o documento e a lista de signatários. A DocuSign manda o e-mail de assinatura para cada pessoa.
  3. Quando o envelope é concluído, a DocuSign avisa o Cange. O Cange baixa o PDF final, com todos os documentos do envelope em um arquivo só, e grava no campo escolhido do cartão.

Por que pedimos uma chave privada: no método JWT, quem prova a identidade é uma chave RSA que você gera na DocuSign. O Cange guarda a parte privada e a usa para pedir acesso em nome do usuário integrador. A própria DocuSign recomenda que o time de segurança da sua empresa avalie esse compartilhamento. Por isso, recomendamos usar um usuário dedicado à integração, e não a conta pessoal de alguém.

Antes de começar

Requisito Detalhe
Plano DocuSign Para usar em produção, a conta precisa de um plano pago que inclua acesso à API (Business Pro ou superior, ou um plano de API). Planos de teste (trial) e planos eSignature sem API não permitem ativar a integração. Na dúvida, confirme com o seu contato comercial da DocuSign.
Conta de desenvolvedor Toda Integration Key nasce em uma conta de desenvolvedor DocuSign (gratuita) e depois é promovida para produção. Crie uma em developers.docusign.com, se ainda não tiver.
Permissão Administrador da conta DocuSign de produção, ou acesso de desenvolvedor a ela, para promover a chave e configurar o app.
Usuário integrador Um usuário DocuSign ativo, com perfil de permissão que permita enviar envelopes (o perfil DS Sender é suficiente). Recomendado: um usuário dedicado, por exemplo contratos@suaempresa.com.br.
No Cange Permissão de administrador no fluxo onde a automação vai rodar.
Campos no fluxo Um campo de anexo com o documento, campos com nome e e-mail dos signatários e, se quiser o PDF assinado de volta, um segundo campo de anexo para receber o arquivo.

Teste primeiro no Sandbox. O Cange tem dois modos de conexão: Sandbox (conta de desenvolvedor, envelopes sem validade jurídica) e Produção. Recomendamos montar tudo no Sandbox, validar o fluxo completo e só depois repetir os passos de produção. Os valores de um ambiente não funcionam no outro.

Parte 1: configuração na DocuSign

Os nomes de menus abaixo seguem a interface da DocuSign em inglês, que é a que aparece na área de desenvolvedor.

Passo 1: crie o app e a Integration Key

  1. Entre na sua conta de desenvolvedor DocuSign, em admindemo.docusign.com.
  2. Abra Apps and Keys. Dependendo da versão da interface, o caminho é Settings ? Integrations ? Apps and Keys ou Admin ? Apps and Keys.
  3. Clique em Add App and Integration Key.
  4. Em nome do app, informe Cange e clique em Add.
  5. A DocuSign mostra a Integration Key, um código no formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Copie e guarde.

[IMAGEM: tela Apps and Keys da DocuSign com o app Cange criado e a Integration Key visível]

A DocuSign também está liberando o Developer Console, uma tela nova para gerenciar integrações. Se a sua conta já usa essa tela, o processo é o mesmo, com nomes de botões diferentes. Este guia segue a tela Apps and Keys.

Passo 2: configure a autenticação e gere a chave RSA

Ainda na tela de edição do app:

  1. Na seção Authentication, em User Application, marque Yes. Não é preciso gerar Secret Key: o método JWT não usa.
  2. Na seção Service Integration, clique em Generate RSA.
  3. A DocuSign mostra a chave pública e a chave privada. Copie a chave privada inteira, incluindo as linhas -----BEGIN RSA PRIVATE KEY----- e -----END RSA PRIVATE KEY-----, e guarde em local seguro.
  4. Clique em Close.

[IMAGEM: janela da DocuSign com a chave privada RSA gerada e o botão Close]

A chave privada só aparece uma vez. Depois de fechar a janela, não dá para ver de novo. Se perder, gere outro par de chaves e use o novo no Cange. A chave pública não é usada.

Passo 3: cadastre a URL de retorno do Cange

Ao autorizar a conexão, no Passo 8, a DocuSign devolve você para o Cange. Para isso, a URL de retorno precisa estar cadastrada no app.

  1. Na seção Redirect URIs, clique em Add URI.
  2. Cole a URL correspondente ao ambiente, conforme a tabela abaixo.
  3. Clique em Save no fim da página.
Ambiente Redirect URI
Sandbox https://api.cange.me/integration-callback/auth/docusign_oauth2_sbox
Produção https://api.cange.me/integration-callback/auth/docusign_oauth2_prd

A URL precisa ser idêntica, letra por letra, sem barra no final. O próprio Cange mostra o valor certo no campo OAuth Callback URL da tela de conexão, no Passo 7, com o botão Copiar ao lado. O valor muda conforme o modo escolhido, Sandbox ou Produção: na dúvida, copie de lá. Depois de salvar, a DocuSign pode levar até 5 minutos para aceitar a URL nova.

Passo 4: copie o User ID do usuário integrador

O User ID identifica o usuário em nome de quem o Cange vai enviar os envelopes. Ele não é o e-mail: é um código no mesmo formato da Integration Key.

  • Se o usuário integrador é você, o valor aparece no topo da página Apps and Keys, em My Account Information ? User ID.
  • Se é outra pessoa, vá em Users, abra o usuário e copie o User ID (em alguns menus aparece como API Username).

Na mesma página aparecem o API Account ID e o Account Base URI. Você não precisa informar esses dois valores no Cange: o Cange descobre os dois sozinho ao verificar a conexão.

Use um usuário que pertença a uma única conta DocuSign. Se o usuário integrador tiver acesso a mais de uma conta, por exemplo a conta da matriz e a de uma filial, o Cange pode enviar os envelopes pela conta errada. Nesse caso, fale com o suporte do Cange antes de conectar.

Com isso, você tem os três valores do Sandbox: Integration Key, User ID e chave privada. Se for testar primeiro, pule para a Parte 2 e volte ao Passo 5 depois.

Passo 5: leve a integração para produção (Go-Live)

  1. Na página Apps and Keys da conta de desenvolvedor, abra o app Cange.
  2. Em Integration Type, escolha Third-party integration key. É a opção para quando um software parceiro, no caso o Cange, pede que você use a sua própria chave. Essa escolha não pode ser alterada depois.
  3. Em Actions, clique em Select Go-Live account, entre com um administrador e escolha a conta DocuSign de produção.
  4. O resultado aparece na tela:

    • App is live: a promoção foi automática. Siga para o Passo 6.
    • Pending approval: a DocuSign vai revisar. Costuma levar de 24 a 48 horas, e pode chegar a 3 dias úteis.
    • Declined com o link Verification required: o administrador da conta de produção precisa fazer uma verificação de identidade, uma vez só. Depois, repita Select Go-Live account.
    • Not Allowed: o plano da conta de produção não permite integrações. Veja o requisito de plano em "Antes de começar".

A antiga exigência de 20 chamadas de API concluídas no Sandbox antes do Go-Live foi removida pela DocuSign em outubro de 2025. O Go-Live não tem custo.

Passo 6: configure o app na conta de produção

A Integration Key continua a mesma em produção, mas a chave RSA, a Redirect URI e o User ID não são copiados do Sandbox. Refaça na conta de produção:

  1. Entre na conta DocuSign de produção, em admin.docusign.com, e abra Apps and Keys.
  2. No app Cange, clique em Actions ? Edit.
  3. Confira que User Application está em Yes.
  4. Clique em Generate RSA e copie a nova chave privada.
  5. Em Redirect URIs, adicione a URL de Produção do Passo 3 e clique em Save.
  6. Copie o User ID do usuário integrador na conta de produção. Ele é diferente do User ID do Sandbox, mesmo que seja a mesma pessoa e o mesmo e-mail.
Valor Sandbox Produção
Integration Key Gerada no Passo 1 A mesma
Chave privada RSA Gerada no Passo 2 Nova, gerada no Passo 6
Redirect URI URL de Sandbox URL de Produção
User ID Da conta de desenvolvedor Da conta de produção
Autorização (consentimento) Feita no Sandbox Precisa ser feita de novo

Parte 2: configuração no Cange

Passo 7: crie a conexão com a DocuSign

  1. No Cange, abra o fluxo e vá em Automações. Crie uma nova automação, ou edite uma existente, e escolha o gatilho que deve disparar o envio, por exemplo "Cartão movido para a etapa Assinatura".
  2. Na ação, escolha Docusign ? Enviar um documento para assinatura.
  3. Na seção Integração com o Docusign, clique em Criar uma nova conexão.
  4. Em Escolha o modo de autenticação com o aplicativo, selecione Sandbox ou Produção, de acordo com o ambiente dos valores que você vai colar.
  5. Preencha os campos:
Campo no Cange O que colar
Nome da integração Um nome que identifique a conexão, por exemplo DocuSign Produção
OAuth Callback URL Já vem preenchido e não é editável. Use o botão Copiar e confira se o valor está nas Redirect URIs do app, do Passo 3. Termina em _sbox no modo Sandbox e em _prd no modo Produção.
Integration Key Integration Key do Passo 1
User ID User ID do usuário integrador, do ambiente escolhido
Private Key (RSA) Chave privada completa, do ambiente escolhido

[IMAGEM: tela de criação da conexão com a DocuSign no Cange, com os campos Nome da integração, OAuth Callback URL, Integration Key, User ID e Private Key]

Passo 8: autorize o acesso (consentimento)

Este passo é obrigatório e é feito uma vez por ambiente. Sem ele, a DocuSign recusa todas as chamadas do Cange.

  1. Clique em Conectar. O Cange salva a configuração e abre uma nova aba com o login da DocuSign. Se o navegador bloquear a janela, libere a abertura de janelas do Cange e tente de novo.
  2. Entre na DocuSign com o mesmo usuário cujo User ID você colou. Se outra conta já estiver logada no navegador, saia dela antes.
  3. A DocuSign mostra as permissões que o Cange está pedindo. Clique em Accept.
  4. A aba mostra a mensagem "Conexão realizada com sucesso! Você pode fechar esta janela e voltar para o Cange para continuar.". Feche a aba.
  5. De volta ao Cange, com o status Aguardando autorização, clique em Verificar conexão.
  6. O status muda para Conectado com sucesso. Clique em Fechar.

Se a verificação mostrar "Consentimento necessário", a autorização não foi concluída ou foi feita com outro usuário. Feche a janela, clique de novo em Criar uma nova conexão e repita os passos 7 e 8 entrando na DocuSign com o usuário integrador.

Passo 9: configure a ação de envio

Com a conexão selecionada, preencha os parâmetros da ação:

Parâmetro Obrigatório Como preencher
Documento Sim Campo de anexo com o arquivo a assinar. Se o campo tiver vários arquivos, todos vão no mesmo envelope. Use PDF de até 25 MB por arquivo.
Nome dos signatários Sim Campo com o nome de cada signatário. Para vários signatários, use um campo de cadastro com uma pessoa por item.
E-mail dos signatários Sim Campo com o e-mail de cada signatário, na mesma estrutura do campo de nome. Signatários sem e-mail são ignorados.
Ordem dos signatários Não Campo numérico que define quem assina primeiro (1, 2, 3...). Sem ele, a ordem segue a lista. A assinatura é sempre em sequência: cada pessoa só recebe o e-mail depois que a anterior assinar.
Enviar o documento para assinatura? Não Ativado: o envelope sai direto para os signatários. Desativado: o envelope fica como rascunho na pasta do usuário integrador na DocuSign, para revisão e envio manual.
Enviar um responsável como editor do documento? Não Um usuário do Cange que recebe o envelope antes dos signatários e pode ajustar o documento antes do envio.
Assunto da mensagem para os signatários Não Assunto do e-mail da DocuSign. Sem preencher, vai "Por favor, assine este documento".
Mensagem para os signatários Não Texto do e-mail. Aceita campos dinâmicos do cartão.
Documento assinado Não Campo de anexo onde o Cange salva o PDF final quando todos assinarem. Veja o Passo 10.
Definir posicionamento automático dos campos? Não Veja "Onde a assinatura aparece no documento", abaixo.
Texto(s) de ancoragem Não Textos do documento onde a assinatura deve ser colocada, separados por vírgula.
Workflow ID Não Código do fluxo de verificação de identidade (IDV) da DocuSign, para exigir verificação de documento com foto do signatário. Cole o código fixo. Recurso pago à parte na DocuSign.

[IMAGEM: parâmetros da ação Enviar um documento para assinatura preenchidos em uma automação do Cange]

Onde a assinatura aparece no documento

Configuração Resultado Quando usar
Posicionamento automático desativado Cada signatário escolhe onde assinar, arrastando a assinatura no documento. Documentos sem padrão fixo.
Posicionamento ativado, sem texto de ancoragem A assinatura de cada pessoa é colocada onde o nome dela aparece no documento. Contratos com bloco de assinatura que traz o nome de cada parte.
Posicionamento ativado, com texto de ancoragem Além do nome, a assinatura é colocada em cada ocorrência do texto informado, para todos os signatários. Documentos com um único signatário e um marcador próprio, por exemplo /assinar/.

O posicionamento pelo nome só vale quando o envelope é enviado direto para assinatura. No modo rascunho, sem texto de ancoragem, o Cange coloca um campo de assinatura em posição fixa na primeira página: ajuste na DocuSign antes de enviar.

Cuidados com a ancoragem. A DocuSign procura o texto em todo o documento, sem diferenciar maiúsculas e minúsculas, e coloca uma assinatura em cada ocorrência, inclusive quando o texto está dentro de outra palavra. Se o nome do signatário aparece também no cabeçalho do contrato, aparece um campo de assinatura ali também. Para evitar isso, use um marcador que só exista no bloco de assinatura. Um truque comum é escrever o marcador em fonte branca no modelo do documento: ele fica invisível para quem lê, mas a DocuSign encontra.

Passo 10: receba o documento assinado no cartão

Quando o parâmetro Documento assinado está preenchido, o Cange pede à DocuSign que avise quando o envelope for concluído. No momento em que o último signatário assina, a DocuSign chama o Cange, e o Cange salva o arquivo docusign_<id-do-envelope>.pdf no campo escolhido.

  • Não há nada a configurar na DocuSign para isso: o aviso vai dentro de cada envelope.
  • O PDF salvo junta todos os documentos do envelope em um arquivo só.
  • O retorno acontece só quando o envelope é concluído. Envelopes recusados ou cancelados não atualizam o cartão: acompanhe esses casos pela DocuSign.
  • O retorno funciona para automações que rodam sobre cartões de fluxo.

Passo 11: teste o fluxo completo

  1. Crie um cartão de teste com um PDF no campo de documento e o seu próprio e-mail como signatário.
  2. Dispare a automação.
  3. Confira o histórico da automação no Cange: a execução deve aparecer como sucesso.
  4. Abra o e-mail da DocuSign, assine e conclua.
  5. Aguarde alguns minutos e confira se o PDF assinado apareceu no campo Documento assinado do cartão.

Erros comuns

Onde aparece Mensagem Causa e solução
Página da DocuSign, ao conectar "redirect URI is not registered" ou "Invalid RedirectUri" A URL de retorno não está cadastrada no app daquele ambiente, ou tem diferença de uma letra. Refaça o Passo 3, ou o item 5 do Passo 6 em produção, e aguarde 5 minutos.
Página da DocuSign, ao conectar "The response type is not supported" User Application não está em Yes no app. Refaça o item 1 do Passo 2.
Verificar conexão, no Cange "Consentimento necessário" A autorização do Passo 8 não foi feita, foi feita com outro usuário ou em outro ambiente. Repita os passos 7 e 8 com o usuário integrador.
Verificar conexão, no Cange "Private key inválida" ou "A private key não é RSA" A chave foi colada pela metade ou sem as linhas BEGIN e END. Cole a chave inteira. Se não tiver mais a chave, gere outra, no Passo 2 ou no Passo 6.
Verificar conexão, no Cange issuer_not_found A Integration Key não existe no ambiente escolhido. Em produção, o Go-Live do Passo 5 ainda não foi concluído, ou a conexão foi criada no modo errado, Sandbox no lugar de Produção.
Verificar conexão, no Cange user_not_found ou invalid_subject O User ID é de outro ambiente, e o do Sandbox usado em produção é o caso mais comum, ou o usuário foi desativado.
Verificar conexão, no Cange no_valid_keys_or_signatures A chave privada é de outro ambiente ou foi removida do app. Em produção, use a chave gerada no Passo 6.
Histórico da automação "Nenhum documento encontrado para envio ao DocuSign" O campo de documento estava vazio no cartão.
Histórico da automação "Nenhum signatário encontrado para o DocuSign" Os campos de e-mail estavam vazios no cartão.
Histórico da automação USER_LACKS_PERMISSIONS O usuário integrador não tem permissão para enviar envelopes. Atribua o perfil DS Sender, ou superior, a ele na DocuSign.
Histórico da automação ACCOUNT_LACKS_PERMISSIONS O plano da conta não inclui o recurso usado: API, aviso de conclusão ou verificação de identidade. Confirme com a DocuSign.
Cartão O PDF assinado não chegou Confira se o envelope está como Completed na DocuSign e se o parâmetro Documento assinado foi preenchido antes do envio. Envelopes enviados antes desse ajuste não retornam. Persistindo, envie ao suporte do Cange o número do cartão e o ID do envelope.

Checklist

Na DocuSign, no Sandbox:

  • App Cange criado e Integration Key copiada
  • User Application em Yes
  • Chave privada RSA gerada e guardada
  • Redirect URI de Sandbox cadastrada
  • User ID do usuário integrador copiado

Na DocuSign, em produção:

  • Plano com acesso à API confirmado
  • Integration Type definido como Third-party integration key
  • Go-Live concluído, com status App is live
  • Nova chave RSA gerada na conta de produção
  • Redirect URI de Produção cadastrada na conta de produção
  • User ID de produção copiado

No Cange:

  • Conexão criada no modo certo, Sandbox ou Produção
  • Consentimento feito com o usuário integrador
  • Status Conectado com sucesso
  • Ação configurada com documento, nomes e e-mails
  • Teste completo: envio, assinatura e PDF de volta no cartão

Precisa de ajuda?

Se algo não funcionar depois de seguir este guia, abra um chamado com o suporte do Cange informando o ambiente (Sandbox ou Produção), a mensagem de erro exata e, se a falha for no envio, o número do cartão. Nunca envie a chave privada RSA por e-mail ou chamado.

Este artigo foi útil?