Relavio Docs

Appearance

PHP SDK ​

Официальный Composer-пакет Relavio PHP SDK пока не выпущен. Для серверной интеграции используйте REST API напрямую через любой HTTP-клиент: Laravel HTTP Client, Guzzle, Symfony HttpClient или нативный curl.

Эта страница показывает базовый PHP-клиент для Search API, Suggest API и событий аналитики.

Базовые настройки ​

Для запросов нужны:

  • базовый URL API: https://relavio.su/api/v1;
  • API-ключ магазина;
  • JSON-заголовки;
  • заголовок api-key.
php
$baseUrl = 'https://relavio.su/api/v1';
$apiKey = 'YOUR_API_KEY';

Пример на Laravel HTTP Client ​

Если интеграция выполняется из Laravel-приложения, используйте Http facade.

php
use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'api-key' => config('services.relavio.api_key'),
])
    ->acceptJson()
    ->asJson()
    ->post('https://relavio.su/api/v1/search', [
        'query' => 'iphone',
        'page' => 1,
        'per_page' => 20,
        'withFilters' => true,
    ]);

if ($response->failed()) {
    throw new RuntimeException('Relavio API error: '.$response->body());
}

$data = $response->json('data');

Минимальный клиент ​

php
<?php

final class RelavioClient
{
    public function __construct(
        private readonly string $apiKey,
        private readonly string $baseUrl = 'https://relavio.su/api/v1',
    ) {}

    /**
     * @param array<string, mixed> $payload
     * @return array<string, mixed>
     */
    public function search(array $payload): array
    {
        return $this->request('search', $payload);
    }

    /**
     * @param array<string, mixed> $payload
     * @return array<string, mixed>
     */
    public function suggests(array $payload): array
    {
        return $this->request('search/suggests', $payload);
    }

    /**
     * @param array<string, mixed> $payload
     * @return array<string, mixed>
     */
    public function event(array $payload): array
    {
        return $this->request('search/events', $payload);
    }

    /**
     * @param array<string, mixed> $payload
     * @return array<string, mixed>
     */
    private function request(string $path, array $payload): array
    {
        $ch = curl_init(rtrim($this->baseUrl, '/').'/'.$path);

        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST => true,
            CURLOPT_HTTPHEADER => [
                'Accept: application/json',
                'Content-Type: application/json',
                'api-key: '.$this->apiKey,
            ],
            CURLOPT_POSTFIELDS => json_encode($payload, JSON_THROW_ON_ERROR),
        ]);

        $body = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        $error = curl_error($ch);

        curl_close($ch);

        if ($body === false) {
            throw new RuntimeException('Relavio request failed: '.$error);
        }

        $decoded = json_decode($body, true, 512, JSON_THROW_ON_ERROR);

        if ($status < 200 || $status >= 300) {
            throw new RuntimeException('Relavio API error '.$status.': '.$body);
        }

        return $decoded;
    }
}

Поиск товаров ​

php
$client = new RelavioClient('YOUR_API_KEY');

$result = $client->search([
    'query' => 'iphone',
    'page' => 1,
    'per_page' => 20,
    'withFilters' => true,
    'filters' => [
        'brand' => ['Apple'],
        'price' => [
            'from' => 50000,
            'to' => 120000,
        ],
    ],
]);

$products = $result['data']['products'] ?? [];

Подсказки ​

php
$suggests = $client->suggests([
    'query' => 'iph',
    'session_id' => 'session-123',
]);

$suggestions = $suggests['data']['suggestions'] ?? [];

Событие аналитики ​

php
$client->event([
    'event_id' => bin2hex(random_bytes(16)),
    'event_type' => 'click',
    'search_id' => 'search-123',
    'session_id' => 'session-123',
    'external_id' => 'iphone-15-128',
    'product_name' => 'iPhone 15 128GB Black',
    'position' => 1,
    'page' => 1,
    'price' => 99990,
    'currency' => 'RUB',
    'metadata' => [
        'source' => 'server',
    ],
]);

Обработка ошибок ​

Обрабатывайте основные статусы отдельно:

  • 401 - неверный или отсутствующий API-ключ;
  • 402 - превышен лимит или недостаточно баланса;
  • 422 - ошибка валидации payload;
  • 500 - внутренняя ошибка сервера.

Подробнее: Ошибки API.

Хранение ключа ​

Не храните API-ключ в коде. Для Laravel добавьте ключ в .env:

ini
RELAVIO_API_KEY=YOUR_API_KEY

И опишите его в config/services.php:

php
'relavio' => [
    'api_key' => env('RELAVIO_API_KEY'),
],

Связанные разделы ​