Интеграции и API

DigiSign във вашите системи

Изпращайте документи за подпис от вашата система, следете статуса и получавайте подписаните файлове обратно, без ръчна намеса. REST API с JSON и ключ за достъп.

Поискайте ключ за достъп Изтеглете описанието (Swagger)

Версия: 1.9.0
Адрес: https://{instance}.digisign.space/api/external/v1
Достъп: apiKey: …
Формат: REST · JSON

За какво го ползват клиентите

Автоматично подписване
Документът се генерира във вашата система и тръгва за подпис без ръчна намеса.
create
Статус в реално време
Вашата система получава известие при всяка промяна на статуса (callbackUrl) или го проверява сама.
status
Обратно в архива
Подписаният документ се изтегля и записва в архива или в досието на служителя.
downloadSigned
UniCredit Bulbank
В УниКредит Булбанк процесът е напълно автоматизиран: от генерирането на документите, през изпращането за подпис, до запазването им в архивна система.
Историята

Първи стъпки

Ключ за достъп
Ключът (apiKey) се предоставя от администратора на DigiSign за вашето приложение.
Адрес
Всеки клиент има собствено приложение: заменете {instance} с името на вашето.
Заглавка
Всяка заявка носи ключа в заглавката apiKey.

bash

curl "https://{instance}.digisign.space/api/external/v1/settings/channels" \
  -H "apiKey: YOUR_API_KEY"

Справочник

Настройки

Видовете документи и каналите за подписване, настроени във вашето приложение.

Видове документи

GET/settings/typesOfDocuments

Връща видовете документи, настроени в DigiSign.

Без параметри.

bash

curl "https://{instance}.digisign.space/api/external/v1/settings/typesOfDocuments" \
  -H "apiKey: YOUR_API_KEY"

Отговор 200

{
  "documentTypes": [
    {
      "id": 0,
      "shortName": "string",
      "name": "string",
      "description": "string",
      "active": true
    }
  ]
}

200401

Канали за подписване

GET/settings/channels

Връща каналите за подписване, дали са разрешени и дали има налични подписи в пакетите, таблетите (Signatus) и лицата с автоматично подписване (B-Trust).

Без параметри.

bash

curl "https://{instance}.digisign.space/api/external/v1/settings/channels" \
  -H "apiKey: YOUR_API_KEY"

Отговор 200

{
  "channels": [
    {
      "id": "BTRUST",
      "name": "string",
      "priority": 0,
      "enabled": true,
      "hasAvailableSignings": true,
      "oneTimeSigning": true,
      "signatusDevices": [
        {
          "deviceId": "string",
          "location": "string",
          "name": "string",
          "enabled": true
        }
      ],
      "autoSigners": [
        {
          "identifier": "string",
          "names": "string"
        }
      ]
    }
  ]
}

200401

Справочник

Заявки за подпис

Създаване, промяна, статус, изтегляне и отказ на заявки за подпис, кодове за 1-Click-Sign.

Нова заявка за подпис

POST/signRequests/create

Създава заявка с един или повече документи (PDF или XML, base64) и подписващите в реда, в който трябва да подпишат. Може да зададе срок, напомняне, папка, етикети, имейл за подписания файл и адрес за известия при промяна на статуса.

Тяло на заявката

Поле	Тип	Описание
`type`задължително	integer	Type ID of document in sign request
`description`задължително	string	Description of the document
`employeeNumber`	string	Employee ID of registered DigiSign user. Used only if the sign request must be associated with specific user (and to be visible in their respective "My Documents" view)
`documents`задължително	DocumentData[]
`participants`	SigningParticipantData[]	List of participants in the signing process. The order of the elements of the list is strictly observed in the signing process.
`expiry`	string	Deadline to sign document(s). Format yyyy-MM-dd HH:mm:ss
`expirationNotification`	integer	Number of hours before expiry to send reminder. Reminders templates are configured in the Settings of the DigiSign Document Portal.
`autoprocess`	boolean	True if the signing process must be initiated automatically by the timer (within 5 min). False if the process will be started manually from the DigiSign Document Portal UI.
`processNow`	boolean	True if the signing process must be initiated immediately.
`sendSignedFileTo`	string	E-mail address where to send the document after the process is completed and all participant have applied their respective digital signatures. Comma separated list of e-mail addresses. Supported delimiters ',' and ';'
`passwordForSendSignedFileTo`	string	Password to protect the ZIP archive with documents sent to the [sendSignedFileTo]. If value is null or empty documents will be sent without protection.
`folderName`	string	Full name of the folder to upload the document into or path to the folder. The path to the folder starts from '/' (main folder) and is separated by '/'. If the value is not specified or its '/' or folder is not found the document will be uploaded into the main folder. If only a single name is passed, the first found folder with this name will be used.
`tags`	[]	Array of tags to be added to the document (for search)
`callbackUrl`	string	Callback URL that will be called by the DigiSign portal when the status of the signing request changes. (Http method: GET)

