Документи з Дія

Зміст

Опис

Продукт використовується для отримання даних про клієнта разом зі сканами документів через сервіс Дія.

Чекліст інтеграції

Інтугрувати API метод цього розділу.
Відобразити клієнту кнопку на сайті / додатку.
Відобразити клієнту QR код або авторедірект в Privat24 на підпис документів.
Отримати успішний Callback Bank ID з даними про клієнта.
Отримати успішний Callback P-Sign з підписаними документами.

API параметри

HTTP METHOD: POST

API ENDPOINT: https://sign.platon.ua/api

Параметр	Значення	Опис
`action` ОБОВ'ЯЗКОВИЙ	`GET_DOC_DIIA`	API метод
`client_key` ОБОВ'ЯЗКОВИЙ	String	API ключ мерчанта в системі PSP Platon саме для BankID + КЕП
`client_request_id` ОБОВ'ЯЗКОВИЙ	String	Унікальним ідентифікатор запиту мерчанту
`success_url` ОБОВ'ЯЗКОВИЙ	String	URL на сторінку успішної верифікації документів Дані відправляються методом GET. Приклад і опис вказано нижче.
`error_url` ОБОВ'ЯЗКОВИЙ	String	URL на сторінку невдалої верифікації документів
`doc_url` ОБОВ'ЯЗКОВИЙ	String	URL, куди буде відправлено Callback Bank ID з даними про клієнта Обов'язкова наявність SSL сертифіката.
`sign_doc_url` ОБОВ'ЯЗКОВИЙ	String	URL, куди буде відправлено Callback P-Sign з підписаними документами Обов'язкова наявність SSL сертифіката.
`mode` ОБОВ'ЯЗКОВИЙ	`test` `prod`	Переключення режиму тестового (`test`) та прод (`prod`) середовищ
`itn` НЕ ОБОВ'ЯЗКОВИЙ	String	Вказати ІНН клієнта якщо він наявний. Якщо ІНН немає - параметр не передавати.
`hash` ОБОВ'ЯЗКОВИЙ	String	Контрольний підпис md5( strtoupper( strrev($client_password). strrev($client_request_id) ) )

Приклад запиту

Приклад запиту на PHP

Content-Type: form-data или x-www-form-urlencoded

<?php
$client_key = '******';
$client_password = '******************';
$client_request_id = microtime(); // рандом
$mode = 'prod';
$success_url = 'https://*************'; 
$error_url = 'https://*************';
$bankid_callback_url = 'https://*************'; 
$callback_url = 'https://*************';
$hash = md5(
          strtoupper(
            strrev($client_password).
            strrev($client_request_id)
          )
        );
?>

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>Bank ID + P-Sogn</title>
  </head>
  <body>
    <form method="POST" action="https://sign.platon.ua/api">
      <input type="hidden" name="action" value="GET_DOC_DIIA">
      <input type="hidden" name="client_key" value="<?= $client_key ?>">
      <input type="hidden" name="client_request_id" value="<?= $client_request_id ?>">
      <input type="hidden" name="success_url" value="<?= $success_url ?>">
      <input type="hidden" name="error_url" value="<?= $error_url ?>">
      <input type="hidden" name="doc_url" value="<?= $bankid_callback_url ?>">
      <input type="hidden" name="sign_doc_url" value="<?= $callback_url ?>">
      <input type="hidden" name="mode" value="<?= $mode ?>">
      <input type="hidden" name="hash" value="<?= $hash ?>">
      <button type="submit">START BANK-ID SIGN</button>
    </form>
  </body>
</html>

Розшифровка callback Bank ID на PHP

<?php
declare(strict_types=1);

// ---------- ПЕРЕМЕННЫЕ
$client_key = 'PL-*****';
$api_password = '********************';

$client_request_id = 'PL-11917';

$privateKey = ''; // приватный ключ для расшифровки (можно не указывать)
$downloadFolder = './docs/';

$hash = md5(strtoupper(strrev($api_password).strrev($client_request_id)));

if (! array_key_exists('personal_data', $_POST) || ! array_key_exists('hash', $_POST)) {
    echo "не прислано данные!\n";
    return;
}

