Мы делаем это стоя. В зимней одежде. Под пристальным взглядом чиновника, сотрудника банка или страховой службы. Даже если делать это дома с комфортом, остаётся риск совершить ошибку и начать заново. Я говорю о работе с бумажными документами, ведь чаще всего это происходит именно так.

Избежать ошибок такого рода помогает автоматизация заполнения. В этой статье я расскажу про то, как помогал одному клиенту Лайв Тайпинг автоматизировать заполнение и подпись бланков страховых компаний с помощью сервиса DocuSign. После его введения количество клиентов и их лояльность повысились.

Что такое DocuSign?

DocuSign — это сервис, позволяющий загружать, отправлять на подпись, просматривать, подписывать и отслеживать статус документов. Делать это можно как из интерфейса сервиса, так и с помощью собственного клиента, который должен использовать API и Embedded View для просмотра и подписи документов.

Правовой статус

DocuSign может работать как с факсимильными, так и с цифровыми подписями. Если вы планируете работать на западном рынке, то проблем с этим возникнуть не должно. В России вам нужно учитывать, использование факсимиле определяется законодательством или специальным соглашением сторон. Есть ряд случаев, в которых использовать факсимиле нельзя. Более подробно об этом можно прочитать на портале «Гарант».

Безопасность

Безопасность документов и электронных подписей сертифицирована в соответствии со стандартом ISO 27001, определяющим основные положения в области систем информационной безопасности.
Все данные между клиентом и сервисами DocuSign передаются в зашифрованном виде по протоколу HTTPS. Документы и шаблоны, которые хранятся в DocuSign, зашифрованы с помощью алгоритма AES-256.

HIPAA Compliance

DocuSign позволяет работать с документами и электронными подписями в полном соответствии с HIPAA (Health Insurance Portability and Accountability Act, или закон США «О перемещаемости и подотчётности страхования здоровья», изданный в 1996 году). Закон определяет стандарты по обеспечению конфиденциальности информации о здоровье: состоянии здоровья, прохождении лечения или оплате медицинских услуг.

Начало работы

Наша цель — заполнять и отправлять бланки с помощью DocuSign.

Предположим, что нам нужно отправлять один и тот же PDF-документ разным людям. Мы могли бы отправлять его по почте вручную, однако для этого в DocuSign существует специальный механизм. Механизм оперирует следующими сущностями:

• Template. Сущность инкапсулирует в себе PDF-документ, поля документа и соотношения между полями и ролями получателей. Это значит, что одно поле с подписью может быть для нанимаемого сотрудника, а другое — для начальника отдела кадров или директора;
• Envelope. Контейнер для хранения и отправки одного и более многостраничных документов.

Процесс работы с документами состоит из:

1. создания шаблона (Template);
2. отправки документа выбранным получателям;
3. сохранения конечного документа.

Разберём каждый шаг по отдельности.

Регистрация демо-аккаунта

Для получения доступа ко всем функциям DocuSign необходимо создать демо-аккаунт. Для этого в разделе Developers на главной странице DocuSign нажмите кнопку Create Sandbox:



Остаётся подтвердить свою учетную запись, и мы готовы идти дальше.

Создание шаблона

Для создания шаблона:

1. перейдите во вкладку Templates и нажмите New -> Create Template;
2. введите название и описание для шаблона:



3. Загрузите документы:



4. Добавьте получателей. Для повторного использования и отправки шаблона разным получателям можно задать только название роли (например, employee для роли сотрудников компании):



5. Нажмите кнопку Next.

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



У каждого поля есть ряд параметров. На параметре Data Label стоит заострить своё внимание. Его можно использовать как идентификатор при работе с данными шаблона или документа через API. Стоит отметить, что Data Label — не уникальное значение, поэтому поля с ним могут дублироваться. Это полезно, если вам нужно автоматически заполнить сразу несколько полей с именем одного и того же человека.

Отправление документа

Чтобы отправить документ получателям, которые его затем заполнят и подпишут, необходимо нажать на кнопку Use напротив выбранного шаблона. После этого откроется окно, в котором нужно ввести имена и email’ы получателей:



После того, как вы отправили документ, выбранным получателям придут уведомления с просьбой проверить, заполнить и подписать документ. В письме будет ссылка на форму с документом. Если у этого документа только один получатель, то после подписания его статус будет заменён на Completed, что будет видно в интерфейсе DocuSign. После этого заполненный и подписанный документ можно скачать. В случае, если получателей два и больше, статус документа останется прежним (Sent).