request.json

{
  "type": 0,
  "description": "string",
  "employeeNumber": "string",
  "documents": [
    {
      "fileName": "string",
      "content": "string",
      "sha256sum": "string"
    }
  ],
  "participants": [
    {
      "names": "string",
      "email": "string",
      "phone": "string",
      "ipAddress": "string",
      "typeOfIdentifier": "EGN",
      "identifier": "string",
      "channel": "BTRUST",
      "signatureVendorAlias": "string",
      "billingMode": "RELYING_PARTY",
      "oneTimeSigning": true,
      "oneTimeRecipient": {
        "country": "string",
        "identificationNumber": "string",
        "documentNumber": "string",
        "firstName": "string",
        "middleName": "string",
        "lastName": "string",
        "phone": "string",
        "email": "string",
        "language": "bg",
        "codeConfirmation": "VENDOR",
        "personIdentifierType": "EGN",
        "personDocumentType": "ID_CARD",
        "firstNameCyrillic": "string",
        "middleNameCyrillic": "string",
        "lastNameCyrillic": "string",
        "birthCountryCode": "string",
        "birthDate": "string",
        "documentIssueDate": "string",
        "documentValidityDate": "string",
        "personAddress": {
          "address": "string",
          "city": "string",
          "countryCode": "string"
        },
        "oneTimeOTPLINK": "OTP"
      },
      "oneTimeAgent": {
        "country": "string",
        "identificationNumber": "string",
        "phone": "string"
      },
      "signAllDocumentsAtOnce": true,
      "signaturePositions": [
        {
          "fileName": "string",
          "pageNum": 0,
          "xAxis": 0,
          "yAxis": 0
        }
      ],
      "signingProperties": [
        {
          "fileName": "string",
          "optional": true,
          "preview": true,
          "visibleSignature": true
        }
      ],
      "deviceId": "string",
      "protectionMode": "none",
      "linkPassword": "string",
      "autoSignerId": "string",
      "coverage": 0,
      "annotations": [
        {
          "fileName": "string",
          "annotationText": "string",
          "pageNum": 0,
          "xAxis": 0,
          "yAxis": 0,
          "fontName": "string",
          "fontSize": 0,
          "fontColor": "string"
        }
      ],
      "visualSignVariant": "DIGISIGN",
      "autoprocess": true,
      "signedDeclaration": "string",
      "employee": {
        "email": "string",
        "employeeId": "string",
        "fullNameCyrillic": "string",
        "fullNameLatin": "string",
        "phone": "string",
        "position": "string"
      },
      "sendSignedFile": true,
      "passwordSendSignedFile": "string"
    }
  ],
  "expiry": "string",
  "expirationNotification": 0,
  "autoprocess": true,
  "processNow": true,
  "sendSignedFileTo": "string",
  "passwordForSendSignedFileTo": "string",
  "folderName": "string",
  "tags": [
    null
  ],
  "callbackUrl": "string"
}

bash

curl -X POST "https://{instance}.digisign.space/api/external/v1/signRequests/create" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Отговор 200

{
  "unid": "string",
  "status": "Waiting",
  "totalParticipants": 0,
  "signedParticipants": 0,
  "errorMessage": "string",
  "success": true
}

200401404

Промяна на заявка

PUT/signRequests/update

Променя заявка и стартира процеса на подписване.

Тяло на заявката

Поле	Тип	Описание
`unid`задължително	string	UNID of sign request
`participants`	SigningParticipantUpdateData[]	Signing participants with new signature positions
`expiry`	string	Deadline to sign document(s). Format yyyy-MM-dd HH:mm:ss
`processNow`	boolean	True if the signing process must be initiated immediately.

request.json

{
  "unid": "string",
  "participants": [
    {
      "identifier": "string",
      "signaturePositions": [
        {
          "fileName": "string",
          "pageNum": 0,
          "xAxis": 0,
          "yAxis": 0
        }
      ],
      "visualSignVariant": "DIGISIGN"
    }
  ],
  "expiry": "string",
  "processNow": true
}

