Yii2 и интеграция с сервисами доставки: как не сойти с ума

Когда ваш интернет-магазин начинает расти, вопрос доставки становится головной болью. Вручную создавать заказы, отслеживать посылки, рассчитывать стоимость — это ад. Но есть решение: подключить сервис доставки через API. В этой статье я покажу, как сделать это на Yii2, используя проверенные подходы. Вы узнаете, как работать с API, кэшировать данные и обрабатывать ошибки, чтобы ваш код не развалился в самый неподходящий момент.

Digital-студия WNDER

Почему именно Yii2?

Yii2 — это не просто фреймворк, а настоящий швейцарский нож для веб-разработчика. У него есть встроенные компоненты для работы с HTTP-запросами, кэшированием и логированием. Всё, что нужно для интеграции с внешними сервисами, уже есть из коробки. Не нужно изобретать велосипед — просто бери и используй.

Допустим, вы хотите подключить несколько служб доставки: Почту России, СДЭК и Boxberry. У каждой — свой API, свои форматы данных и свои особенности. Но Yii2 позволяет абстрагироваться от этих различий с помощью компонентов. Вы создаёте общий интерфейс, а под каждую службу — свой класс-адаптер. Это удобно и масштабируемо.

Проектируем архитектуру

Прежде чем писать код, давайте подумаем, что нам нужно от службы доставки. Обычно это три вещи:

\n
• Расчёт стоимости доставки по адресу и весу посылки.
\n
• Создание заказа на доставку.
\n
• Отслеживание статуса посылки.
\n

Каждый сервис имеет свои методы, но мы можем свести их к общему интерфейсу. Например, так:

interface DeliveryServiceInterface\n{\n    public function calculateCost($address, $weight);\n    public function createOrder($orderData);\n    public function trackOrder($trackingNumber);\n}

Теперь для каждой службы пишем свой класс, реализующий этот интерфейс. Например, для СДЭК:

class CdekService implements DeliveryServiceInterface\n{\n    private $apiUrl = 'https://api.cdek.ru/v2';\n    private $client;\n\n    public function __construct()\n    {\n        $this->client = new \\yii\\httpclient\\Client([\n            'baseUrl' => $this->apiUrl,\n            'requestConfig' => [\n                'format' => \\yii\\httpclient\\Client::FORMAT_JSON,\n            ],\n            'responseConfig' => [\n                'format' => \\yii\\httpclient\\Client::FORMAT_JSON,\n            ],\n        ]);\n    }\n\n    public function calculateCost($address, $weight)\n    {\n        $response = $this->client->post('/calculator/tarifflist', [\n            'from_location' => ['code' => 'MSK'],\n            'to_location' => ['address' => $address],\n            'packages' => [['weight' => $weight]],\n        ])->send();\n\n        if (!$response->isOk) {\n            throw new \\Exception('СДЭК: ошибка расчёта стоимости');\n        }\n\n        return $response->data['total_sum'];\n    }\n\n    // ... остальные методы\n}

Точно так же делаем классы для других служб. В итоге получаем гибкую систему, где добавить новую службу — дело пяти минут.

Кэшируем, чтобы не платить лишнего

API служб доставки — это не бесплатный ресурс. За каждый запрос, как правило, нужно платить или есть ограничение по количеству. Поэтому очень важно кэшировать ответы. Например, стоимость доставки для одного и того же города и веса вряд ли изменится за час.

В Yii2 кэш настраивается элементарно. Создаём компонент кэша в конфигурации:

'components' => [\n    'cache' => [\n        'class' => 'yii\\caching\\FileCache',\n    ],\n],

Теперь в методе расчёта стоимости сначала проверяем кэш:

public function calculateCost($address, $weight)\n{\n    $cacheKey = 'delivery_cost_' . md5($address . $weight);\n    $cost = \\Yii::$app->cache->get($cacheKey);\n\n    if ($cost === false) {\n        $cost = $this->fetchCostFromApi($address, $weight);\n        \\Yii::$app->cache->set($cacheKey, $cost, 3600); // на час\n    }\n\n    return $cost;\n}

Вот и всё. Теперь один и тот же запрос не будет долбить API каждый раз, когда пользователь обновляет страницу.

Обработка ошибок и вебхуки

Ни один API не работает идеально. Бывают сбои, таймауты, неожиданные форматы ответов. Ваш код должен быть готов к этому. В Yii2 есть удобный механизм обработки исключений и логирования.

Оберните вызов API в try-catch:

try {\n    $response = $this->client->post('/orders', $orderData)->send();\n    if (!$response->isOk) {\n        throw new \\Exception('Не удалось создать заказ: ' . $response->data['message']);\n    }\n    return $response->data['entity']['uuid'];\n} catch (\\Exception $e) {\n    \\Yii::error(\"Ошибка создания заказа: \" . $e->getMessage(), 'delivery');\n    throw new \\yii\\web\\ServerErrorHttpException('Сервис доставки временно недоступен');\n}

Теперь о вебхуках. Это способ, когда сервис доставки сам сообщает вашему сайту об изменении статуса посылки. Например, "заказ принят", "в пути", "доставлен". В Yii2 для этого нужно создать action, который принимает POST-запрос от сервиса.

public function actionWebhook()\n{\n    $data = \\Yii::$app->request->post();\n    // Проверяем подпись, чтобы убедиться, что запрос от настоящего сервиса\n    if (!$this->validateSignature($data)) {\n        throw new \\yii\\web\\ForbiddenHttpException('Неверная подпись');\n    }\n\n    // Обновляем статус заказа в базе\n    $order = Order::findOne(['tracking_number' => $data['track_number']]);\n    if ($order) {\n        $order->status = $data['status'];\n        $order->save();\n    }\n\n    // Возвращаем 200 OK\n    \\Yii::$app->response->statusCode = 200;\n    return;\n}

Обратите внимание на проверку подписи. Без неё любой злоумышленник может отправить фейковый вебхук и испортить статусы заказов. Каждый сервис доставки предоставляет свою схему подписи — обычно это HMAC-подпись на основе секретного ключа.

Практические советы

Собрал несколько лайфхаков, которые сэкономят вам часы работы:

\n
• Используйте официальные SDK. Многие сервисы (например, СДЭК) предоставляют готовые библиотеки для PHP. Не нужно изобретать велосипед — просто подключите через Composer.
\n
• Тестируйте на песочнице. У всех крупных сервисов есть тестовое окружение. Обязательно используйте его на этапе разработки, чтобы не тратить реальные деньги на тестовые заказы.
\n
• Логируйте все запросы. Включите логирование HTTP-запросов в Yii2. Это поможет быстро найти причину ошибки, когда что-то пойдёт не так.
\n
• Не доверяйте ответам API на 100%. Всегда проверяйте, что данные пришли в ожидаемом формате. Иногда сервисы меняют структуру ответа без предупреждения.
\n

Вот пример, как настроить логирование HTTP-запросов в Yii2:

$client = new \\yii\\httpclient\\Client([\n    'transport' => 'yii\\httpclient\\CurlTransport',\n    'requestConfig' => [\n        'options' => [\n            CURLOPT_VERBOSE => true,\n            CURLOPT_STDERR => fopen('/var/log/curl.log', 'a'),\n        ],\n    ],\n]);

Так вы будете видеть все заголовки и тела запросов, что очень помогает при отладке.

Что в итоге

Интеграция Yii2 с сервисами доставки — это не ракетостроение. Главное — правильно спроектировать архитектуру, использовать кэширование и не забывать про обработку ошибок. Следуя этим принципам, вы получите надёжную систему, которая будет работать без сбоев.

Надеюсь, мои советы помогут вам сэкономить время и нервы. Если у вас остались вопросы — пишите в комментариях, постараюсь ответить.

Студия WNDER