Всё то, что мы сейчас проделали вручную (отправили документ нужным получателям, а получатели заполнили его), можно делать автоматически, используя API. Об этом пойдёт речь в следующем разделе.

Начало работы с API

У DocuSign есть два интерфейса API: SOAP и REST. Мы будем рассматривать второй вариант, поскольку он более нагляден, а также содержит в себе наиболее полную реализацию методов. REST API позволяет подписывать документы, отправлять документы на подпись, а также автоматизировать документооборот.

Для работы с REST API нам нужно авторизоваться. Для этих целей в API добавлена возможность передавать данные для авторизации в специальном заголовке, в котором должно быть имя пользователя, пароль, а также Integrator Key.

Для начала разберёмся, как получить Integrator Key, а затем вернёмся к составлению запросов к API.

Получаем Integrator Key

Integrator Key (также Client ID) — это уникальный идентификатор для получения доступа к DocuSign API. Для одного аккаунта может быть зарегистрировано несколько таких ключей. Сделано это для того, чтобы разделить окружения и использовать свой ключ для каждого из них. Изначально в новых аккаунтах ключей нет, поэтому придётся его создать. Для этого вам необходимо зайти в свой аккаунт и выполнить эти шаги:

1. Перейдите в DocuSign Admin:



2. В меню слева выберите API and Keys:



3. Нажмите ADD INTEGRATION KEY:



4. Добавьте описание приложения:



5. Нажмите Add

Готово. Теперь ключ можно найти в секции My Integrator Keys.

Создаём запросы к DocuSign

Каждый запрос к DocuSign должен сопровождаться заголовком X-DocuSign-Authentication, где в формате JSON передаются имя пользователя, пароль и Integrator Key. Такой формат следует использовать только для интеграции сторонних сервисов с DocuSign. Для работы с клиентскими приложениями (например с приложением на iOS) необходимо использовать OAuth.

Нашим первым запросом к DocuSign должен быть запрос на получение информации об аккаунте. Там же будет находиться так называемый baseUrl — url, который должен использоваться для составления последующих запросов к DocuSign.

$ curl -i -H 'X-DocuSign-Authentication:
              { "Username": "developer@example.com",
                "Password": "example",
                "IntegratorKey": "00000000-aaaa-bbbb-cccc-0123456789b" }'          https://demo.docusign.net/restapi/v2/login_information

{
  "loginAccounts": [
    {
      "name": "Developer",
      "accountId": "9999999",
      "baseUrl": "https://demo.docusign.net/restapi/v2/accounts/9999999",
      "isDefault": "true",
      "userName": "Dev Eloper",
      "userId": "00000000-aaaa-bbbb-cccc-0123456789a",
      "email": "developer@example.com",
      "siteDescription": ""
    }
  ]
}

Вооружившись baseUrl и заголовком X-DocuSign-Authentication, мы готовы делать запросы к API.

Получение шаблона

Предположим, что у вас уже есть база шаблонов, которую проще всего слелать через интерфейс DocuSign. Мы будем использовать шаблон, который уже создали ранее. В качестве примера возьмём согласие на обработку персональных данных, в котором нам необходимо заполнить поля с данными о получателе документа.

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

$ curl -i -H 'X-DocuSign-Authentication:
              { "Username": "developer@example.com",
                "Password": "example",
                "IntegratorKey":"00000000-aaaa-bbbb-cccc-0123456789b" }'          https://demo.docusign.net/restapi/v2/accounts/9999999/templates/00000000-aaaa-bbbb-cccc-0123456789c

Данные о полях шаблона содержатся в свойстве tabs, которое принадлежит свойству recipients. Из всего ответа сейчас нас интересует именно оно:

{
  "recipients": {
    "signers": [
      {
        "tabs": {
          "signHereTabs": [ ... ],
          "dateSignedTabs": [ ... ],
          "textTabs": [ ... ]
        },
        "name": "",
        "email": "",
        "roleName": "employee"
      },
      {
        "name": "",
        "email": "",
        "roleName": "hr"
      }
    ],
    "agents": [],
    "editors": [],
    "intermediaries": [],
    "carbonCopies": [],
    "certifiedDeliveries": [],
    "inPersonSigners": [],
    "recipientCount": "2"
  }
}

В DocuSign существует семь типов получателей: Agents, Carbon Copies, Certified Deliveries, Editors, In Person Signers, Intermediaries, и Signers. В нашем шаблоне мы используем только Signers*, поэтому и рассматривать мы будем только этот тип.

