API перевірки покупців BlackPost: документація та приклади інтеграції

BlackPost API — це RESTful інтерфейс для перевірки покупців за номером телефону. Він дозволяє інтегрувати перевірку в будь-яку систему: CRM, інтернет-магазин, мобільний додаток або автоматизований скрипт. API повертає ризик-скор (0-100), кількість скарг, категорії порушень та рекомендації.

У цій статті — повна документація: всі ендпоінти, параметри, формати відповідей, коди помилок. Плюс готові приклади інтеграції на трьох мовах: PHP, Python та JavaScript.

REST

JSON API

100ms

середній час відповіді

99.9%

uptime

355K+

записів у базі

Огляд API

BlackPost API побудований за принципами REST:

Base URL: https://blackpost.com.ua/api/v1
Формат: JSON (request і response)
Автентифікація: API-ключ у заголовку X-API-Key
HTTPS: обов'язковий (HTTP-запити відхиляються)
Кодування: UTF-8

Доступні ендпоінти

Метод	Ендпоінт	Опис	Тариф
`GET`	`/check`	Перевірка одного покупця за телефоном	Всі
`POST`	`/check/bulk`	Масова перевірка (до 50 номерів)	Pro
`POST`	`/report`	Подача скарги на покупця	Всі
`GET`	`/report/{id}`	Статус скарги	Всі
`POST`	`/webhook/register`	Реєстрація webhook	Pro
`DELETE`	`/webhook`	Видалення webhook	Pro
`GET`	`/account`	Інформація про акаунт та ліміти	Всі

Автентифікація

API використовує ключ-автентифікацію. Ключ передається в HTTP-заголовку X-API-Key з кожним запитом.

HTTP GET /api/v1/check?phone=380971234567 HTTP/1.1 Host: blackpost.com.ua X-API-Key: bg_your_api_key_here Accept: application/json

Отримання API-ключа

Зареєструйтесь на blackpost.com.ua/register
Підтвердіть email
Перейдіть до Налаштування → API ключі → Створити ключ
Скопіюйте ключ (формат: bg_..., 32+ символів)

⚠️ Безпека Ніколи не розміщуйте API-ключ у клієнтському коді (JavaScript фронтенду). Використовуйте лише server-to-server запити. Зберігайте ключ у змінних середовища (.env) або конфігураційних файлах, що не потрапляють до git.

Перевірка покупця

GET /api/v1/check Перевірити одного покупця

Параметри запиту (query string)

phone string required Номер телефону (будь-який формат: +380..., 380..., 0...)
name string optional Ім'я покупця (для перехресної верифікації)

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

cURL curl -X GET "https://blackpost.com.ua/api/v1/check?phone=380971234567&name=Іван" \ -H "X-API-Key: bg_your_api_key" \ -H "Accept: application/json"

Відповідь: покупець знайдений у базі

JSON — 200 OK { "success": true, "found": true, "buyer": { "phone": "380971234567", "risk_score": 67, "risk_level": "high", "risk_level_ua": "Високий ризик", "total_reports": 4, "unique_sellers": 3, "last_report_date": "2026-03-10", "categories": { "non_pickup": 3, "fraud": 1 }, "name_match": true }, "recommendation": "prepayment_required", "recommendation_ua": "Потрібна передоплата!" }

Відповідь: покупець НЕ знайдений

JSON — 200 OK { "success": true, "found": false, "buyer": null, "recommendation": "safe", "recommendation_ua": "Безпечно відправляти" }

Поля відповіді

Поле	Тип	Опис
`success`	boolean	Чи успішний запит
`found`	boolean	Чи знайдений телефон у базі
`buyer.risk_score`	integer	Скор ризику 0-100 (0=чистий, 100=критичний)
`buyer.risk_level`	string	`clean` \| `low` \| `medium` \| `high` \| `critical`
`buyer.risk_level_ua`	string	Рівень ризику українською
`buyer.total_reports`	integer	Загальна кількість скарг
`buyer.unique_sellers`	integer	Кількість різних продавців, що скаржились
`buyer.last_report_date`	string	Дата останньої скарги (YYYY-MM-DD)
`buyer.categories`	object	Кількість скарг за категоріями
`buyer.name_match`	boolean\|null	Чи збігається ім'я (якщо передано параметр `name`)
`recommendation`	string	`safe` \| `caution` \| `prepayment_advised` \| `prepayment_required` \| `do_not_ship`

Масова перевірка

POST /api/v1/check/bulk Перевірити до 50 номерів за раз

Тіло запиту (JSON)

phones array required Масив номерів телефонів (max 50)