if  ($hash !== $_POST['hash']) {
    echo "подписи не совпадают!\n";
}

function isJson($string): bool
{
    json_decode($string);
    return json_last_error() === JSON_ERROR_NONE;
}

// расшифровка
$personalData = $_POST['personal_data'];
if (! isJson($_POST['personal_data'])) {
    openssl_private_decrypt(base64_decode($personalData), $decrypted, $privateKey);
    $personalData = $decrypted;
}
$personalData = json_decode($personalData, true);

// скачивание файлов
foreach ($personalData['scans'] as $scan) {
    $filename = $downloadFolder.$scan['type'].'.'.$scan['extension'];
    file_put_contents($filename, fopen($scan['link'], 'r'));
    echo "файл сохранен! $filename\n";
}

// персональные данные
var_dump($personalData);

Розшифровка callback P-sign на PHP

<?php
declare(strict_types=1);

$postRequiredFields = [
    'action',
    'status',
    'request_id',
    'client_request_id',
    'channel',
];

$signerFields = [
    'name',
    'second_name',
    'surname',
    'itn',
];



$result = [];

$allPostFields = array_merge($postRequiredFields, $signerFields);

foreach ($allPostFields as $fieldName) {
    if (array_key_exists($fieldName, $_POST)) {
        $result[$fieldName] = $_POST[$fieldName];
    }
}

$callbackDataAsString = json_encode($result);

// сохраняем данные последнего коллбека
$fileSaveResult = file_put_contents('last_callback_post_fields.txt', $callbackDataAsString);

  $are = var_export($_POST, true);
  //http_response_code(500);
  
  $log = __DIR__ . '/inArray.log';
  file_put_contents($log, $are. "\n\n", FILE_APPEND);

if ($fileSaveResult) {
    echo "файл с данными коллбека сохранен! \n";
} else {
    echo "нет доступа к файлу с данными коллбека - он не может быть записан :( \n";
}

// обрабатываем подписанные файлы (сохраняем)
$signedData = array_key_exists('signatures', $_POST) ? $_POST['signatures'] : null;
if (! $signedData) {
    return;
}

foreach ($signedData as $idx => $signedFileData) {
    if ($_FILES['signatures']['tmp_name'][$idx]['signed_file']) {
        // сохраняем в текущую папку (где находится этот обработчик)
        $signFileSaveResult = move_uploaded_file(
            $_FILES['signatures']['tmp_name'][$idx]['signed_file'],
            $_FILES['signatures']['name'][$idx]['signed_file']
        );

        if (! $signFileSaveResult) {
            $filename = $_FILES['signatures']['name'][$idx]['signed_file'];
            echo "подписанный файл $filename не может быть сохранен :( \n";
        }
    }
}

Callback

IP адреси сервера відправки:

104.248.247.85
104.21.35.224
172.67.180.63

Редирект клиента при успешной верификации документов:

После успешной авторизации на success_url будет перенаправлен браузер клиента и методом GET переданы параметры.

Пример GET параметров

https://YOUR_SUCCESS_PAGE/RA/callback/cachcallback.php? request_id=0.47912000%201625658249&
id=99c93434-82e4-4191-8f01- c8e6fe5623a0&
url=aHR0cHM6Ly93d3cucHJpdmF0MjQudWEvcmQva2VwP2hhc2g9cmQva2VwL3siY2xpZW50SWQiOiJQTEFUT05fOTljOTM0MzQtODJlNC00MTkxLThmMDEtYzhlNmZlNTYyM2EwIiwib3BlcmF0aW9uSWQiOiJSMXBhVm1GTVkyTjBhMFJrVjNaWlYySkhibXB6YzJkRmVuaHZWVnAyVTNseFMxRk9TVVpQVUZWWldVcDRaVmhXWVc1UmRHOTNaMWxzWVU1U2JYQktTMWxsIiwiYWN0aW9 uIjoic2lnbiJ9&
qr=aHR0cHM6Ly9zaWduLnBsYXRvbi51YS9hcGkvdjEvc21hcnQtaWQvOTljOTM0MzQtODJlNC00MTkxLThmMDEtYzhlNmZlNTYyM2EwL3FyP3Npe mU9MjUw

