Developer notes
Technical reference for developers who customize TikTok Shop Connector.
Add-on identity
Section titled “Add-on identity”| Item | Value |
|---|---|
| Add-on id | kv_tiktok_shop |
| Function prefix | fn_kv_tiktok_shop_ |
| Language variables | kv_tiktok_shop.* |
| CSS scope | .kv-tiktok-shop |
| PHP namespace | Tygh\Addons\KvTiktokShop |
| Preset | marketplace (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 |
TikTok Shop Partner Center API: request signing (HMAC-SHA256 of path + sorted query + body, wrapped in the app secret), authorization code exchange, rotating refresh token under a database lock, per-API versions in the path (202309, 202502, 202507, 202602), business errors in HTTP 200, one thin method per endpoint |
Drivers\TikTokShop\Driver, Mapper |
Hub driver (SKU lookup by seller SKU, create product with image upload, inventory and price, orders, fulfilment, cancel, returns) and the pure translation (unit tested with the official samples in tests/fixtures/) |
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_tiktok_shop.webhook?c=<account> stores the event as a job |
Database tables
Section titled “Database tables”| Table | Purpose |
|---|---|
?:kv_tiktok_shop_accounts |
App credentials per company (secrets sealed), last connection check, sealed authorization (tokens + authorized shops) |
?:kv_tiktok_shop_log |
Log |
?:kv_tiktok_shop_jobs |
Queue |
?:kv_tiktok_shop_product_map, ?:kv_tiktok_shop_order_map |
Product mapping and imported orders |
Hooks used
Section titled “Hooks used”PHP hooks: update_product_post, delete_product_post (mark mapped products dirty) and init_templater_post (license UI plugin). Template hooks: addons:manage / tabs_content (license card) and index:styles (admin CSS).
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_tiktok_shop_base_url'] = 'http://127.0.0.1:12877';node tests/mock-server/server.js 12877 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_tiktok_shop/. Do not edit them in a store; they are replaced on update.