Objetivo
Este endpoint tem o objetivo de adicionar ou remover signatários de um envelope desejado, sendo possível adicionar ou remover um ou mais signatários ao mesmo tempo.
URL
/rest/signer/IntegrationEnvelope/{envelopeId}/signatories
Parâmetros
Para realizar a requisição via API é necessário fazer a autenticação da chave de acesso do usuário, você pode encontrar o passo a passo para realizar essa etapa, clicando aqui.
EnvelopeId: Este é um parâmetro obrigatório na requisição, corresponde ao ID do envelope que o signatário desejado está inserido, pode ser obtido através dos seguintes endpoints:
- /rest/signer/IntegrationEnvelope – endpoint de criação de envelope, será recebido o EnvelopeId no retorno da requisição se o envelope for criado com sucesso
- /rest/signer/IntegrationEnvelope/ListEnvelope – endpoint para listar os envelopes no tenant, o endpoint irá listar todos os envelopes, com suas informações, incluindo o envelopeId
O envelope desejado deve estar em um dos seguintes status para que seja possível realizar a edição:
- Pendente – Quando o envelope está pendente para ser assinado
- Expirado – Quando a data limite de assinatura do envelope já passou
- Recusado – Quando algum dos signatários se recusa a assinar o documento. Se o envelope possuir somente 1 signatário e 1 documento, não poderá ser editado após recusado.
- Em autorização – Quando o envelope está aguardando o documento ser autorizado para assinatura
RemoveSignatories: Este parâmetro é utilizado para remover algum signatário que está inserido no envelope desejado. Deve ser preenchido utilizando um ou mais “EnvelopeSignatoryId” para indicar qual será o signatário que deverá ser retirado do envelope. Este valor pode ser obtido através do seguintes endpoints:
- /rest/signer/IntegrationEnvelope/EnvelopeData – endpoint para detalhar as informações do envelope, inserindo o “envelopeId” na requisição, este endpoint retorna todas as informações do envelope, nessas informações contem o EnvelopeSignatoryId
- /rest/signer/IntegrationEnvelope/ListEnvelope – endpoint para listar os envelopes no tenant, inserindo o “SSN” do signatário ou deixando vazio, o endpoint irá listar todos os envelopes, com suas informações, incluindo o EnvelopeSignatoryId
Para remover mais de um signatário ao mesmo tempo, deve ser utilizado uma vírgula para separar cada “EnvelopeSignatoryId” na requisição. Ex: 123 , 456 , 789
Se este parâmetro não for preenchido no corpo da requisição, o envelope não terá nenhum signatário removido quando ocorrer a requisição.
AddSignatories: Este parâmetro é utilizado para inserir um ou mais signatários em um envelope especifico, desde que o signatário que será adicionado já exista na agenda de contatos. O parâmetro deve ser preenchido no corpo da requisição utilizando um ou mais “contactId”, valor utilizado para identificar o signatário desejado, podendo ser encontrado através dos seguintes endpoints:
- /rest/signer/IntegrationContact: endpoint para listar todos os contatos que o usuário possui na agenda de contatos. Neste endpoint o “contactId” é retornado somente como “Id”.
- /rest/signer/IntegrationContact/InsertContact: endpoint para criação de um novo contato na agenda de contatos, após a criação do contato, o endpoint irá retornar o “contactId” que foi criado, com todas as informações do contato.
- /rest/signer/IntegrationEnvelope/EnvelopeData: endpoint para detalhar as informações do envelope, inserindo o “envelopeId” na requisição, este endpoint retorna todas as informações do envelope, nessas informações, no campo “signatories” haverá o valor “id”, este que corresponde ao “contactId” do signatário
- /rest/signer/IntegrationEnvelope/ListEnvelope: endpoint para listar os envelopes no tenant, inserindo o “SSN” do signatário ou deixando vazio, o endpoint irá listar todos os envelopes, com suas informações, incluindo o “contactId” que estará presente no campo de “Signatories” com o valor “id”.
Para adicionar mais de um signatário ao mesmo tempo, deve ser utilizado uma vírgula para separar cada “ContactId” na requisição. Ex: 123 , 456 , 789
Se este parâmetro não for preenchido no corpo da requisição, o envelope não terá nenhum signatário inserido quando o endpoint for executado.
Retornos
O retorno do endpoint será de acordo com o resultado da requisição feita. Quando feita com sucesso, irá retornar para o usuário todos os signatários do envelope e suas informações, sendo que caso tenha sido feita uma remoção, não irá apresentar o signatário removido e se for feito uma inserção, mostrará também o signatário inserido.
Quando ocorrer algum erro, o endpoint retornará o erro indicando qual o problema que gerou o erro.
Exemplo de um erro quando o “EnvelopeSignatoryId” não existe no envelope para remove-lo.