Получение уведомлений
Для получения уведомлений от сервисов «Наложка» необходимо реализовать доступный из интернета веб-хук, адрес которого нужно указать при запросе доступа к API.
Все запросы к веб-хуку отправляются методом POST и в теле содержат данные события в формате JSON. Набор полей события отличается в зависимости от типа события, но есть поля, которые присутствуют в данных любого события. К ним относятся:
- id — уникальный строковой идентификатор события;
- type — мнемонический строковой тип события;
- occurred_at — момент возникновения события.
Для проверки подлинности полученного события в строке запроса вам придет параметр signature, значением которого является цифровая подпись события, кодированная в Base64, рассчитанная от всего тела запроса по алгоритму RSA с дайджестом SHA-256. Публичный ключ в PEM формате для проверки такой подписи вы можете взять по ссылке nalogka-rsa-public.pem для событий боевого сервера и nalogka-sandbox-rsa-public.pem для событий тестового сервера (при запросе этих ссылок ssl-сертификат должен быть действителен). Разные ключи для боевого и тестового сервера позволяют исключить ошибку обработки тестового события боевым сервером, если некорректно настроен вебхук.
Чтобы проверить подпись, воспользуйтесь готовыми библиотеками для работы с OpenSSL для вашего языка программирования. Если подпись не совпадает, опишите проблему в email-письме и отправьте его на адрес integration@nalogka.com, приложив полученное сообщение (желательно с HTTP-заголовками).
Отладить проверку подписи боевого сервера можно, взяв в качестве сообщения
строку Проверка RSA-подписи Наложки и к ней подпись (base64) —
fvKGw3YBaG5S9pfj3qVmr81VVovCQPPEvTua6LcMnNswMlFxcyIyj8il59VS5YuIBXUoc1LiXLvw
f3BctBJrUHTgrTYpsgPBO6t2F5/vp8jSnIc06PSLy/sDQzunkn9v8vwJi6f1yvF6Y/NIGxTopDss
qfmnvIMnfLmqHXrwu6ToTMZZCrwx/p1kZAnUdd3LyPNc56aERL0vsYWbMKV7raWQhDUUD8BV+cKf
aawHLogBsI1BtYxkKV2kPVyIwzvUHL9XtkhGJLzHAHlxWc84rvTLeZ7cEsbZr3AG+teyq7nlXPRf
ruVJoOIg3z+a4IDOcYsWJI3b6+67pSQIYakBZFSTwH3HRiLS1Sw8dGGGDNtUckjkGbc1X8g+ovZB
SF8SUxEkdZGWOf9dAeJyePFLutZu7FvGvdXduNHYOq57TXYYsMVIQ9bFodaVse7bXx6O0gKLdEY/
OqK1dJa3J74LqgkEeh85mBv9hDQxvLk0LtYFh2JOMYEJ63d563LjcRls6WhxiDHe+EnkQ0ywNHxP
zLVm4CSyjdw7m1pawxffk2cgIyTgiH6tbVFA/iDz/9rPOb0z3oscxn+4wLYVb0Bgy8TXdEGaeBqv
1c03Rak/ZnOGM6W2Nlv6ghxa0KdNVWAw8MexpAQoyR2etmIn5NbSB+Qzgpoq/KEAQGPIspvkabI=
Примеры
Предположим, что вами указан вебхук
https://your-server.example.com/nalogka-event.
При возникновении события, система отправляет HTTP-запрос вида:
POST /nalogka-event?signature=FWzrfYzsrGgNujIPZNQ%2BOuNwcjRDN7U0AkOJK9bHDCxmP6Mz3WQve3hw7AUGCMFQ8AzUmivuU4AmmczYaRUf%2Bu2PmwQr4CDfbwkxSYKYVo6NLoR0kUoWOJhoZkfdbOXf25W7wlBLd7OHPd61kunFMzXrcxMkF4PM%2Fk1f6p1FT5I6ifJm5OA51GCGUuU4Scm0xqC%2FDC%2BAR6VDdAwkaL4HL7VWBU8Z2Y%2F7TI7yp8fKRh0IQJKXa62TNveB4PgXbjNXS7zSWrUAbECw8n59iGXrGsfAM2KNfnMrfmvOVhVr5%2BgpnkmQL4rLTCorQQhCG9CIItiDmyS1fflhR%2Ba1tu0lJo42LqMP4rM6BfuOR%2FCMpjA%2Bpi5mPTiU%2BQks%2Fsvz8XxMJgsZ%2FcjRSiO4QF%2BLbkHGGBXgEcPRcujPV%2BHAb%2BaFasC32muRqxyKjX37W4SIryPXwxAmojzq6GNcXi4HdBmFLrUevnq1vFXwqPzLBshaLalaDWYgX3xpb2%2BId6L0q%2F1OhGivuhdbUaMtWZk4zYE8pkaZQksPK2FPk9d%2FmU8yeGfbD65pqQYywrU2%2FSCOKf2u8XGZboWJHzAzBHWZxm%2BtwAWET1Gbxz0UGJTo6tpxm33MnL95wDcGzYDTfMyYKtJO6kO8YCj1q0JMQCUAt77DaqEsLS8d7Cm4RBayjzPa2GI%3D%0A
Host: your-server.example.com
Content-Type: application/json; charset=utf-8
Connection: close
{
"id": "bd98529d9e12f92844749cbac51f0661",
"type": "deals.deal.changed_status",
"occurred_at": "2018-10-23T10:37:22+03:00"
"old_status": "draft",
"new_status": "confirmed",
"deal: {
"~type": "Deal",
"~id": "1106",
"created_at": "2018-08-28T09:15:16+00:00",
"updated_at": "2018-08-28T09:15:16+00:00",
"marketplace_id": "nalogka",
"status": "draft",
"status_updated_at": "2018-08-28T09:15:16+00:00",
"conditions": "Хрупкий, крупногабаритный груз",
"buyer_profile_id": "41",
"seller_profile_id": "17",
"confirmed_by": "both",
"deposit": null,
"calculation_result": {
"~type": "CalculationResult",
"subject_items_sum": 6700.45,
"seller_provided_sum": 200,
"seller_consumed_sum": 200,
"buyer_consumed_sum": 200,
"commission_sum": 276.02,
"commission_seller_sum": 138.01,
"commission_buyer_sum": 138.01,
"buyer_expenses": 7338.46,
"seller_expenses": 338.01,
"buyer_have_to_pay_online": 538.01,
"buyer_have_to_pay_offline": 100,
"seller_have_to_pay_online": 0,
"payout": 6562.44,
"seller_profit": 6362.44,
"commission_payer": "50/50"
},
"token": "z8cvo9ushk1tnwe",
"attachments": [
{
"~type": "Attachment",
"id": "MF0mpOSy/cat.jpg",
"description": "",
"public_url": "http://filestorage/file/MF0mpOSy/cat.jpg",
"mime_type": "image/jpeg",
"size": "485377"
}
],
"commission_payer": "50/50",
"buyer_have_to_pay_offline": "270",
"subject_items": [
{
"~type": "SubjectItem",
"sku": "AB0000001",
"name": "Смартфон Apple iPhone 5s 16Gb Серебристый",
"description": "Есть царапина на корпусе",
"price": "23500",
"quantity": "1"
}
],
"additional_services": [
{
"~type": "AdditionalService",
"type": "delivery",
"name": "Доставка СДЭК",
"description": "Тариф Посылка Склад-Склад",
"original_cost": 450,
"final_cost": 400,
"payer": "seller",
"provided_by": "seller"
}
],
"dispute": null
}
}
Пример проверки подписи события на PHP
// получаем подпись из параметра запроса
$signature = base64_decode($_GET['signature']);
// получаем тело запроса
$body = file_get_contents('php://input');
// читаем ключ из nalogka-rsa-public.pem, ранее полученный из https://api.nalozhka.ru/nalogka-rsa-public.pem
$publicKey = openssl_get_publickey('file://path/to/nalogka-rsa-public.pem');
$result = openssl_verify($body, $signature, $publicKey, OPENSSL_ALGO_SHA256));
if (1 === $result) {
// подпись верна
} elseif (0 === $result) {
// подпись не соответствует данным
} else {
// ошибка при проверке подписи
}