Page Comparison

Зміст

Table of Contents

maxLevel	2
indent	0px
absoluteUrl	true
style	circle

Опис

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

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

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

API параметри

HTTP METHOD: POST

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

Параметр

Значення

Опис

action

Status

colour	Green
title	Обов'язковий

GET_DOC_DIIA

API метод

client_key

Status

colour	Green
title	Обов'язковий

String

API ключ мерчанта в системі PSP Platon саме для BankID + КЕПдокументів Дія

client_request_id

Status

colour	Green
title	Обов'язковий

String

Унікальним ідентифікатор запиту мерчанту

success_url

Status

colour	Green
title	Обов'язковий

String

URL на сторінку успішної верифікації документів

Info
Дані відправляються методом GET. Приклад і опис вказано нижче.

error_url

Status

colour	Green
title	Обов'язковий

String

URL на сторінку невдалої верифікації документів

doc_url

Status

colour	Green
title	Обов'язковий

String

URL, куди буде відправлено Callback Bank ID з даними про клієнта

Info
Обов'язкова наявність SSL сертифіката.

sign_doc_url

Status

colour	Green
title	Обов'язковий

String

URL, куди буде відправлено Callback P-Sign з підписаними документами

Info
Обов'язкова наявність SSL сертифіката.

mode

Status

colour	Green
title	Обов'язковий

test
prod

Переключення режиму тестового (test) та прод (prod) середовищ

itn

Status

colour	Yellow
title	не Обов'язковий

String

Вказати ІНН клієнта якщо він наявний. Якщо ІНН немає - параметр не передавати.

hash

Status

colour	Green
title	Обов'язковий

String

Контрольний підпис

Code Block

language	php

md5(
  strtoupper(
    strrev($client_password).
    strrev($client_request_id)
  )
)

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

Expand

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

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

Code Block

language	php

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

$callback$doc_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>GET_DOC_DIIA</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$doc_url ?>">
      <input type="hidden" name="mode" value="<?= $mode ?>">
      <input type="hidden" name="hash" value="<?= $hash ?>">
      <button type="submit">START BANK-ID SIGN<GET_DOC_DIIA</button>
    </form>
  </body>
</html>

Expand

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

Code Block

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

Expand

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

Code Block

language	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 переданы параметры.

Expand

title	Пример 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

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

Expand

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

Code Block

language	php

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

Expand

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

Code Block

language	json

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

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

Expand

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

Code Block

language	json

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

Перевірка

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

Versions Compared

Old Version 1

New Version Current

Key

Зміст

Опис

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

API параметри

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

Callback

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

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

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

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

Перевірка