Skip to content

Доставка и накладные ​

Способ доставки устроен в точности как способ оплаты: ключ, валюты, свойства и необязательный драйвер. Без драйвера цену считает таблица, с драйвером — спрашивают перевозчика.

Кто из двоих, решается в одном месте, 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

Вернувшаяся посылка сама статус заказа не меняет. Что значит возврат — деньги назад, пересылка, разговор — это политика магазина, а не компонента.

Дальше ​

pbShop — магазин для сайтов на PageBlocks