Примеры работы с API

Готовые сценарии на PHP, JavaScript и cURL. Описание всех методов — в документации API v2. Токен сайта берётся в кабинете: «Интеграция».

Сценарий 1. Магазин передаёт трек-номер

Заказ отправлен: сообщаем Слуху трек и покупателя. Слух определит службу доставки, начнёт опрос и будет присылать покупателю каждое событие.

curl -X POST https://slyh.ru/api/v2/tracking \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1048-track" \
  -d '{
    "track_number": "RB123456789CN",
    "order": "1048",
    "customer": {"name": "Анна Петрова", "phone": "+79001112233", "email": "anna@example.ru"}
  }'

Заголовок Idempotency-Key защищает от дублей при повторе запроса: безопасно повторять, если ответ не пришёл.

Сценарий 2. Смена статуса заказа

$payload = json_encode([
    'order'    => '1048',
    'status'   => 'Заказ собран и передан в доставку',
    'customer' => ['phone' => '+79001112233'],
], JSON_UNESCAPED_UNICODE);

$ch = curl_init('https://slyh.ru/api/v2/statuses');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 5,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json',
        'Idempotency-Key: 1048-' . md5('Заказ собран и передан в доставку'),
    ],
    CURLOPT_POSTFIELDS     => $payload,
]);
$result = json_decode(curl_exec($ch), true);

if (isset($result['error'])) {
    error_log('Слух: ' . $result['error']['code'] . ' — ' . $result['error']['message']);
}

Не блокируйте оформление заказа ответом сервиса: ставьте отправку в очередь и повторяйте при ошибках сети и кодах 5xx.

Сценарий 3. Сообщение по шаблону

Сначала создайте шаблон в кабинете («Интеграция» → «Шаблоны для API v2») с кодом order_ready и текстом «{name}, ваш заказ {order} готов к выдаче». Затем:

const response = await fetch('https://slyh.ru/api/v2/messages', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    template: 'order_ready',
    variables: { name: 'Анна', order: '1048' },
    customer: { phone: '+79001112233' },
  }),
});
const { data } = await response.json();           // { id: 42, status: 'queued' }

// Проверить результат позже
const state = await fetch(`https://slyh.ru/api/v2/messages/${data.id}`, { headers: { Authorization: `Bearer ${token}` } });
console.log((await state.json()).data.notifications);

Сценарий 4. Проверка статуса посылки

curl https://slyh.ru/api/v2/shipments/RB123456789CN -H "Authorization: Bearer $TOKEN"

Поле status: in_transit — в пути, delivered — доставлена, untrackable — отследить не удалось, return_or_long — возврат или долгая доставка, carrier_unknown — служба не опознана.

Сценарий 5. Приём вебхука

Адрес вебхука задаётся в кабинете. Всегда проверяйте подпись: без неё запрос может прислать кто угодно.

$body   = file_get_contents('php://input');
$sign   = $_SERVER['HTTP_X_SLYH_SIGNATURE'] ?? '';
$wanted = 'sha256=' . hash_hmac('sha256', $body, $secret);

if (!hash_equals($wanted, $sign)) {
    http_response_code(403);
    exit;
}

$event = json_decode($body, true);

if ($event['event'] === 'shipment.delivered') {
    // отметить заказ выполненным: $event['data']['tracking_number']
}

http_response_code(200);

Коды ошибок