Інтеграція InPost (Поштомати)

Модуль InPost інтегрує WooCommerce з API ShipX. Генеруйте етикетки, дозвольте клієнтам вибрати поштомат на карті та відстежуйте відправлення з панелі адміністратора.

Налаштування

Перейдіть до WooCommerce > Налаштування > Polski PRO > InPost.

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

Налаштування	Опис
Токен API	Токен авторизації з панелі InPost Manager
ID організації	Ідентифікатор організації в системі InPost
Режим sandbox	Використовує тестове середовище ShipX API

Токен передається в заголовку Authorization: Bearer {token}. Він повинен мати дозволи на створення відправлень та етикеток.

Налаштування методу доставки

Після налаштування API створіть новий метод доставки:

Перейдіть до WooCommerce > Налаштування > Доставка > Зони доставки
Відредагуйте зону “Polska”
Натисніть “Додати метод доставки”
Виберіть “InPost Поштомат” або “InPost Кур’єр”

Налаштування методу	Типове значення	Опис
Назва методу	”InPost Поштомат”	Назва, що відображається клієнту
Вартість	0	Вартість доставки (0 = безкоштовна)
Безкоштовна доставка від	""	Сума замовлення, від якої доставка безкоштовна
Типовий розмір посилки	A	Розмір: `A`, `B`, `C`
Страхування	Ні	Додати страхування до відправлення

Карта пунктів видачі

Віджет карти

Після вибору “InPost Поштомат” на сторінці оформлення замовлення відображається інтерактивний віджет карти.

Віджет пропонує:

Карту з мітками поштоматів
Пошук за містом - введіть назву міста, щоб відцентрувати карту
Пошук за координатами - автоматична геолокація (за згодою користувача)
Пошук за поштовим індексом - знайдіть найближчі поштомати
Список поштоматів - відсортований від найближчого
Деталі пункту - адреса, години роботи, доступні розміри комірок

Пошук за містом

Віджет надсилає запит до ендпоінту ShipX API:

GET /v1/points?type=parcel_locker&city={city}&per_page=25

Результати кешуються на 24 години в transients WordPress.

Пошук за координатами

Коли клієнт надасть згоду на геолокацію:

GET /v1/points?type=parcel_locker&relative_point={lat},{lng}&per_page=10

Фільтрування пунктів

/**
 * Фільтрує список пунктів видачі InPost.
 *
 * @param array  $points  Масив пунктів видачі з API
 * @param string $city    Шукане місто
 * @param array  $coords  Координати [lat, lng] або порожній масив
 */
apply_filters('polski_pro/inpost/points', array $points, string $city, array $coords): array;

Приклад - виключення тимчасово недоступних пунктів:

add_filter('polski_pro/inpost/points', function (array $points, string $city, array $coords): array {
    $excluded_points = ['KRA123', 'WAW456']; // Тимчасово вимкнено
    return array_filter($points, function (array $point) use ($excluded_points): bool {
        return ! in_array($point['name'], $excluded_points, true);
    });
}, 10, 3);

Генерація етикеток

З панелі замовлення

У панелі InPost на сторінці замовлення:

Згенерувати етикетку - створює відправлення в API ShipX і генерує PDF-етикетку
Завантажити етикетку - завантажує згенеровану етикетку
Друкувати етикетку - відкриває попередній перегляд друку

Масова генерація

Виберіть кілька замовлень у списку та виберіть “Згенерувати етикетки InPost”. Етикетки генеруються у фоновому режимі. Після завершення завантажте файл ZIP.

Дані відправлення

Етикетка генерується на основі:

Поле	Джерело	Опис
Відправник	Налаштування магазину	Адреса та дані компанії з WooCommerce
Одержувач	Дані замовлення	Ім’я, прізвище, телефон, e-mail
Пункт видачі	Вибір клієнта	ID поштомата, вибраного при оформленні
Розмір посилки	Налаштування методу	Або перевизначення в замовленні
Сума накладеного платежу	Замовлення COD	Лише для замовлень з оплатою при отриманні

