View Source

note

Зміст

note

Опис

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

note

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

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

note

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)
  )
)

note

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

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>

<?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);

<?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";
        }
    }
}

note

Callback

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

104.248.247.85
104.21.35.224
172.67.180.63

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

После успешной авторизации на success_url будет перенаправлен браузер клиента и методом 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

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

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`		ОКПО юридического лица

{
  "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	Шифрованная подпись запроса

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

{ 
  "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	Причина отказа

note

Перевірка

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