API за проверка на клиенти

С REST API на NePrati.com онлайн магазин или друга система може да провери телефона или имейла на клиента при нова поръчка с наложен платеж и да подаде сигнал, когато пратка не е потърсена. Ключът за достъп е безплатен.

За какво служи

API е подходящо за магазини и системи, които не работят с WooCommerce: собствена платформа, система за обработка на поръчки или вътрешен инструмент. Най-честите случаи са два:

  • проверка на клиента в момента на поръчката, преди да потвърдите изпращането;
  • подаване на сигнал, когато пратка с наложен платеж не е потърсена или е отказана.

Ако магазинът ви е на WooCommerce, не е нужно да програмирате — безплатният плъгин NePrati Check прави проверката автоматично.

Как да получите ключ

  1. Регистрирайте се безплатно или влезте в профила си. Формата за ключ е достъпна само за влезли потребители.
  2. Отворете формата за API ключ на страницата на плъгина.
  3. Въведете името и адреса на сайта си и имейл за контакт. Новият ключ се показва веднага. Ако вече сте създали ключ за сайта си, използвайте него. Ако за сайта ви вече има ключ, до който нямате достъп, пишете ни през страницата „Контакти“.

Пазете ключа като парола. Изпращайте заявките само от сървъра си и не поставяйте ключа в 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 — същият като в проверката на сайта.

Полета в отговора
ПолеОписание
foundtrue, ако има активни сигнали, и 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Кога се връща
400missing_paramsЛипсват и phone, и email.
400short_descriptionПри /report: описанието е по-кратко от 10 знака.
401missing_key, invalid_keyКлючът липсва, невалиден е или е деактивиран.
409duplicateПри /report: за същия телефон вече има сигнал през последните 24 часа.
429rate_limitНадвишен е лимитът на заявките. Изчакайте до един час и опитайте отново.
500db_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). Той проверява телефона и имейла при всяка нова поръчка, отбелязва поръчките със сигнали, може да ги задържа автоматично и позволява да подадете сигнал направо от екрана на поръчката. Ключът се създава от същата форма.