Technical reference for developers who customize Allegro Marketplace Connector.
| Item |
Value |
| Add-on id |
kv_allegro |
| Function prefix |
fn_kv_allegro_ |
| Language variables |
kv_allegro.* |
| CSS scope |
.kv-allegro |
| PHP namespace |
Tygh\Addons\KvAllegro |
| Preset |
marketplace (Marketplace Hub, generated by kv new --kind integration --class marketplace) |
| Class |
Role |
Hub\* |
Channel independent layer: category and parameter mapping, price rules, listing builder, product sync, order import, status map, shipments, returns. Talks to the channel only through Hub\DriverInterface |
Drivers\Allegro\Driver |
Implements the interface: category crawl, offer creation and read-back, price and quantity commands, checkout forms, fulfillment, shipments, customer returns, refunds |
Drivers\Allegro\Mapper |
Pure translation (offer body, checkout form to order, return to claim, refund bodies, statuses). Unit tested with samples built from the Allegro OpenAPI specification |
Client\Api |
The HTTP calls of the Allegro REST API: versioned media type application/vnd.allegro.public.v1+json, device flow and authorization code flow, refresh with rotation, image upload host |
Client\BaseClient |
cURL with TLS verification and timeouts, JSON, error mapping (ApiException::retryable for 408, 425, 429 and 5xx), masked logging, one repeat after a 401 |
Accounts, Secret |
Credentials and the token record sealed with AES-256-GCM; one account per store owner or per vendor |
Queue, Jobs |
Job queue: back-off 5 min / 15 min / 1 h / 3 h / 12 h, per-job isolation, overlap lock |
Log |
Event log with masking, filters, CSV, retention |
| Purpose |
Call |
| Authorization |
POST /auth/oauth/device, POST /auth/oauth/token (device code, authorization code, refresh token), GET /auth/oauth/authorize |
| Connection test |
GET /me |
| Reference data |
GET /sale/categories, GET /sale/categories/{id}/parameters |
| Catalogue match |
GET /sale/products?phrase=<EAN>&mode=GTIN |
| Images |
POST /sale/images (upload host) |
| Offers |
POST /sale/product-offers, GET /sale/product-offers/{id}, GET /sale/product-offers/{id}/operations/{operationId}, GET /sale/offers?external.id= |
| Stock and price |
PUT /sale/offer-quantity-change-commands/{uuid}, PUT /sale/offer-price-change-commands/{uuid} and their reports |
| Orders |
GET /order/checkout-forms, GET /order/checkout-forms/{id}, PUT /order/checkout-forms/{id}/fulfillment, POST /order/checkout-forms/{id}/shipments, GET /order/carriers |
| Returns and refunds |
GET /order/customer-returns, POST /payments/refunds |
| Table |
Purpose |
?:kv_allegro_accounts |
Credentials per company (secrets sealed), authorization record (token cache, sealed), last connection check |
?:kv_allegro_log, ?:kv_allegro_jobs |
Log and queue |
?:kv_allegro_product_map, ?:kv_allegro_order_map, ?:kv_allegro_returns |
Product mapping, imported orders, returns |
?:kv_allegro_category_map, ?:kv_allegro_attr_map, ?:kv_allegro_options |
Category and parameter mapping, rules |
?:kv_allegro_cache, ?:kv_allegro_batches |
Reference data, offer ids, batch states; batches awaiting their result |
See init.php and design/backend/templates/addons/kv_allegro/hooks/: product and order hooks mark mapped products dirty and report shipments; the admin pages are added to the Orders menu.
php81 tests/unit.php, node tests/mock-server/server.js 11830 and node tests/e2e/e2e.mjs (needs $config['kv_allegro_base_url'] in config.local.php). The mock follows the Allegro OpenAPI specification; it proves the add-on against the documented shapes, not against the real Allegro.
