Доставка и накладные
Способ доставки устроен в точности как способ оплаты: ключ, валюты, свойства и необязательный драйвер. Без драйвера цену считает таблица, с драйвером — спрашивают перевозчика.
Кто из двоих, решается в одном месте, DeliveryService::quote(). Разойдись эта развилка на показе корзины и на оформлении — покупатель увидел бы одну цену, а заплатил другую.
Цена таблицей
Хватает для самовывоза и курьера по городу, и не требует ни API, ни ключа, ни договора.
| Поле | Что делает |
|---|---|
prices | цена на валюту |
tiers | пороги по весу: upto в граммах и цены. Порог без upto — «и выше» |
free_from | бесплатно от этой суммы товаров, на валюту |
max_weight | предел веса в граммах; пусто — без предела |
Порядок разбора: сначала побеждает «бесплатно от суммы», потом подходящий порог по весу, потом ровная цена.
За пределом веса способ исчезает
Он не показывается с отказом — он убирается из списка. Способ, который не увезёт эту посылку, — не тот выбор, в который покупателю надо вникать: при посылке 21 кг и пределе 20 у него просто одним вариантом меньше.
Цена у перевозчика
Вместо таблицы спрашивают драйвер. Три вещи о том, чего это стоит.
Ответы кешируются: цена — 10 минут, справочник городов и отделений — сутки, а отказ — минуту, чтобы лежащее API не долбили на каждый показ страницы.
Молчащее API откатывается на таблицу. Если перевозчика не дозвались, способ продолжает работать по табличной цене, а откат пишется в журнал MODX. Эта строка важна: незаполненный ключ службы раньше терялся молча, и магазин выглядел так, будто считает по API, а считал таблицей.
Явный отказ — не то же, что сбой. Когда перевозчик ответил и сказал, что не повезёт, способ убирается из списка, и откат не делается. Откатиться здесь значило бы назвать цену услуге, в которой только что отказали.
Отказ перевозчика покупателю не показывают
Не показывали и не показывают: список собирается из доступного. Журнал — это то место, куда смотрят, когда ожидаемого способа в списке нет.
Пункты выдачи
POST /pay/delivery способы под состав корзины
POST /pay/delivery/{ключ}/cities поиск города
POST /pay/delivery/{ключ}/points отделения в городеВстроенная витрина спрашивает город поиском и дальше предлагает два выбора. Блок отделения и блок адреса не показываются вместе — выключенный выключен целиком, а не сделан серым.
В снимок заказа рядом с улицей уезжают city_ref, point и point_ref. У Новой Пошты это Ref перевозчика, а у Укрпошти ссылка на отделение — это индекс: им её опознаёт и расчёт, и накладная.
Обязательные поля адреса
Служба сама называет, какие поля ей нужны, и ответ зависит от того, куда едет посылка:
| Драйвер | До отделения | До двери |
|---|---|---|
novaposhta | ничего | город, улица |
ukrposhta | ничего | индекс, улица, дом |
Это держит сервер, а не только форма
До 13.10.2026 список назывался, доезжал до витрины пометить поля звёздочкой — и на сервере его не проверял никто. Ломалось в обе стороны: доставка до отделения требовала адреса, которого у неё нет, а Почте России хватало любого адреса без индекса.
Если пишете свой чанк корзины, ваша форма обязана эти поля собрать: сервер откажет строкой pbs_err_address_fields и назовёт недостающие.
Способ без драйвера отвечает вместо этого своей колонкой «нужен адрес». У способа с драйвером эту колонку не спрашивают вовсе.
Накладные (ТТН)
Выписывают оба драйвера коробки. В окне заказа три кнопки — создать, отследить, удалить, — а защита от второй накладной стоит в сервисе, а не в драйверах: перевозчик берёт за каждую, и ошибка здесь стоит настоящих денег так, что тестом её не поймать.
Всё, что нужно службе, лежит в properties способа доставки.
Нова Пошта — api_key, city_sender, sender, sender_address, sender_contact, sender_phone, payer, payment_method, cargo_type, service_type, cod, cod_payer.
Четыре значения sender* — это Ref из справочника самой службы, а не названия, которые печатают руками. Получатель, наоборот, заводится на лету. service_type — куда едет посылка: WarehouseWarehouse, WarehouseDoors, DoorsWarehouse, DoorsDoors.
Укрпошта — api_key, token, api_key_tracking, sender_uuid, postcode_sender, type, delivery_type, package, cod, paid_by_recipient, name_order.
Укрпошті нужны три отдельных доступа
Это удивляет каждого по одному разу. Bearer к eCom API, token контрагента, который едет в адресе параметром, и третий bearer к status-tracking, а это другая служба на другом хосте. Выписка одной накладной — три вызова: адрес, потом клиент, потом отправление.
И ещё: курьеру она требует индекс, улицу и дом. По одному индексу накладную не примет.
Печать наклейки — не наша. Бланк у каждой службы свой и отдаётся готовым PDF (у Укрпошти — /shipments/{uuid}/sticker). Это скачивание чужого файла, а не наш рендер. Не путать с документами, которые магазин рисует сам.
Трекинг
WaybillService::dueForTracking() отбирает посылки, про которые стоит спросить, а track() на каждую зовёт крон сайта — см. Подписки и крон. Доехавшая и расчётная посылка из отбора уходит, а не опрашивается вечно.
Ответ трекинга несёт код, человеческий текст, дату и три отдельных признака: доставлено, возврат и деньги. То, что последние два отделены от первого, — весь смысл:
| Служба | Код | Что значит |
|---|---|---|
| Нова Пошта | 9 | вручено — не деньги |
| Нова Пошта | 10 | вручено, деньги собраны |
| Нова Пошта | 11 | вручено, деньги переведены магазину |
| Нова Пошта | 102, 103, 106 | отказ, возврат, обмен |
| Укрпошта | 41000 | вручено получателю |
| Укрпошта | 41010 | вручено отправителю — то есть возврат |
| Укрпошта | 31200, 35500 | возврат, международный возврат |
У Укрпошти своего кода для возврата нет вовсе
Он приходит тем же кодом, что доставка, — 41000, и отличается только полем причины. Драйвер составляет 41010, чтобы их различать. Если читаете коды в своём слушателе — читайте признаки, а не коды.
События и лента истории срабатывают только на смену кода. Крон опрашивает перевозчика раз в час, и событие на каждый ответ означало бы письмо «посылка едет» ежечасно всё время, пока она едет.
Наложенный платёж
Работает целиком: сумма уезжает в накладную, а когда служба сообщает, что деньги переведены, заказ становится оплаченным.
Включается свойством cod у способа доставки. Дальше сумма едет в накладной — BackwardDeliveryData у Новой Пошты, postPayData у Укрпошти.
Как узнают о деньгах — различается, и ни один из способов не есть «посылка доехала»:
- Нова Пошта говорит об этом в самом статусе — код
11; - Укрпошта в трекинге не говорит вовсе. Нужен второй запрос к другому сервису, и драйвер делает его только по вручённой посылке и только у способа, настроенного на наложенный платёж.
Дальше магазин записывает деньги обычным порядком: строка платежа помечается оплаченной, и pbShopPaymentSuccess → заказ оплачен следует само. Второй дороги к «оплачен» намеренно нет, потому что на первой висят лента истории, склад, промокод, чек и письмо.
Записывается сумма заказа, а не сумма перевода
Служба удерживает свой процент, и на счёт магазина приходит меньше. Но покупатель на отделении заплатил полную цену, и заказ оплачен целиком; удержанное — расход магазина перед перевозчиком, а не недоплата покупателя. Запиши сюда перевод — и каждый заказ с наложенным платежом читался бы недоплаченным, с вечным долгом размером в комиссию.
Вопрос про деньги задаётся до гейта «сменился ли код», и это не случайность. У Укрпошти перевод приходит, не меняя кода посылки: заказ может стоять на «вручено» неделю, а потом приходит перевод. Под гейтом магазин не узнал бы о нём никогда.
Повторов это не даёт: запись идемпотентна по платежам заказа, а не по его статусу. «Деньги у магазина» — состояние, а не событие: служба будет отвечать 11 до конца времён.
is_paid у статуса — не про деньги
Это стоит знать, если строите свою логику поверх. В поставочном сиде is_paid стоит и у «Отправлен», а не только у «Оплачен»: он означает «выдать доступ», а не «деньги пришли». На вопрос «деньги правда пришли» отвечает isSettled(), который смотрит строки платежей.
Ошибка здесь выключала наложенный платёж целиком на установке по умолчанию: менеджер, переводивший заказ в «Отправлен», то есть делавший ровно то, что от него ждут, заставлял магазин считать заказ уже оплаченным.
События
pbShopWaybillCreate pbShopWaybillStatus
pbShopOrderDelivered pbShopOrderReturnedВернувшаяся посылка сама статус заказа не меняет. Что значит возврат — деньги назад, пересылка, разговор — это политика магазина, а не компонента.
Дальше
- Заказы в менеджере — лист сборки и накладная в посылку
- Что где лежит — куда уехали СДЭК и Почта России