*Своим названием этот тип говорит о том, что его получатели должны подписать документ. Это вовсе не обязательно: если не назначить этому пользователю поля, которые он должен заполнить (или подписать), то ему будет достаточно открыть документ и просмотреть его.

Как уже было упомянуто выше, у каждого получателя есть свойство tabs, в котором содержатся все поля в документе. Поля делятся ещё на несколько типов. Мы не будем рассматривать все из них и в целях экономии времени возьмем только textTabs (поля для ввода текста) и signHereTabs (поля для подписей). Это два основных поля, которые чаще всего встречаются в документах.

Перейдём к автозаполнению.

Заполнение полей и отправка документа получателям

Для того, чтобы DocuSign сам подставил нужные значения, при создании документа необходимо передать список всех получателей, добавив свойство tabs для получателей, которым вы хотите заполнить поля.

Поле обязательно должно содержать свойства name, tabLabel, xPosition, yPosition, а также значение поля ввода value. Мы уже говорили про tabLabel выше — это поле пригодится нам для его идентификации. Например, с полем с tabLabel, равным nameFull, можно однозначно сопоставить полное имя получателя и добавить его в value.

В нашем документе есть поля для заполнения: nameFull, idNumber, idIssuedBy, idType и addressFull.

Зададим значение для этих полей и отправим документ:

nameFull: “Иван Петров”
idNumber: “1234 567890”
idIssuedBy: “УВД”
idType: “паспорт”
addressFull: “Московский проспект, 12, кв. 221”

Чтобы создать документ, выполним такой запрос:

$ curl -X POST -H 'X-DocuSign-Authentication:
              { "Username": "developer@example.com",
                "Password": "example",
                "IntegratorKey":"00000000-aaaa-bbbb-cccc-0123456789b" }'           -d '{
                "status": "sent",
                "emailSubject": "Example",
                "templateId": "00000000-aaaa-bbbb-cccc-0123456789c",
                "templateRoles": {
                  "signers": [{
                    "name": "Иван Петров",
                    "email": "ivan@email.com",
                    "recipientId": "1",
                    "routingOrder": "1",
                    "tabs": {
                      "textTabs": [
                        {
                          "xPosition": "150",
                          "yPosition": "200",
                          "name": "Full Name",
                          "tabLabel": "nameFull",
                          "value": "Иван Петров"
                        },
                        ...
                      ],
                    }
                  }]
                }
              }'              'https://demo.docusign.net/restapi/v2/accounts/9999999/envelopes/'

В ответе будет содержаться идентификатор созданного документа (envelopeId), дата последнего изменения статуса (statusDateTime) и сам статус (status):

{
  "envelopeId": "00000000-aaaa-bbbb-cccc-0123456789d",
  "uri": "/envelopes/00000000-aaaa-bbbb-cccc-0123456789d",
  "statusDateTime": "2016-09-27T19:52:09.7670000Z",
  "status": "created"
}

Документ заполнен и отправлен, и получателю не нужно заботиться о том, чтобы вписывать свои данные самостоятельно. Вот так выглядит форма заполнения документа:

Сертификация

Сертификация необходима для того, чтобы вы могли использовать интеграцию с DocuSign в рабочей среде. Для того, чтобы процесс сертификации прошёл без сучка без задоринки, необходимо, чтобы ваш клиент удовлетворял следующим требованиям:

1. не использовать недокументированные особенности API;
2. не использовать фичи, к которым у вас нет доступа в силу ограничений подписки;
3. не выходить за пределы выделенной квоты.

Что сделать, чтобы пройти сертификацию?

1. Заполнить и отправить форму запроса на сертификацию в Developer Center, в которой вы укажете:

• Integrator Key
• Account ID
• интервал времени, за которое нужно будет выполнить не менее 20 запросов к DocuSign. Запросы будут отражать то, как вы планируете использовать API

2. Использовать ваше приложение в выбранный временной интервал, сделать не менее 20 транзакций с DocuSign.

3. Если всё в порядке, то вы получите Post Certification Guide для подготовки к релизу. Обычно на этот процесс уходит не более недели, но я не рекомендую делать это перед самым релизом — без сертификации документы не будут иметь юридической силы, а вы не будете иметь доступа к поддержке DocuSign.

Заключение

В этом примере мы максимально поверхностно рассмотрели особенности интеграции с DocuSign, а также создали клиент для автозаполнения шаблонов и отправки документов на подпись. Я надеюсь, что этих знаний вам будет достаточно для того, чтобы понять, использовать ли сервис и продумать более сложную интеграцию или нет.