Developer notes
Overview · Installation · Configuration · Usage · FAQ
Hooks used
Section titled “Hooks used”| Hook | Use |
|---|---|
create_shipment_post |
A new shipment with a tracking number becomes a parcel and is registered. |
update_shipment_post |
4.18 and later only (the hook does not exist in 4.17): a changed number or carrier resets the parcel. Registered in init.php only when PRODUCT_VERSION is 4.18.0 or higher. |
delete_shipments |
Parcels of deleted shipments are removed. |
Admin controllers orders.post, shipments.post |
Catch tracking numbers saved on the order and shipment forms on 4.17; assign the parcel badge. |
Storefront controller orders.post |
Adds the Delivery status tab and the status link on orders.details. |
| Template hooks | Storefront orders:tabs, orders:details_bullets; admin orders:data_shipping, shipments:additional_info. |
Hook for other add-ons
Section titled “Hook for other add-ons”fn_set_hook('kv_parcel_status_changed', $parcel, $old_status, $new_status, $track);Runs after a parcel changed its normalised status (after the order rule). $parcel is the row of ?:kv_pst_parcels, $track the normalised answer of the service. Messaging add-ons can send “out for delivery” or “delivered” messages from here.
Normalised statuses
Section titled “Normalised statuses”| Add-on | 17TRACK | AfterShip |
|---|---|---|
pending |
NotFound | Pending |
info_received |
InfoReceived | InfoReceived |
in_transit |
InTransit | InTransit |
out_for_delivery |
OutForDelivery | OutForDelivery |
pickup |
AvailableForPickup | AvailableForPickup |
failed_attempt |
DeliveryFailure | AttemptFail |
exception |
Exception | Exception |
expired |
Expired | Expired |
delivered |
Delivered | Delivered |
Webhook
Section titled “Webhook”index.php?dispatch=kv_parcel_status.webhook&token=<token> (storefront area, POST JSON). The token is created on install (128 bit). 17TRACK: the sign header (sha256 of body + “/” + API key) is checked when present. AfterShip: aftership-hmac-sha256 (base64 HMAC-SHA256 of the body with the webhook secret) is required when a secret is set. Answers: 200 applied, 401 bad signature, 403 bad token.
Tables
Section titled “Tables”| Table | Contents |
|---|---|
?:kv_pst_parcels |
One row per shipment: number, carrier, service, remote id, status, last event, ETA, applied order status, error, attempts, timestamps. |
?:kv_pst_events |
Carrier events per parcel, de-duplicated by a hash of time, text and place. |
?:kv_pst_log |
Activity log; the newest 3000 entries are kept. |
php admin.php --dispatch=kv_parcel_status.cron (or HTTP with cron_password). Time budget 240 s on the console, 50 s over HTTP.