Параметр	Значение	Описание
`request_id`	String	Уникальный идентификатор запроса мерчанта
`id`	String	Уникальный идентификатор запроса Platon
`url`	String	URL для редиректа клиента для подписания документов в base64
`qr_code`	String	QR-код для редиректа клиента для подписания документов в base64

При успешном запросе:

Callback BankID при успешном запросе

array (
  'personal_data' => '{
    "inn":"3317817839",
    "sex":"M",
    "clId":"565d8f1fdd2856ae7aec55909c70c9fde10ce4b8",
    "type":"physical",
    "email":"********",
    "phone":"38096111111",
    "scans":[{
      "link":"https:\\/\\/sign.platon.ua\\/storage\\/scans\\/*****.pdf",
      "type":"idpassport",
      "number":2,
      "extension":"pdf",
      "dateCreate":"22.02.2018",
      "dateModification":"22.02.2018 12:22:53.514"
    },
    {
      "link":"https:\\/\\/sign.platon.ua\\/storage\\/scans\\/****.pdf",
      "type":"inn",
      "number":5,
      "extension":"pdf",
      "dateCreate":"22.02.2018",
      "dateModification":"22.02.2018 12:23:48.97"
    },
    {
      "link":"https:\\/\\/sign.platon.ua\\/storage\\/scans\\/*****.pdf",
      "type":"personalPhoto",
      "number":1,
      "extension":"pdf",
      "dateCreate":"30.03.2021",
      "dateModification":"30.03.2021 04:16:37.124"
    },
    {
      "link":"https:\\/\\/sign.platon.ua\\/storage\\/scans\\/*****.pdf",
      "type":"passport",
      "number":4,
      "extension":"pdf",
      "dateCreate":"17.05.2013",
      "dateModification":"24.03.2016 07:21:12.0"
    }],
    "edrpou":"3377818840",
    "birthDay":"05.11.1990",
    "clIdText":"\\u041f\\u0435\\u0440\\u0435\\u0434\\u0430\\u043d\\u0430 \\u0456\\u043d\\u0444\\u043e\\u0440\\u043c\\u0430\\u0446\\u0456\\u044f \\u0454 \\u0434\\u043e\\u0441\\u0442\\u043e\\u0432\\u0456\\u0440\\u043d\\u043e\\u044e \\u0456 \\u043f\\u0456\\u0434\\u0442\\u0432\\u0435\\u0440\\u0434\\u0436\\u0435\\u043d\\u0430 BankID 20.07.2021 16:10",
    "lastName":"\\u0411\\u0443\\u0440\\u043c\\u0430\\u043a\\u0430",
    "resident":"UA",
    "addresses":[{
      "city":"\\u0416\\u0418\\u0422\\u041e\\u041c\\u0418\\u0420",
      "type":"factual",
      "state":"\\u0416\\u0418\\u0422\\u041e\\u041c\\u0418\\u0420\\u0421\\u042c\\u041a\\u0410",
      "flatNo":"100",
      "street":"\\u041a\\u041d\\u042f\\u0417\\u0406\\u0412 \\u041e\\u0421\\u0422\\u0420\\u041e\\u0417\\u042c\\u041a\\u0418\\u0425",
      "country":"UA",
      "houseNo":"100",
      "dateModification":"23.12.2019 06:53:31.13"
    }],
    "documents":[{
      "type":"idpassport",
      "issue":"1810",
      "number":"001472599",
      "dateIssue":"01.02.2018",
      "dateExpiration":"01.02.2028",
      "dateModification":"19.04.2019 23:41:22.146",
      "issueCountryIso2":"UA"
    }],
    "firstName":"\\u041e\\u043b\\u0435\\u043a\\u0441\\u0430\\u043d\\u0434\\u0440",
    "signature":"f7c3478d6ef4a06461d99b404ba6d9841b594a1e",
    "middleName":"\\u0421\\u0435\\u0440\\u0433\\u0456\\u0439\\u043e\\u0432\\u0438\\u0447",
    "dateModification":"11.07.2019 12:32:56.883"
  }',
  'hash' => '7c11f8515909a2f2080f1dfd034bfbb0',
)

