Technical reference for developers who customize Mercado Libre Marketplace Connector.
| Item |
Value |
| Add-on id |
kv_mercadolibre |
| Function prefix |
fn_kv_mercadolibre_ |
| Language variables |
kv_mercadolibre.* |
| CSS scope |
.kv-mercadolibre |
| PHP namespace |
Tygh\Addons\KvMercadolibre |
| Preset |
marketplace (Marketplace Hub, generated by kv new --kind integration --class marketplace) |
| Class |
Role |
Hub\* |
Channel independent layer: category and attribute mapping, price rules, listing builder, product sync, order import, status map, shipments. Talks to the channel only through Hub\DriverInterface |
Drivers\MercadoLibre\Driver |
Implements the interface: category crawl and predictor, item creation (with the description as a second call) and read-back, stock and price updates, order search and read, shipments, labels, notification handling |
Drivers\MercadoLibre\Mapper |
Pure translation (item body, GTIN rules, attributes by value id, order and shipment to the hub order, statuses). Unit tested with samples that follow the documented response shapes |
Client\Api |
The HTTP calls of the Mercado Libre API: authorization code flow per site host, refresh with single-use rotation (a parallel refresh is detected), x-format-new for shipments, error body with the cause list |
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 |
Webhook |
Notification check: private key derived from the cron key, topic list, resource format, seller id |
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; the webhook job reads the resource named by a notification |
Log |
Event log with masking, filters, CSV, retention |
| Purpose |
Call |
| Authorization |
GET https://auth.<site host>/authorization (browser), POST /oauth/token (authorization_code, refresh_token, form encoded) |
| Connection test |
GET /users/me |
| Reference data |
GET /sites/{site}/categories, GET /categories/{id}, GET /categories/{id}/attributes, GET /sites/{site}/domain_discovery/search (predictor) |
| Items |
POST /items, POST and PUT /items/{id}/description, GET /items/{id}, PUT /items/{id} (available_quantity, price), GET /users/{id}/items/search?seller_sku= |
| Orders |
GET /orders/search (order.date_last_updated.from), GET /orders/{id} |
| Shipments |
GET /shipments/{id} (header x-format-new: true), GET /shipments/{id}/orders (header X-New-Domain: true), PUT /shipments/{id} (custom shipping), GET /shipment_labels |
| Notifications |
inbound POST to the add-on (topics orders_v2, items, shipments) |
- There is no sandbox: both modes call
https://api.mercadolibre.com; $config['kv_mercadolibre_base_url'] in config.local.php redirects the calls to the mock server (development only).
- The notification carries no signature; the add-on authenticates the address (key in the URL) and never trusts the body: it only names a resource that is then read with the seller’s token.
- The refresh token is valid for 6 months and single use; the token record is replaced in the same step as the refresh.
- The shipment resource and the order resource are changing (new format header,
order_id removed from shipments); the add-on reads the order id from the order and the shipment id from the order.
| Table |
Purpose |
?:kv_mercadolibre_accounts |
Credentials per company (secrets sealed), authorization record (token cache, sealed), last connection check |
?:kv_mercadolibre_log, ?:kv_mercadolibre_jobs |
Log and queue |
?:kv_mercadolibre_product_map, ?:kv_mercadolibre_order_map, ?:kv_mercadolibre_returns |
Product mapping, imported orders, returns (unused by this channel) |
?:kv_mercadolibre_category_map, ?:kv_mercadolibre_attr_map, ?:kv_mercadolibre_options |
Category and attribute mapping, rules |
?:kv_mercadolibre_cache, ?:kv_mercadolibre_batches |
Reference data, item ids, seller id, batch states |
See init.php and design/backend/templates/addons/kv_mercadolibre/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_mercadolibre_base_url'] in config.local.php). The mock follows the documented behaviour (single-use refresh tokens, items without description, x-format-new, label states); it proves the add-on against the documentation, not against the real Mercado Libre.