cURL curl -X POST "https://blackpost.com.ua/api/v1/check/bulk" \ -H "X-API-Key: bg_your_api_key" \ -H "Content-Type: application/json" \ -d '{"phones": ["380971234567", "380501112233", "380631234567"]}'

Відповідь

JSON — 200 OK { "success": true, "total": 3, "found": 1, "results": [ { "phone": "380971234567", "found": true, "risk_score": 67, "risk_level": "high", "total_reports": 4 }, { "phone": "380501112233", "found": false, "risk_score": 0, "risk_level": "clean", "total_reports": 0 }, // ... ] }

Подача скарги

POST /api/v1/report Подати скаргу на покупця

Тіло запиту (JSON)

phonestringrequiredТелефон покупця
categorystringrequirednon_pickup | fraud | return_abuse | address_change | other
ttnstringoptionalНомер ТТН Нової Пошти (автоверифікація)
commentstringoptionalДодатковий коментар (до 500 символів)
order_amountnumberoptionalСума замовлення (грн)
buyer_namestringoptionalПІБ покупця

JSON — 201 Created { "success": true, "report_id": "rpt_abc123def456", "status": "pending", "message": "Скаргу прийнято. TTN буде перевірено автоматично." }

Статуси скарги: pending → verifying (перевірка TTN) → confirmed (підтверджено) або rejected (відхилено). Перевірка TTN відбувається автоматично через API Нової Пошти.

Webhook-сповіщення

Webhook дозволяє отримувати push-сповіщення про нові скарги на телефони, які ви раніше перевіряли. Це корисно для моніторингу повторних покупців — навіть якщо на момент першого замовлення покупець був «чистим», він може отримати скарги пізніше.

Реєстрація webhook

POST /api/v1/webhook/register Зареєструвати URL для сповіщень

urlstringrequiredHTTPS URL вашого сервера для прийому webhook
secretstringoptionalСекретний ключ для HMAC-підпису (рекомендовано)
eventsarrayoptionalТипи подій: ["new_report", "score_change"]. За замовчуванням — всі

Формат webhook-запиту

BlackPost надсилає POST-запит на ваш URL:

JSON — POST to your URL { "event": "new_report", "timestamp": "2026-03-15T14:30:00Z", "data": { "phone": "380971234567", "new_risk_score": 67, "previous_risk_score": 42, "new_reports_count": 1, "total_reports": 4, "category": "non_pickup" } }

Заголовок X-Webhook-Signature містить HMAC-SHA256 підпис тіла запиту з вашим secret. Перевіряйте його для захисту від підроблених запитів.

ℹ️ Ретрай-логіка Якщо ваш сервер не відповідає 200 OK протягом 10 секунд, BlackPost повторює запит 3 рази з інтервалом 30 сек, 5 хв, 30 хв. Після 3 невдалих спроб — сповіщення зберігається в лозі (доступний через API).

Приклад інтеграції: PHP

Готовий клас для інтеграції BlackPost у PHP-проект (OpenCart, WordPress, Laravel, чистий PHP):

PHP class BlackPostClient { private $apiKey; private $baseUrl = 'https://blackpost.com.ua/api/v1'; private $timeout = 8; public function __construct($apiKey) { $this->apiKey = $apiKey; } // Перевірка одного покупця public function check($phone, $name = null) { $params = ['phone' => $phone]; if ($name) $params['name'] = $name; return $this->request('GET', '/check?' . http_build_query($params)); } // Подача скарги public function report($phone, $category, $ttn = null, $comment = '') { return $this->request('POST', '/report', [ 'phone' => $phone, 'category' => $category, 'ttn' => $ttn, 'comment' => $comment, ]); } // Чи ризиковий покупець? public function isRisky($phone, $threshold = 50) { $result = $this->check($phone); if (!$result || !$result['found']) return false; return $result['buyer']['risk_score'] >= $threshold; } private function request($method, $endpoint, $data = null) { $ch = curl_init(); curl_setopt_array($ch, [ CURLOPT_URL => $this->baseUrl . $endpoint, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => $this->timeout, CURLOPT_HTTPHEADER => [ 'X-API-Key: ' . $this->apiKey, 'Accept: application/json', 'Content-Type: application/json', ], ]); if ($method === 'POST') { curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data)); } $response = curl_exec($ch); $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($httpCode >= 400) return null; return json_decode($response, true); } } // Використання: $bp = new BlackPostClient('bg_your_api_key'); $result = $bp->check('0971234567', 'Іван Петренко'); if ($result['found'] && $result['buyer']['risk_score'] >= 50) { // Ризиковий покупець — переводимо на передоплату echo "⚠️ Ризик: " . $result['buyer']['risk_level_ua']; }

Приклад інтеграції: Python

Python import requests from typing import Optional, Dict class BlackPostClient: def __init__(self, api_key: str): self.api_key = api_key self.base_url = "https://blackpost.com.ua/api/v1" self.session = requests.Session() self.session.headers.update({ "X-API-Key": api_key, "Accept": "application/json", }) self.session.timeout = 8 def check(self, phone: str, name: Optional[str] = None) -> Dict: """Перевірити покупця за телефоном.""" params = {"phone": phone} if name: params["name"] = name try: resp = self.session.get(f"{self.base_url}/check", params=params) resp.raise_for_status() return resp.json() except requests.RequestException as e: return {"success": False, "error": str(e)} def is_risky(self, phone: str, threshold: int = 50) -> bool: """Швидка перевірка: чи ризиковий покупець.""" result = self.check(phone) if not result.get("found"): return False return result["buyer"]["risk_score"] >= threshold def report(self, phone: str, category: str, ttn: str = "", comment: str = "") -> Dict: """Подати скаргу на покупця.""" try: resp = self.session.post(f"{self.base_url}/report", json={ "phone": phone, "category": category, "ttn": ttn, "comment": comment, }) resp.raise_for_status() return resp.json() except requests.RequestException as e: return {"success": False, "error": str(e)} def bulk_check(self, phones: list) -> Dict: """Масова перевірка (до 50 номерів).""" try: resp = self.session.post(f"{self.base_url}/check/bulk", json={ "phones": phones[:50] }) resp.raise_for_status() return resp.json() except requests.RequestException as e: return {"success": False, "error": str(e)} # Використання: bp = BlackPostClient("bg_your_api_key") # Перевірка result = bp.check("0971234567", name="Іван") if result["found"]: print(f"Ризик: {result['buyer']['risk_score']}/100") # Швидка перевірка if bp.is_risky("0971234567"): print("⚠️ Потрібна передоплата!") # Скарга bp.report("0971234567", "non_pickup", ttn="20450000012345")

Приклад інтеграції: JavaScript (Node.js)

JavaScript class BlackPostClient { constructor(apiKey) { this.apiKey = apiKey; this.baseUrl = 'https://blackpost.com.ua/api/v1'; } async check(phone, name = null) { const params = new URLSearchParams({ phone }); if (name) params.append('name', name); try { const resp = await fetch( `${this.baseUrl}/check?${params}`, { headers: { 'X-API-Key': this.apiKey, 'Accept': 'application/json', }, signal: AbortSignal.timeout(8000), } ); return await resp.json(); } catch (err) { return { success: false, error: err.message }; } } async isRisky(phone, threshold = 50) { const result = await this.check(phone); if (!result?.found) return false; return result.buyer.risk_score >= threshold; } async report(phone, category, ttn = '', comment = '') { try { const resp = await fetch(`${this.baseUrl}/report`, { method: 'POST', headers: { 'X-API-Key': this.apiKey, 'Content-Type': 'application/json', }, body: JSON.stringify({ phone, category, ttn, comment }), }); return await resp.json(); } catch (err) { return { success: false, error: err.message }; } } } // Використання: const bp = new BlackPostClient('bg_your_api_key'); const result = await bp.check('0971234567'); if (result.found && result.buyer.risk_score >= 50) { console.log(`⚠️ Ризик: ${result.buyer.risk_level_ua}`); }

Коди помилок

HTTP код	Значення	Що робити
`200`	Успішний запит	Обробити відповідь
`201`	Скаргу створено	Зберегти `report_id`
`400`	Невалідні параметри	Перевірити формат телефону/параметрів
`401`	Невалідний API-ключ	Перевірити ключ, переконатись що починається з `bg_`
`403`	Доступ заборонено	Тариф не підтримує цей ендпоінт (напр. bulk на Free)
`404`	Ендпоінт не знайдено	Перевірити URL
`429`	Перевищено ліміт запитів	Зачекати або оновити тариф
`500`	Внутрішня помилка сервера	Повторити через 30 сек, якщо не допомагає — написати підтримці

Формат помилки

JSON — 4xx/5xx { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Перевищено денний ліміт запитів (50). Оновіть тариф.", "daily_limit": 50, "daily_used": 50 } }

Ліміти та тарифи

Тариф	Ціна	Перевірок/день	Bulk	Webhook	Підтримка
Free	0 грн	50	—	—	Email
Basic	299 грн/міс	500	—	—	Email + Telegram
Pro	599 грн/міс	Безлімітно	✓ (до 50/запит)	✓	Пріоритетна

Rate limit: 10 запитів/секунду для всіх тарифів (захист від DDoS). При перевищенні — 429 з заголовком Retry-After.

Best Practices для інтеграції

1. Non-blocking дизайн

Завжди обгортайте API-виклики в try/catch. Якщо BlackPost не відповідає — замовлення повинно проходити нормально. Перевірка покупця — це допоміжна функція, а не критичний шлях.

2. Кешування

Кешуйте результати перевірок на 12-24 години. Якщо один покупець зробив 3 замовлення за день — це 1 API-запит замість 3. Використовуйте телефон як ключ кешу.

3. Таймаут

Встановлюйте таймаут 5-8 секунд. Середній час відповіді API — 100-300 мс, але мережеві затримки можливі. 8 секунд — достатній запас.

4. Безпека ключа

Зберігайте API-ключ у .env файлі (не в коді)
Ніколи не виносьте ключ на фронтенд
Використовуйте окремі ключі для dev/staging/production
Ротуйте ключі щоквартально

5. Логування

Логуйте всі перевірки: телефон, результат, час відповіді. Це допоможе: а) відстежувати ефективність, б) розслідувати інциденти, в) оптимізувати кешування.

6. Graceful degradation

Якщо API повертає помилку або таймаутить — не блокуйте замовлення. Логуйте помилку, позначте замовлення «не перевірено», перевірте пізніше (через масову перевірку або вручну).

7. Webhook верифікація

Завжди перевіряйте HMAC-підпис webhook-запитів. Без цього зловмисник може надсилати фальшиві повідомлення на ваш URL.

PHP — Webhook verification $payload = file_get_contents('php://input'); $signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? ''; $expected = hash_hmac('sha256', $payload, $webhookSecret); if (!hash_equals($expected, $signature)) { http_response_code(403); exit('Invalid signature'); } $data = json_decode($payload, true); // Обробити webhook...

Готові інтегрувати BlackPost?

Зареєструйтесь, отримайте API-ключ та почніть перевіряти покупців через 5 хвилин. 355 000+ записів. Безкоштовний тариф для старту.

Отримати API-ключ Повна документація

Часті запитання

API BlackPost доступний на всіх тарифах: Free (50 запитів/день), Basic (500/день, 299 грн/міс), Pro (без обмежень, 599 грн/міс). Масова перевірка та webhook — тільки на Pro.

Офіційних SDK поки немає, але API настільки простий (один GET-ендпоінт для перевірки), що SDK не потрібен. В статті наведені готові приклади-обгортки для PHP, Python та JavaScript, які можна використовувати як міні-SDK.

Webhook дозволяє отримувати push-сповіщення про нові скарги на ваших покупців. Ви реєструєте URL свого сервера, і BlackPost надсилає POST-запит з даними щоразу, коли з'являється нова скарга на телефон з вашої бази. HMAC-підпис для верифікації.

API приймає будь-який формат українського номера: +380971234567, 380971234567, 0971234567, 971234567. Сервер автоматично нормалізує до формату 380XXXXXXXXX. Підтримуються лише українські номери.

Free: 50 запитів/день, Basic: 500/день, Pro: без обмежень. Також є rate limit 10 запитів/секунду для захисту від DDoS. При перевищенні ліміту API повертає 429 Too Many Requests.

Так. API BlackPost — це стандартний REST API з JSON-відповідями. Він інтегрується з будь-якою CRM, яка підтримує HTTP-запити: KeepinCRM, SalesDrive, KeyCRM, Bitrix24, 1С та інші. В статті є приклади для PHP, Python та JavaScript.

API перевірки покупців BlackPost: повна документація та приклади інтеграції

Огляд API

Доступні ендпоінти

Автентифікація

Отримання API-ключа

Перевірка покупця

Параметри запиту (query string)

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

Відповідь: покупець знайдений у базі

Відповідь: покупець НЕ знайдений

Поля відповіді

Масова перевірка

Тіло запиту (JSON)

Відповідь

Подача скарги

Тіло запиту (JSON)

Webhook-сповіщення

Реєстрація webhook

Формат webhook-запиту

Приклад інтеграції: PHP

Приклад інтеграції: Python

Приклад інтеграції: JavaScript (Node.js)

Коди помилок

Формат помилки

Ліміти та тарифи

Best Practices для інтеграції

1. Non-blocking дизайн

2. Кешування

3. Таймаут

4. Безпека ключа

5. Логування

6. Graceful degradation

7. Webhook верифікація

Готові інтегрувати BlackPost?

Часті запитання