Параметры		Описание
`fields`	Область данных общей информации
	`firstName`	имя
	`middleName`	отчество
	`lastName`	фамилия
	`phone`	актуальный телефон
	`inn`	идентификационный номер налогоплательщика
	`clId`	идентификатор клиента (необязательное поле и может отсутствовать)
	`clIdText`	статических текст подтверждения выдачи информации
	`birthDay`	дата рождения
	`sex`	пол (M - мужской, F - женский)
	`email`	email
	`resident`	определение резидентности (стандарт ISO(2)) UA — резидент /UA — нерезидент
	`dateModification`	последняя дата модификации данных в объекте (dd.MM.yyyy HH:mm:ss.S)
`addresses`	Область данных адреса регистрации/рождения
	`type`	тип адреса juridical — адрес регистрации (штамп в паспорте) factual — адрес фактический (реально проживает) birth – адрес рождения
	`country`	страна
	`state`	область
	`area`	район
	`city`	город
	`subTown`	микрорайон/жилмассив и пр. в городе
	`street`	улица
	`houseNo`	номер дома
	`flatNo`	номер квартиры
`documents`	Область данных документа регистрации
	`type`	тип документа passport – гражданский паспорт zpassport – загранпаспорт ident – удостоверение личности (высылается любой документ регистрации) idpassport — пластиковый паспорт govregistration - свидетельство государственной регистрации
	`series`	серия (отсутствует в idpassport)
	`number`	номер
	`issue`	кем выдан
	`dateIssue`	когда выдан
	`dateExpiration`	срок действия (dd.MM.yyyy)
	`issueCountryIso2`	страна выдачи
`scans`	Сканы
	`type`	типы сканов passport — скан гражданского паспорта zpassport — скан загранпаспорта inn – скан идентификационного налогового номера personalPhoto – фотография личности (анфас)
	`file`	файл
	`dateCreate`	дата сканирования
	`extension`	тип расширения файла
`edrpou`		ОКПО юридического лица

Callback P-Sign при успешном запросе

{
  "action":"GET_SMART_ID",
  "status":"SUCCESS",
  "request_id":"1d7f09c9-d4ec-42ba-910c-44c92788c3b7",
  "client_request_id":"0.689538001615372279",
  "channel":"diia",
  "name":"\u041e\u043b\u0435\u043a\u0441\u0430\u043d\u0434\u0440",
  "second_name":"\u041b\u0435\u043e\u043d\u0456\u0434\u043e\u0432\u0438\u0447",
  "surname":"\u0420\u043e\u0434\u0438\u043d\u0430",
  "itn":"3475806070"
}

Параметр	Значение	Описание
`action`	`GET_SMART_ID`
`status`	`SUCCESS`
`request_id`	String	Уникальный идентификатор запроса на стороне Platon
`client_request_id`	String	Уникальный идентификатор запроса на стороне мерчанта
`channel`	String	Канал получения запроса
`signatures`	List	Список с результатами подписания
`$_FILES['signatures']`	File	Подписанные файлы
`name`	String	Имя подписана
`second_Name`	String	Отчество подписана
`surname`	String	Фамилия подписана
`itn`	String	ИНН код подписанта
`errorMessage`	String	Текст ошибки
`hash`	String	Шифрованная подпись запроса

При неуспешном запросе:

Response при неуспешном запросе

{ 
  "action":"GET_SMART_ID",
  "client_request_id":"0.58243700 1615373685",
  "result":"DECLINED",
  "error_message":"The callback url field is required."
}

Параметр	Значение	Описание
`action`	`GET_SMART_ID`
`result`	`DECLINED`	При отказе нашей системы или SmartID
`request_id`	String	Уникальный идентификатор запроса на стороне Platon
`client_request_id`	String	Уникальный идентификатор запроса на стороне мерчанта
`error_message`	String	Причина отказа

Перевірка

Для індивідуальної перевірки необхідно завантажити файли документів підписаних КЕП на офіційний ресурс Центрального засвідчувального органу.