Хук генерації етикетки

/**
 * Фільтрує дані відправлення перед надсиланням до API ShipX.
 *
 * @param array     $shipment_data Дані відправлення
 * @param \WC_Order $order         Замовлення WooCommerce
 */
apply_filters('polski_pro/inpost/shipment_data', array $shipment_data, \WC_Order $order): array;

Приклад - додавання посилання на замовлення:

add_filter('polski_pro/inpost/shipment_data', function (array $shipment_data, \WC_Order $order): array {
    $shipment_data['reference'] = sprintf('ORDER-%s', $order->get_order_number());
    return $shipment_data;
}, 10, 2);

Відстеження відправлень

Автоматичне відстеження

Після генерації етикетки модуль перевіряє статус відправлення кожні 2 години (WP-Cron). Статуси відображаються на статуси WooCommerce:

Статус InPost	Статус WooCommerce	Опис
`created`	`processing`	Відправлення створено
`dispatched_by_sender`	`processing`	Надіслано відправником
`collected_from_sender`	`shipped`	Забрано від відправника
`out_for_delivery`	`shipped`	У доставці
`ready_to_pickup`	`shipped`	Готове до отримання в поштоматі
`delivered`	`completed`	Доставлено / отримано

Сповіщення клієнта

Клієнт отримує e-mail із посиланням на відстеження на сайті InPost. Посилання додається до:

E-mail “Замовлення в обробці”
Сторінки “Мій акаунт > Замовлення > Деталі”
Нотаток замовлення (видимих для клієнта)

Хук відстеження

/**
 * Дія, що викликається після оновлення статусу відправлення.
 *
 * @param int      $order_id      ID замовлення
 * @param string   $tracking_number Номер відстеження
 * @param string   $old_status    Попередній статус InPost
 * @param string   $new_status    Новий статус InPost
 */
do_action('polski_pro/inpost/status_updated', int $order_id, string $tracking_number, string $old_status, string $new_status);

Приклад - SMS-сповіщення про готовність до отримання:

add_action('polski_pro/inpost/status_updated', function (
    int $order_id,
    string $tracking_number,
    string $old_status,
    string $new_status
): void {
    if ($new_status === 'ready_to_pickup') {
        $order = wc_get_order($order_id);
        $phone = $order->get_billing_phone();
        send_sms($phone, sprintf(
            'Ваша посилка %s чекає в поштоматі. Код отримання в e-mail.',
            $tracking_number
        ));
    }
}, 10, 4);

Розміри посилок

Розмір	Габарити (см)	Вага макс.
A	8 x 38 x 64	25 кг
B	19 x 38 x 64	25 кг
C	41 x 38 x 64	25 кг

Розмір посилки можна встановлювати глобально, для кожного методу доставки або перевизначати вручну в замовленні.

Усунення проблем

Карта поштоматів не завантажується Перевірте, чи токен API правильний та активний. Перевірте консоль браузера на наявність помилок CORS або JavaScript. Переконайтеся, що скрипт polski-pro-inpost-map.js завантажено.

Помилка генерації етикетки “Unauthorized” Токен API минув або не має дозволів на створення відправлень. Згенеруйте новий токен у панелі InPost Manager.

Статус відправлення не оновлюється Перевірте, чи WP-Cron працює правильно. Запустіть вручну: wp cron event run polski_pro_inpost_tracking.

Подальші кроки

Повідомляйте про проблеми: GitHub Issues
Документація API ShipX: https://docs.inpost24.com/

Ця сторінка має суто інформаційний характер і не є юридичною консультацією. Перед впровадженням проконсультуйтеся з юристом. Polski for WooCommerce є програмним забезпеченням з відкритим кодом (GPLv2), що надається без гарантій.