API за проверка на клиенти
С REST API на NePrati.com онлайн магазин или друга система може да провери телефона или имейла на клиента при нова поръчка с наложен платеж и да подаде сигнал, когато пратка не е потърсена. Ключът за достъп е безплатен.
За какво служи
API е подходящо за магазини и системи, които не работят с WooCommerce: собствена платформа, система за обработка на поръчки или вътрешен инструмент. Най-честите случаи са два:
- проверка на клиента в момента на поръчката, преди да потвърдите изпращането;
- подаване на сигнал, когато пратка с наложен платеж не е потърсена или е отказана.
Ако магазинът ви е на WooCommerce, не е нужно да програмирате — безплатният плъгин NePrati Check прави проверката автоматично.
Как да получите ключ
- Регистрирайте се безплатно или влезте в профила си. Формата за ключ е достъпна само за влезли потребители.
- Отворете формата за API ключ на страницата на плъгина.
- Въведете името и адреса на сайта си и имейл за контакт. Новият ключ се показва веднага. Ако вече сте създали ключ за сайта си, използвайте него. Ако за сайта ви вече има ключ, до който нямате достъп, пишете ни през страницата „Контакти“.
Пазете ключа като парола. Изпращайте заявките само от сървъра си и не поставяйте ключа в JavaScript код, който се зарежда в браузъра на клиента, или в публични хранилища.
Удостоверяване
Ключът се изпраща в заглавката X-NePrati-Key на всяка заявка. API приема ключа и като параметър api_key, но заглавката е за предпочитане, защото адресите с параметри по-лесно попадат в дневници. Заявките се изпращат с метод POST и тяло във формат JSON (Content-Type: application/json).
Проверка на клиент
POST https://neprati.com/wp-json/neprati/v1/check
| Параметър | Описание |
|---|---|
phone | Телефонен номер на клиента. |
email | Имейл адрес на клиента. |
Задължителен е поне единият параметър. Ако изпратите и двата, резултатът обединява сигналите за телефона и за имейла. Номерът се сравнява точно, след като се премахнат интервалите и другите знаци (водещият „+“ се запазва). Затова номер с код на държавата и същият номер, започващ с 0, са различни стойности. Използвайте формат 08XXXXXXXX — същият като в проверката на сайта.
| Поле | Описание |
|---|---|
found | true, ако има активни сигнали, и false, ако няма. |
report_count | Брой активни сигнали. |
risk_score | Ниво на риск от 0 до 100 (как се изчислява). |
risk_label | „Без сигнали“, „Нисък риск“, „Среден риск“, „Висок риск“ или „Критичен риск“. |
first_report_date | Дата на първия сигнал във формат ДД.ММ.ГГГГ или null. |
last_report_date | Дата на последния сигнал във формат ДД.ММ.ГГГГ или null. |
Отговор, когато няма сигнали (found: false):
{
"found": false,
"report_count": 0,
"risk_score": 0,
"risk_label": "Без сигнали",
"first_report_date": null,
"last_report_date": null
} Примерен отговор, когато има сигнали:
{
"found": true,
"report_count": 2,
"risk_score": 60,
"risk_label": "Висок риск",
"first_report_date": "ДД.ММ.ГГГГ",
"last_report_date": "ДД.ММ.ГГГГ"
} Отговорът не съдържа описанията на сигналите, имената на подателите и доказателствата.
Подаване на сигнал
POST https://neprati.com/wp-json/neprati/v1/report
| Параметър | Задължителен | Описание |
|---|---|---|
phone | да, ако няма email | Телефонен номер на получателя. |
email | да, ако няма phone | Имейл адрес на получателя. |
description | да | Описание на случая, поне 10 знака. |
name | не | Име на получателя. |
city | не | Град. |
courier_company | не | Куриерска фирма. |
order_number | не | Номер на поръчката. |
site_name | не | Име на магазина. Ако липсва, се използва името, въведено при създаването на ключа. |
Сигналът се публикува веднага и без доказателства. Към описанието автоматично се добавят „Подаден от:“ с името на магазина и номерът на поръчката, ако е изпратен, така че те се виждат при проверка на номера. Ако за същия телефонен номер вече има сигнал от последните 24 часа, независимо от кого е подаден, заявката се отхвърля с код 409.
Успешен отговор:
{
"success": true,
"report_id": 12345,
"message": "Сигналът е подаден успешно."
} Подавайте сигнал само при реален случай и описвайте фактите — без обиди и без лични данни, които не са нужни. Сигналът се показва при проверка до 12 месеца от подаването.
Лимити и грешки
Лимитът е 1 500 заявки за един ключ, общо за проверки и сигнали. Броят се всички заявки с валиден ключ освен отхвърлените заради лимита (код 429), а броячът се нулира, след като мине един час без нито една преброена заявка. Затова при постоянен поток от заявки лимитът може да бъде достигнат и за повече от час.
При грешка API връща JSON с полета code, message и data.status, например:
{
"code": "rate_limit",
"message": "Надвишен лимит: … заявки/час.",
"data": { "status": 429 }
} | HTTP код | code | Кога се връща |
|---|---|---|
| 400 | missing_params | Липсват и phone, и email. |
| 400 | short_description | При /report: описанието е по-кратко от 10 знака. |
| 401 | missing_key, invalid_key | Ключът липсва, невалиден е или е деактивиран. |
| 409 | duplicate | При /report: за същия телефон вече има сигнал през последните 24 часа. |
| 429 | rate_limit | Надвишен е лимитът на заявките. Изчакайте до един час и опитайте отново. |
| 500 | db_error | Сигналът не можа да бъде записан. Опитайте отново по-късно. |
Има и публична заявка без ключ — GET https://neprati.com/wp-json/neprati/v1/plugin-info. Тя връща информация за последната версия на плъгина за WooCommerce и не съдържа данни за сигнали.
Примери
Проверка с cURL
curl -X POST "https://neprati.com/wp-json/neprati/v1/check" \
-H "Content-Type: application/json" \
-H "X-NePrati-Key: YOUR_API_KEY" \
-d '{"phone": "08XXXXXXXX"}' Подаване на сигнал с cURL
curl -X POST "https://neprati.com/wp-json/neprati/v1/report" \
-H "Content-Type: application/json" \
-H "X-NePrati-Key: YOUR_API_KEY" \
-d '{"phone": "08XXXXXXXX", "description": "Пратката не е потърсена в срока за съхранение.", "order_number": "1001"}' Проверка с PHP
$ch = curl_init('https://neprati.com/wp-json/neprati/v1/check');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-NePrati-Key: YOUR_API_KEY',
],
CURLOPT_POSTFIELDS => json_encode(['phone' => '08XXXXXXXX']),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$result = json_decode((string) $body, true);
if ($status === 200 && !empty($result['found'])) {
// Има сигнали: например потвърдете поръчката по телефона
// или предложете плащане с карта.
}
// При грешка или таймаут обработете поръчката по обичайния начин. Задайте кратко време за изчакване и не спирайте поръчката, ако API не отговори. Плъгинът за WooCommerce работи по същия начин — с изчакване до 10 секунди.
Добри практики и лични данни
- Проверявайте само при реална поръчка. Не проверявайте списъци с номера и не изпращайте масови заявки.
- Не показвайте резултата на трети лица. Използвайте го само за решението по конкретната поръчка.
- Пазете отговорите само толкова, колкото е нужно за обработката на поръчката.
- Опишете проверката в политиката за поверителност на магазина си: какви данни изпращате (телефон, имейл), с каква цел и на какво основание.
- Подавайте сигнал само при реален случай, с факти и без обидни изрази.
Заявките към /check се записват в технически дневник на платформата: ключ, телефон, имейл, резултат и IP адрес.
Готова интеграция за WooCommerce
Ако магазинът ви е на WooCommerce, използвайте плъгина NePrati Check (версия 1.3.1). Той проверява телефона и имейла при всяка нова поръчка, отбелязва поръчките със сигнали, може да ги задържа автоматично и позволява да подадете сигнал направо от екрана на поръчката. Ключът се създава от същата форма.