Developer notes
Technical reference for developers who customize Royal Mail Click & Drop Shipping.
Add-on identity
Section titled “Add-on identity”| Item | Value |
|---|---|
| Add-on id | kv_royal_mail |
| Function prefix | fn_kv_royal_mail_ |
| Language variables | kv_royal_mail.* |
| CSS scope | .kv-royal-mail |
| PHP namespace | Tygh\Addons\KvRoyalMail |
| API | Royal Mail Click & Drop API v1, https://api.parcel.royalmail.com/api/v1, Authorization: Bearer <API key>, 5 calls per second |
Structure
Section titled “Structure”| Class | Role |
|---|---|
Client\BaseClient |
HTTP (cURL, TLS verification, timeouts), JSON, error mapping (401 / 403 / 429 have no body), raw PDF GET, masked logging |
Client\Api |
ping() (GET /carriers), services() (GET /services), createOrder() (POST /orders), orders() (GET /orders/{ids}), deleteOrders(), labels() (GET /orders/{ids}/label) |
Rates |
The rate table: zone of a country, weight bands, save / starter bands |
RateCalculator |
Called by the shipping service class at checkout: table lookup, no HTTP |
Shipments |
Create (payload mapping), track, cancel, label, bulk labels, CS-Cart shipment |
Installer |
The five checkout services and their delivery times |
Accounts, Secret |
API key sealed with AES-256-GCM; one account per store owner or per vendor |
Config, Access |
Settings, owner mode, who may see and manage what |
Queue, Jobs, JobException |
Job queue (create_label, track, probe): back-off 5 min / 15 min / 1 h / 3 h / 12 h, overlap lock |
Log |
Event log with masking, filters, CSV, retention |
The ChannelShipper-only endpoint GET /orders/{ids}/full is not used; tracking comes from GET /orders/{ids} (trackingNumber, printedOn, manifestedOn, shippedOn).
Database tables
Section titled “Database tables”| Table | Purpose |
|---|---|
?:kv_royal_mail_accounts |
API key per company (sealed), last connection check, account type and service codes (extra) |
?:kv_royal_mail_rates |
Rate table: company, service, zone (uk / eu / world), max grams, price |
?:kv_royal_mail_log |
Log |
?:kv_royal_mail_jobs |
Queue |
?:kv_royal_mail_shipments |
Click & Drop orders (provider_ref = orderIdentifier), tracking, stored label |
Hooks used
Section titled “Hooks used”PHP: change_order_status_post (send at a chosen status). Template hooks: orders:tabs_extra, orders:list_extra_links, addons:manage, addons:tabs_content, index:styles. Shipping service module kv_royal_mail (class Tygh\Shippings\Services\KvRoyalMail, service code = rate table key). Context menu schema orders (bulk actions).
Test without Royal Mail
Section titled “Test without Royal Mail”The base URL can be overridden for tests in config.local.php (development only):
$config['kv_royal_mail_base_url'] = 'http://127.0.0.1:11872/api/v1';node tests/mock-server/server.js 11872 starts a stand-in that follows tests/fixtures/click-and-drop-api-v1.yaml (the published Swagger file); node tests/e2e/e2e.mjs --seed seed.json runs the HTTP end-to-end test against it; php tests/unit.php runs the unit tests; php83 tests/smarty5-compile.php src/design compiles the templates with Smarty 5.
Template overrides
Section titled “Template overrides”Admin templates live in design/backend/templates/addons/kv_royal_mail/. Do not edit them in a store; they are replaced on update.