mercaia / module-assistant

dev-main 2026-11-08 21:25 UTC

Requires

• php: >=8.1
• magento/framework: >=103.0.4
• magento/module-catalog: *
• magento/module-checkout: *
• magento/module-configurable-product: *
• magento/module-csp: *
• magento/module-sales: *
• magento/module-store: *

proprietary

Published on Packagist.org on 2026-11-08 21:31 UTC

README

Magento Open Source and Adobe Commerce 2.4.4 – 2.4.8, PHP 8.1+, Luma and Hyvä. It lets Mercaia read the catalog and check orders, and adds the assistant to the storefront with "add to cart".

An independent Composer package: no code shared with apps/api, only the contract below. It can move to its own repository for Marketplace distribution. Why it works this way: ADR-0018.

Install

composer require mercaia/module-assistant   # not published yet: use a path repository or app/code
bin/magento module:enable Mercaia_Assistant
bin/magento setup:upgrade
bin/magento cache:flush

Until it is published, copy this directory to app/code/Mercaia/Assistant.

Then, in the Mercaia dashboard under Stores → Connect, copy the connection code. In Magento, paste it in Stores → Configuration → Mercaia → Assistant, set Enabled to Yes, and flush the config cache. Set it per website or store view if they connect separately.

Contract, version 1

POST {base_url}/mercaia/api/{action}?___store={store_code}, a JSON body, and these headers:

X-Mercaia-Timestamp: 1762628400
X-Mercaia-Signature: sha256=hex(HMAC-SHA256(secret, timestamp + "." + body))

Requests older than 5 minutes, or with a bad signature, get 401. Disabled also means 401.

Action	Body	Answer
status	{}	module: "mercaia", module_version, magento_version, stores[]
products	{"page": 1}	items[], page, pages. A page has 100 products, with one row per sellable SKU
orders	{"order_number","email"}	order or null, the same for a wrong number and a wrong email

A product row: id, sku, group_id (the configurable's SKU), name, description, price, sale_price, currency, availability, url, image, brand, category, gtin, color, size, attributes (what the product page shows). Prices are what a guest sees in this store view.

Add a field: fine. Remove or change one: a new contract version.

In the storefront

window.MercaiaStore.addToCart(sku, qty) returns a promise of true/false. The widget offers it only when one variant is the obvious one, and otherwise links to the product page.