Developer notes
Technical reference for developers who customize Sendcloud Shipping.
Add-on identity
Section titled “Add-on identity”| Item | Value |
|---|---|
| Add-on id | kv_sendcloud |
| Function prefix | fn_kv_sendcloud_ |
| Language variables | kv_sendcloud.* |
| CSS scope | .kv-sendcloud |
| PHP namespace | Tygh\Addons\KvSendcloud |
| Preset | shipping (generated by kv new --kind integration) |
Structure
Section titled “Structure”| Class | Role |
|---|---|
Client\BaseClient |
HTTP (cURL, TLS verification, timeouts), JSON, error mapping, masked logging |
Client\Api |
The Sendcloud v3 calls: shippingOptions, servicePoints, announce, cancel, shipment, tracking, returnPortalUrl, document; HTTP Basic authentication |
Options |
Request body of /shipping-options and the choice of one option (carrier list, exact code, cheapest / fastest, home vs. service point) |
RateCalculator |
Checkout rate: one Sendcloud call per route and weight (memory and 5 minute session cache), currency conversion, markup / free threshold / fallback |
Points |
Service point search and mapping, selection in the cart, the point stored with the order (kv_sendcloud_points) |
Shipments |
Announce (create + label), cancel, tracking, webhook status, core shipment, payload mapping |
Client |
Client per company, the connection test |
Accounts, Secret |
Credentials (test and live) 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: back-off 5 min / 15 min / 1 h / 3 h / 12 h, per-job isolation, overlap lock; handlers in Jobs::handle(), recurring work in Jobs::schedule() |
Log |
Event log with masking, filters, CSV, retention |
Webhook |
Signature check and event ids; the controller kv_sendcloud.webhook?c=<account> stores the event as a job |
Database tables
Section titled “Database tables”| Table | Purpose |
|---|---|
?:kv_sendcloud_accounts |
Credentials per company (secrets sealed), last connection check, token cache |
?:kv_sendcloud_log |
Log |
?:kv_sendcloud_jobs |
Queue |
?:kv_sendcloud_shipments |
Labels and tracking (shipment id, parcel id, option code, label file) |
?:kv_sendcloud_points |
The service point chosen at checkout, per order |
Hooks used
Section titled “Hooks used”PHP hooks: change_order_status_post (automatic labels), get_order_info (attach the point), place_order, place_suborders (Multi-Vendor sub-orders), delete_order, template_document_order_context_init (point on invoices and e-mails). Template hooks: checkout:shipping_method (picker card), orders:totals_shipping (storefront order), orders:tabs_extra, orders:customer_shot_info, orders:list_extra_links (admin order). The bulk action is a context menu item (schemas/context_menu/orders.post.php).
Sendcloud endpoints used
Section titled “Sendcloud endpoints used”POST /shipping-options, GET /service-points, POST /shipments/announce, POST /shipments/{id}/cancel, GET /shipments/{id}, GET /parcels/tracking/{tracking_number}, GET /parcels/{id}/documents/label, GET /shipments/{id}/return-portal-url, all below https://panel.sendcloud.sc/api/v3. Webhook: parcel_status_changed, header Sendcloud-Signature (hex HMAC-SHA256 of the raw body).
Test the HTTP layer without the provider
Section titled “Test the HTTP layer without the provider”The base URL can be overridden for tests in config.local.php (development only):
$config['kv_sendcloud_base_url'] = 'http://127.0.0.1:11830';node tests/mock-server/server.js 11830 starts a local stand-in of the provider API; node tests/e2e/e2e.mjs runs the HTTP end-to-end test against it; php tests/unit.php runs the unit tests.
Template overrides
Section titled “Template overrides”Admin templates live in design/backend/templates/addons/kv_sendcloud/. Do not edit them in a store; they are replaced on update.