Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

Зміст

Опис

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

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

  • Інтугрувати 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</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

Причина отказа

Перевірка

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

  • No labels