Developer notes

Technical reference for developers who customize Hepsiburada Marketplace Connector.

Add-on identity

Item	Value
Add-on id	kv_hepsiburada
Function prefix	fn_kv_hepsiburada_
Language variables	kv_hepsiburada.*
CSS scope	.kv-hepsiburada
PHP namespace	Tygh\Addons\KvHepsiburada
Preset	marketplace (generated by kv new --kind integration), extended with the Marketplace Hub

Structure

The add-on has three layers. Only the last one knows Hepsiburada.

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\Hepsiburada\, 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 (N11, Allegro …) is a new add-on built from the same hub with its own Api, Mapper and Driver.

Hepsiburada API calls used

Hosts per service (test = the same name with -sit): listing-external (listings), oms-external (orders, packages, claims), mpop (catalog), shipping-external (cargo companies). The mock server answers all of them on one port.

Purpose	Call
Connection test	GET /listings/merchantid/{id}?offset=0&limit=1 (listing)
Categories, attributes, values	GET /product/api/categories/get-all-categories, …/categories/{id}/attributes, …/categories/{id}/attribute/{aid}/values (mpop)
Import products	POST /product/api/products/import (multipart JSON file, returns a tracking id)
Import status	GET /product/api/products/status/{trackingId}
Stock and price	POST /listings/merchantid/{id}/inventory-uploads (returns an upload id), GET …/inventory-uploads/id/{uploadId}
Orders	GET /orders/merchantid/{id} and …/cancelled (order lines, offset + limit, begindate / enddate)
Packages	GET /packages/merchantid/{id}/shipped, …/delivered, …/undelivered
Packing (“picking”)	POST /packages/merchantid/{id} (lineItemRequests)
Invoice link	PUT /packages/merchantid/{id}/packagenumber/{pn}/invoice
Own carrier tracking	POST /packages/merchantid/{id}/packagenumber/{pn}/intransit
Cancel lines	POST /lineitems/merchantid/{id}/id/{lineId}/cancelbymerchant
Claims	GET /claims/merchantid/{id}, POST /claims/number/{n}/accept
Cargo companies	GET /cargoFirms/{id} (shipping)

Every request carries Authorization: Basic (API user and password) and User-Agent: <integrator name>. The endpoints, field names and wire shapes were taken from the Hepsiburada developer portal as published through its OpenAPI documents and the SIT recordings of an open-source client; tests/mock-server/server.js encodes exactly what the add-on relies on. Hepsiburada publishes no per-endpoint rate limit that the add-on depends on: a 429 answer is retried by the queue; batches are kept at 100 items.

Database tables

Table	Purpose
?:kv_hepsiburada_accounts	Credentials per company (secrets sealed), last connection check
?:kv_hepsiburada_log, ?:kv_hepsiburada_jobs	Log, queue
?:kv_hepsiburada_product_map	Product mapping: merchant SKU, listing state (N / P / Y), dirty flags, last pushed values, error
?:kv_hepsiburada_order_map	Imported orders, channel status, steps pushed, import error and retry time; the lines column keeps line id, SKU, quantity and the package number
?:kv_hepsiburada_options	Rules per account
?:kv_hepsiburada_category_map, ?:kv_hepsiburada_attr_map	Category mapping with price rule, attribute mapping
?:kv_hepsiburada_cache	Cached reference data (categories, attributes, values, brands)
?:kv_hepsiburada_batches	Import tracking ids (p: prefix) and inventory upload ids (i: prefix) waiting for their per item result
?:kv_hepsiburada_returns	Claims

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_hepsiburada) and the menu schema. The storefront controller serves kv_hepsiburada.invoice, a page signed per order that prints the CS-Cart invoice as HTML for Hepsiburada to download.

Test the HTTP layer without Hepsiburada

The base URL can be overridden for tests in config.local.php (development only):

$config['kv_hepsiburada_base_url'] = 'http://127.0.0.1:11841';

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.