Developer notes
Part of the BOX NOW Lockers documentation. Previous: Troubleshooting. Next: Conformance with the BOX NOW documents.
Add-on id kv_box_now, namespace Tygh\Addons\KvBoxNow, shipping service module kv_box_now (class Tygh\Shippings\Services\KvBoxNow, service code boxnow_locker). PHP 7.4 to 8.3, Smarty 4 and 5 (no Smarty plugin files; plain fn_* modifiers only).
Source map
Section titled “Source map”| File | Role |
|---|---|
Client/Api.php |
Partner API: auth-sessions (JSON client credentials, token cached encrypted), origins, entrusted-partners, delivery-requests, parcels, labels, :cancel, PUT delivery-requests/{orderNumber}, :customerReturns; X-PartnerID; {code, message} errors. |
Client/Locations.php |
Public locker list `locationapi-<stage |
Client/BaseClient.php |
cURL (TLS verification on), logging with masking, error mapping, test transport. |
Lockers.php |
Local copy of the locker list (kv_box_now_lockers), server-side check of a locker id, search by postal code. |
Points.php |
Locker of the cart / order, widget script per country. |
Shipments.php |
Delivery flow: record-before-call with the order number, P410 adoption via GET /parcels?orderNumber=, unknown results, labels, cancel, returns, events (data.time order, never backwards), polling. |
Webhook.php |
Keyed webhook URL, CloudEvents parsing (data.event), header reader. |
Parcel.php |
Field rules: international phones, two-decimal amounts, compartment sizes, order numbers, tracking URL, mb_substr cuts. |
RateCalculator.php |
Merchant price, country of the account, 20 kg, box fit. |
Accounts.php, Queue.php, Jobs.php, Access.php, Idempotency.php |
Credentials (AES-256-GCM sealed, Stage + Production), job queue, vendor rules, locks. |
Tables
Section titled “Tables”kv_box_now_accounts, _shipments (one row per delivery request, order_number written before the call), _parcels (one row per parcel, outbound O / return R, state and last event time), _points (locker of an order), _lockers (locker list per environment and country), _jobs, _log.
change_order_status_post (automatic request), get_order_info, place_order, place_suborders (locker of the cart to the order and sub-orders), delete_order, template_document_order_context_init (locker in invoices and e-mails). Controllers: checkout.pre (no order without a locker), frontend kv_box_now (cron, webhook, lockers, point_select), backend kv_box_now and orders.post (tab).
Rules in force
Section titled “Rules in force”mb_substr for every text cut; per-order GET_LOCK and atomic claims; the delivery row with its order number before the POST, lookup before resend; refused credentials pause the account; vendor privilege per action (run_now, cron, backfill closed) and owner-mode checks; shop time zone for displayed dates; tests never reach BOX NOW (the e2e refuses a non-local mock).
php81 tests/unit.php && php83 tests/unit.phpphp -S 127.0.0.1:<port> tests/mock-server/server.phpnode tests/e2e/e2e.mjs --store <url> --db <db> --root <store dir> --mock http://127.0.0.1:<port>node tests/e2e/vendor-smoke.mjs --store <mv url> --db <mv db> --root <mv dir> --mock http://127.0.0.1:<port>The mock follows tests/fixtures/official/contract.json, transcribed from the official manual and webhook guide.