bash

curl -X PUT "https://{instance}.digisign.space/api/external/v1/signRequests/update" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Отговор 200

{
  "unid": "string",
  "status": "Waiting",
  "totalParticipants": 0,
  "signedParticipants": 0,
  "errorMessage": "string",
  "success": true
}

200401404

Статус на заявка

GET/signRequests/status

Връща статуса на заявката и колко от участниците са подписали. По желание проверява статуса и при доставчика, преди да отговори.

Параметри

Поле	Тип	Описание
`unid`задължително	string	UNID of sign request
`forceCheck`	boolean	Force check the request status in DigiSign Gateway and update in portal (if needed) before returning the result. Force check will be executed only when 'forceCheck' is 'true' and status in portal is 'Processing'

bash

curl "https://{instance}.digisign.space/api/external/v1/signRequests/status?unid=REQUEST_UNID" \
  -H "apiKey: YOUR_API_KEY"

Отговор 200

{
  "unid": "string",
  "status": "Waiting",
  "totalParticipants": 0,
  "signedParticipants": 0,
  "errorMessage": "string",
  "success": true
}

200401404

Изтегляне на подписания документ

GET/signRequests/downloadSigned

Връща подписаните файлове. По желание ги изтрива от DigiSign след успешно изтегляне.

Параметри

Поле	Тип	Описание
`unid`задължително	string	UNID of sign request
`deleteDocument`	boolean	Delete document from DigiSign after successful download.

bash

curl "https://{instance}.digisign.space/api/external/v1/signRequests/downloadSigned?unid=REQUEST_UNID" \
  -H "apiKey: YOUR_API_KEY"

Отговор 200

{
  "unid": "string",
  "status": "Waiting",
  "errorMessage": "string",
  "success": true,
  "documents": [
    {
      "fileName": "string",
      "content": "string",
      "sha256sum": "string"
    }
  ]
}

200401404

Отказ на заявка

POST/signRequests/cancel

Оттегля заявка за подпис.

Тяло на заявката

Поле	Тип	Описание
`unid`задължително	string	UNID of the sign request
`reason`	string	Reason for the cancellation. Will be set in processing signing participant

request.json

{
  "unid": "string",
  "reason": "string"
}

bash

curl -X POST "https://{instance}.digisign.space/api/external/v1/signRequests/cancel" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Отговор 200

{
  "unid": "string",
  "status": "Waiting",
  "errorMessage": "string",
  "success": true
}

200400401404

Проверка на код (1-Click-Sign)

POST/signRequests/validateOtp

Проверява кода, който текущият подписващ е получил.

Тяло на заявката

Поле	Тип	Описание
`unid`задължително	string	UNID of the sign request
`otpCode`задължително	string	OTP code received from vendor
`phone`	string	Optional parameter. Phone number of the current signing party. If specified will be checked against current signing party phone number. Format "+[0-9]".

request.json

{
  "unid": "string",
  "otpCode": "string",
  "phone": "string"
}

bash

curl -X POST "https://{instance}.digisign.space/api/external/v1/signRequests/validateOtp" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Отговор 200

{
  "success": true,
  "remainingAttempts": 0,
  "details": "string"
}

200400401404

Нов код (1-Click-Sign)

POST/signRequests/resendOtp

Изпраща отново кода на текущия подписващ.

Тяло на заявката

Поле	Тип	Описание
`unid`задължително	string	UNID of the sign request
`phone`	string	Optional parameter. Phone number of the current signing party. If specified will be checked against current signing party phone number. Format "+[0-9]".

request.json

{
  "unid": "string",
  "phone": "string"
}

bash

curl -X POST "https://{instance}.digisign.space/api/external/v1/signRequests/resendOtp" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Отговор 200

{
  "success": true,
  "details": "string"
}

200400401404

Кодове на отговор

200: Успех
400: Невалидна заявка
401: Липсващ или невалиден ключ
403: Няма права
404: Не е намерено

Описанията на полетата са на английски, както в техническата спецификация.

Въпроси за интеграцията: пишете на support@digisign.space.

За какво го ползват клиентите

Автоматично подписване

Статус в реално време

Обратно в архива

UniCredit Bulbank

Първи стъпки

Ключ за достъп

Адрес

Заглавка

Настройки

Заявки за подпис

Тяло на заявката

Тяло на заявката

Параметри

Параметри

Тяло на заявката

Тяло на заявката

Тяло на заявката

Кодове на отговор