Блог

Мой вариант использования — создать конверт с агентом, чтобы указать имя и адрес электронной почты следующего подписывающего.

Я создал конверт по ПОЧТЕ {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes с телом запроса:

 {
  "recipients": {
    "agents": [
      {
        "clientUserId": "1",
        "email": "aaa@example.com.au",
        "name": "Agent",
        "recipientId": "1",
        "routingOrder": "1"
      }
    ],
    "signers": [
      {
        "clientUserId": "2",
        "email": "",
        "name": "",
        "recipientId": "2",
        "routingOrder": "2",
        "tabs": {
          "signHereTabs": [
            {
              "anchorIgnoreIfNotPresent": "false",
              "anchorString": "Signature_anchor_1",
              "anchorUnits": "pixels",
              "anchorYOffset": "0",
              "name": "Please sign here",
              "recipientId": "1"
            }
          ]
        }
      }
    ]
  },
  "emailSubject": "DocuSign API - Signature Request on Document Call",
  "documents": [
    {
      "documentId": "1",
      "name": "{{fileName}}",
      "documentBase64": "{{fileBase64}}"
    }
  ],
  "status": "sent"
}
  

После того, как агент указал имя и адрес электронной почты подписавшего, я не смог получить URL-адрес подписи по ПОЧТЕ {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}/views/recipient с телом запроса:

 {
  "clientUserId": "2",
  "userName": "",
  "email": "",
  "recipientId": "2",
  "returnUrl": "https://www.sample.com",
  "authenticationMethod": "email"
}
  

Ответ:

 {
    "errorCode": "INVALID_REQUEST_PARAMETER",
    "message": "The request contained at least one invalid parameter. A value was not found for parameter 'userName'."
}
  

Я попытался получить его с новым указанным именем и электронной почтой:

 {
  "clientUserId": "2",
  "userName": "new",
  "email": "new@example",
  "recipientId": "2",
  "returnUrl": "https://www.sample.com",
  "authenticationMethod": "email"
}
  

Но все равно получил ответ об ошибке:

 {
    "errorCode": "UNKNOWN_ENVELOPE_RECIPIENT",
    "message": "The recipient you have identified is not a valid recipient of the specified envelope."
}
  

Я пытался получить recipientId , вызвав get envelope API и используя recipientId для получения представления, но все еще не работает.

Как можно сгенерировать этот URL-адрес? Каким должно быть тело запроса?

Update:
With scenario below:

1. Envelope has 1 Agent and 1 Recipient, when the sender sends out the envelop, the email and name of the recipient are unknown for the sender, only agent knows the info (that’s why I put the name and email as empty for the recipient).
2. Agent received the request and put in the name and email address for that recipient
3. We want to get that embedded signing link for the recipient, but now seems that we could not retrieve it even with the info obtained by calling GET GET /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients

Update 2:

As suggested to put a place holder for the name and email and also add the clientUserId for the signer, I call the create envelope API with request body:

 {
  "recipients": {
    "agents": [
      {
        "clientUserId": "1",
        "email": "aaa@example.com.au",
        "name": "Agent",
        "recipientId": "1",
        "routingOrder": "1"
      }
    ],
    "signers": [
      {
        "clientUserId": "2",
        "email": "example@example.com",
        "name": "example",
        "recipientId": "2",
        "routingOrder": "2",
        "tabs": {
          "signHereTabs": [
            {
              "anchorIgnoreIfNotPresent": "false",
              "anchorString": "Signature_anchor_1",
              "anchorUnits": "pixels",
              "anchorYOffset": "0",
              "name": "Please sign here",
              "recipientId": "1"
            }
          ]
        }
      }
    ]
  },
  "emailSubject": "DocuSign API - Signature Request on Document Call",
  "documents": [
    {
      "documentId": "1",
      "name": "{{fileName}}",
      "documentBase64": "{{fileBase64}}"
    }
  ],
  "status": "sent"
}
  

For the agent, he cannot change the email/name for the signer, since when he accesses the DocuSign signing link, DocuSign pops a message «All recipients have been assigned«.

So I tried to use intermediaries instead of agents and call with the request body:

 {
  "recipients": {
    "intermediaries": [
      {
        "clientUserId": "1",
        "email": "aaa@example.com.au",
        "name": "Intermediary",
        "recipientId": "1",
        "routingOrder": "1"
      }
    ],
    "signers": [
      {
        "clientUserId": "2",
        "email": "example@example.com",
        "name": "example",
        "recipientId": "2",
        "routingOrder": "2",
        "tabs": {
          "signHereTabs": [
            {
              "anchorIgnoreIfNotPresent": "false",
              "anchorString": "Signature_anchor_1",
              "anchorUnits": "pixels",
              "anchorYOffset": "0",
              "name": "Please sign here",
              "recipientId": "1"
            }
          ]
        }
      }
    ]
  },
  "emailSubject": "DocuSign API - Signature Request on Document Call",
  "documents": [
    {
      "documentId": "1",
      "name": "{{fileName}}",
      "documentBase64": "{{fileBase64}}"
    }
  ],
  "status": "sent"
}
  

The intermediary can update the name/email for the signer. But after the intermediary change the info, DocuSign will send an email to the updated email address even the clientUserId is already set in the request body for that signer.

I’m wondering if this is the expected behaviour:

1. Whenever an intermediary updates a signer’s name/email, DocuSign will send the email to the updated email address regardless whether the clientUserId is set for that signer

This might be another question, but it seems DocuSign handles the update email event for signer and witness differently. I’m wondering scenario I observed is the expected one:

1. When a signer updates/adds the name/email for his witness, DocuSign will not send the email to the updated email address if the clientUserId is set for that witness

Update3:

After calling with the intermediaries param, I can retrieve the Signer’s signing URL by either calling with request body:

 {
  "clientUserId": "2",
  "userName": "example",
  "email": "example@example.com",
  "recipientId": "2",
  "returnUrl": "https://www.google.com",
  "authenticationMethod": "email"
}
  

OR

 {
  "clientUserId": "2",
  "userId": {{userId retrieved from get envelope recipients}},
  "recipientId": "2",
  "returnUrl": "https://www.google.com",
  "authenticationMethod": "email"
}
  

But after the intermediary changed the email/name of the recipient, none of the above request body could retrieve the signing URL. I tried both original and updated clientId and ( email name ) combination, but still not working.

I assume this is a design of DocuSign: it’s not allowed to retrieve the recipient’s signing URL after an intermediary changes the recipient’e email/name, this signing URL can be only obtained by that email sent by DocuSign. This email cannot be turned off event the clientUserId is set. Is it correct?

Update 4:
As suggested, I tried with the workflow option with request body:

 {
  "recipients": {
    "intermediaries": [
      {
        "clientUserId": "1",
        "email": "aaa@example.com.au",
        "name": "Intermediary",
        "recipientId": "1",
        "routingOrder": "1"
      }
    ],
    "signers": [
      {
        "clientUserId": "2",
        "email": "example@example.com",
        "name": "example",
        "recipientId": "2",
        "routingOrder": "2",
        "tabs": {
          "signHereTabs": [
            {
              "anchorIgnoreIfNotPresent": "false",
              "anchorString": "Signature_anchor_1",
              "anchorUnits": "pixels",
              "anchorYOffset": "0",
              "name": "Please sign here",
              "recipientId": "1"
            }
          ]
        }
      }
    ]
  },
  "workflow": {
    "workflowSteps": [
      {
        "action": "pause_before",
        "itemId": "2",
        "triggerOnItem": "routing_order"
      }
    ]
  },
  "emailSubject": "DocuSign API - Signature Request on Document Call",
  "documents": [
    {
      "documentId": "1",
      "name": "{{fileName}}",
      "documentBase64": "{{fileBase64}}"
    }
  ],
  "status": "sent"
}
  

Я могу приостановить рабочий процесс только перед порядком маршрутизации 2, поскольку возникнет ошибка 400, если я введу workflow параметр as для достижения «вставить приостановку рабочего процесса сразу после промежуточного получателя«:

   "workflow": {
    "workflowSteps": [
      {
        "action": "pause_after",
        "itemId": "1",
        "triggerOnItem": "routing_order"
      }
    ]
  },
  

После того, как промежуточный получатель обновил имя / адрес электронной почты, я выполнил вызов API, чтобы установить clientUserId для подписавшего, и это работает нормально. Но я не смог возобновить рабочий процесс, вызвав URL {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}?resend_envelope=true с телом запроса:

 {
    "workflow": {
        "workflowStatus": "in_progress"
    }
}
  

Статус подписавшего остался как created и не может быть обновлен до sent , таким образом, не удалось получить URL-адрес подписи для подписывающего. Как мы можем отменить рабочий процесс?

сегодня у каждого получателя в DocuSign должны быть электронная почта и имя. Я подозреваю, что по юридическим причинам, требующим указания имени, всегда будет применяться. В вашем сценарии есть имя и электронная почта, вы просто не знаете, что это такое, верно? Сначала вы можете выполнить вызов GET recipients для этого конвертаhttps://developers.docusign.com/docs/esign-rest-api/reference/Envelopes/EnvelopeRecipients/list /

 GET /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients
  

Затем вы получите имя электронной почты и сможете выполнить вызов POST для создания встроенного URL-адреса подписи.

После того, как Агент ввел имя и адрес электронной почты получателя, Docusign автоматически отправил электронное письмо для этого получателя. Мне интересно, можно ли отключить это электронное письмо?

Гораздо лучше было бы предоставить агенту приложение, которое позволяет им устанавливать имя / адрес электронной почты получателя. Приложение также установило бы атрибут client_user_id, чтобы электронные письма не отправлялись.

Требуется ли имя и электронная почта? Да, но если вы не знаете адрес электронной почты этого человека (и вы используете встроенную подпись), вы можете создать электронное письмо, которое включает имя подписавшего и использует example.com домен, поскольку этот домен не существует. Например, если подписавший — Пэт Джонсон, тогда используйте patjohnson@example.com в качестве адреса электронной почты.

Также помните, что если у вас нет адреса электронной почты подписавшего, то вам, вероятно (обсудите со своим юрисконсультом), нужен какой-то способ для подписавшего, чтобы получить копию того, что они подписали. Обычно DocuSign делает это, отправляя на электронную почту пользователя. Но если вы знаете, что электронное письмо поддельное, вам понадобится другой план.

Обновить

Я считаю, что когда intermediary получатель устанавливает имя / адрес электронной почты подписывающего лица, атрибуты подписывающего лица, включая client_user_id, сбрасываются. Таким образом, подписывающий получает электронное письмо с приглашением, поскольку он (на данный момент) является обычным подписывающим лицом.

Одним из исправлений является вставка паузы рабочего процесса сразу после промежуточного получателя. Затем используйте эту паузу, чтобы изменить имя подписывающего лица на client_user_id.