Developer notes
Technical reference for developers who customize Trendyol Marketplace Connector.
Add-on identity
Section titled “Add-on identity”| Item | Value |
|---|---|
| Add-on id | kv_trendyol |
| Function prefix | fn_kv_trendyol_ |
| Language variables | kv_trendyol.* |
| CSS scope | .kv-trendyol |
| PHP namespace | Tygh\Addons\KvTrendyol |
| Preset | marketplace (generated by kv new --kind integration), extended with the Marketplace Hub |
Structure
Section titled “Structure”The add-on has three layers. Only the last one knows Trendyol.
| Layer | Classes | Role |
|---|---|---|
| Base | Client\BaseClient, Accounts, Secret, Config, Access, Queue, Jobs, Log, Webhook |
HTTP (cURL, TLS verification, timeouts), encrypted credentials per company, settings, job queue (back-off 5 min / 15 min / 1 h / 3 h / 12 h), log with masking and CSV |
Marketplace Hub (Hub\) |
DriverInterface, Hub, Options, Rules, StatusMap, Cache, Categories, Listings, ProductMap, ProductSync, Orders, Shipments, Returns |
Channel independent: category and attribute mapping, price rules and stock buffer, listing builder, product and batch sync, order import with buyer and address mapping, status mapping, shipment steps, returns, per item errors. It talks to the channel only through DriverInterface with normalized arrays (documented in the interface file) |
Driver (Drivers\Trendyol\, Client\Api) |
Driver, Mapper, Api |
Api = HTTP calls (Basic auth, User-Agent, endpoints), Mapper = pure translation (unit tested with samples), Driver = the DriverInterface implementation. Hub\Hub::DRIVER names it |
A second channel (Hepsiburada, N11 …) is a new add-on built from the same hub with its own Api, Mapper and Driver.
Trendyol API calls used
Section titled “Trendyol API calls used”| Purpose | Call |
|---|---|
| Connection test | GET /integration/product/sellers/{id}/products/approved |
| Categories, attributes, values, brands | GET /integration/product/product-categories, …/categories/{id}/attributes, …/attributes/{aid}/values, …/brands/by-name |
| Create products | POST /integration/product/sellers/{id}/v2/products (returns batchRequestId) |
| Stock and price | POST /integration/inventory/sellers/{id}/products/price-and-inventory (returns batchRequestId) |
| Batch result | GET /integration/product/sellers/{id}/products/batch-requests/{batchId} |
| Orders | GET /integration/order/sellers/{id}/v2/orders (paged, 200 per page, two week window) |
| Picking / Invoiced | PUT /integration/order/sellers/{id}/shipment-packages/{package} |
| Own carrier tracking | PUT …/shipment-packages/{package}/alternative-delivery |
| Cannot supply | PUT …/shipment-packages/{package}/items/unsupplied |
| Returns | GET …/claims, PUT …/claims/{claim}/items/approve |
| Webhook | POST /integration/webhook/sellers/{id}/webhooks (API_KEY authentication) |
Every request carries Authorization: Basic and User-Agent: <supplierId> - <integrator>. Limits: 50 requests per 10 seconds per endpoint (429 is retried by the queue), batches of at most 1000 items.
Database tables
Section titled “Database tables”| Table | Purpose |
|---|---|
?:kv_trendyol_accounts |
Credentials per company (secrets sealed), last connection check |
?:kv_trendyol_log, ?:kv_trendyol_jobs |
Log, queue |
?:kv_trendyol_product_map |
Product mapping: barcode, listing state (N / P / Y), dirty flags, last pushed values, error |
?:kv_trendyol_order_map |
Imported orders, channel status, steps pushed, import error and retry time |
?:kv_trendyol_options |
Rules per account |
?:kv_trendyol_category_map, ?:kv_trendyol_attr_map |
Category mapping with price rule, attribute mapping |
?:kv_trendyol_cache |
Cached reference data (categories, attributes, values, brands) |
?:kv_trendyol_batches |
Asynchronous batch requests waiting for their per item result |
?:kv_trendyol_returns |
Claims |
Hooks used
Section titled “Hooks used”PHP hooks: update_product_post (marks the mapped product for the next sync) and delete_product_post (removes its mapping). Template hooks: index:styles (admin styles). The pages come from the add-on’s own controller (kv_trendyol) and the menu schema.
Test the HTTP layer without Trendyol
Section titled “Test the HTTP layer without Trendyol”The base URL can be overridden for tests in config.local.php (development only):
$config['kv_trendyol_base_url'] = 'http://127.0.0.1:11830';tests/mock-server/server.js follows the documented API (Basic auth, User-Agent rule, batches, packages, claims); tests/unit.php covers the mapping with samples shaped like the documentation; tests/e2e/e2e.mjs drives a whole store against the mock.