Избери тема:
Използвайте нашето API директно без значение от платформата, на която е магазинът ви.
Адресът на нашето API е https://api.buyercheck.bg
Всички заявки към API-то трябва да съдържат header x-buyercheck-key със стойността на API ключа. POST заявките трябва да съдържат и api_user поле в body-то със стойността на имейла на вашия потребител в buyercheck.bg
За да получите API ключ, посетете страницата с планове и закупете подходящ план, въвеждайки домейна на вашия сайт. След като заплатите поръчката, ще получите API ключ на посочения email.
Преди да започнете с всичко останало, вашият магазин трябва да има webhook адрес (не използвайте buyercheck в името), защитен с парола (secret), където BuyerCheck ще изпраща данни за поръчките - след като ги обработим.
2.1. Задължително трябва да създадете механизъм, който да валидира данните, които получавате на този адрес.
Примерна проверка на signature за PHP може да видите долу:
function validateWebhook($request) {
$headers = $request->get_headers();
// Verify timestamp
$timestamp = isset($headers['x-buyercheck-timestamp'][0]) ? $headers['x-buyercheck-timestamp'][0] : null;
if (!$timestamp || abs(time() - $timestamp) > 300) { // 5 minute window
return false;
}
// Verify signature
$params = $request->get_params();
$received_signature = isset($headers['x-buyercheck-signature'][0]) ? $headers['x-buyercheck-signature'][0] : null;
$expected_signature = hash_hmac('sha256', $timestamp . json_encode($params), self::$webhook_secret);
if (!$received_signature || !hash_equals($expected_signature, $received_signature)) {
return false;
}
return true;
}
2.2. След валидиране на signature и payload, трябва да създадете механизъм, по който да маркирате поръчките, които получавате на webhook-а по начин, по който след това може да филтрирате, за да не ни изпращате поръчки, които вече сме обработили. Може да използвате buyercheck-finalized таг или мета свойство, в зависимост от структурата на базата данни на вашия магазин когато поръчката е със статус "successful" или "canceled".
Примерна заявка на webhook-а, изпратена от нас изглежда така:
{
"orders": [
{
"order_id": "1234567890",
"email": "test@example.com",
"phone": "0887654321",
"ip_address": "127.0.0.1",
"order_status": "pending",
"amount": 100,
"pending_amount": 100,
"created_at": "2025-10-11T00:00:00Z",
"risk_score": 12,
"recommended_action": "Cancel",
"risk_details_external": "High risk due to...",
"calculated_at": "2025-10-11T00:00:01Z"
}
]
}
Първото задължително поле, което трябва да зададете е category, но за да видите възможните стойности, трябва да изпратите заявка GET https://api.buyercheck.bg/onboard-store
След това, задайте и останалите данни за вашия магазин:
$data = array(
'api_user' => 'buyercheck_user_email',
'domain' => 'domain.com',
'category' => 'electronics',
'webhook_secret' => 'generate_secure_webhook_secret_here',
'webhook_url' => 'https://domain.com/randomstring/v1/webhook/',
'raw_data_consent' => true,
'excluded_test_emails' => array('test@example.com', 'test2@example.com'),
'excluded_test_phones' => array('+359888888888', '0887654321')
);
// Send data to Buyercheck API
$response = wp_remote_post('https://api.buyercheck.bg/onboard-store', array(
'headers' => array(
'x-buyercheck-key' => 'buyercheck_api_key'
),
'body' => $data
));
Обърнете внимание, че сме настроили магазина с excluded_test_emails и excluded_test_phones - така ще изключим имейли и телефони (с които сте тествали или тествате) от синхронизирането на поръчките - както за стари така и за бъдещи поръчки.
Трябва да изградите модул, който ще синхронизира поръчките от вашия магазин към нашите сървъри. Този модул трябва да започне със събиране на всички поръчки, изключвайки маркираните от webhook-а с buyercheck-finalized(виж. т.2.2) от най-старите към най-новите и да ги изпраща към нас, по следния начин и по 20 поръчки на заявка.
...
$orders = getOrdersExcludingBuyercheckFinalized();
// remap orders to buyercheck format
function remapOrder($order) {
$email = $order->customer_email;
$phone = $order->customer_phone;
// if raw_data_consent is false, hash email, phone and ip address
if (!$raw_data_consent) {
$email = hash('sha256', $email);
$phone = hash('sha256', $phone);
}
return [
'order_id' => $order->id,
'email' => $email, // hash email
'phone' => $phone, // hash phone
'ip_hash' => hash('sha256', $order->ip_address), // hash ip
'order_status' => $order->status, // order status (pending, completed, failed). Order status 'pending' means about to be sent or already sent to customer; not cancelled; not delivered.
'amount' => $order->total_amount, // total amount
'pending_amount' => $order->pending_amount, // pending amount - if status is pending , otherwise 0
'created_at' => $order->created_at // UTC timestamp
];
}
$remappedOrders = array_map('remapOrder', $orders);
// batch orders in pairs of 20
$batchedOrders = array_chunk($remappedOrders, 20);
foreach ($batchedOrders as $batch) {
// POST request to buyercheck api
$response = wp_remote_post('https://api.buyercheck.bg/submit-order-data', array(
'headers' => array(
'x-buyercheck-key' => 'buyercheck_api_key'
),
'body' => [
'store_id' => 'domain.com',
'api_user' => 'buyercheck_user_email',
'orders' => $batch
]
));
}
Обърнете внимание, че ако сме настроили магазина с raw_data_consent = false, трябва да хешираме със SHA-256 функция email, телефон и ip адрес - ако не го направите, ще получите грешка 400. Единствено изключение е ip_address, което винаги се подава хеширано.
Също обърнете внимание и на статусите - pending е всяка поръчка, която предстои да обработите или сте обработили и изпратили, но все още не е взета или върната.
След като създадете механизма за синхронизиране на поръчките, настройте CRON JOB, който да го изпълянява 3 пъти дневно - през 8 часа или поне веднъж на 12 часа. Също може да използвате и Event-базирани механизми за синхронизиране на поръчките, ако сте на платформа, която ги поддържа.
По време на финализиране на поръчката на клиент, след като е задал поне имейла си, можете да използвате API за проверка на риска на поръчката.
// POST request to buyercheck api
$response = wp_remote_post('https://api.buyercheck.bg/check-risk', array(
'headers' => array(
'x-buyercheck-key' => 'buyercheck_api_key'
),
'body' => [
'store_id' => 'domain.com',
'api_user' => 'buyercheck_user_email',
'email_hash' => hash('sha256', $order->customer_email), // hash email
'phone_hash' => hash('sha256', $order->customer_phone), // hash phone
'ip_hash' => hash('sha256', $order->ip_address), // hash ip
'amount' => $order->total_amount // total amount
]
));
Ще получите отговор в JSON формат:
{
"risk_score": 15, // 0-100
"recommended_action": "Cancel", // Process, Verify, Cancel
"risk_details": "Explanation of the risks in readable format"
}
Съветваме ви да запазите отговора в текущия чекаут обект на клиента за тази поръчка и да не изпращате нова заявка към API-то на BuyerCheck за същата поръчка, за да не изхабявате квотата ви от проверки към плана ви.
Join 10k+ people to get notified about new posts, news and updates.
Do not worry we don't spam!