ZIRA-MARKET Product Feed

A read-only HTTP/JSON feed of one supplier's catalogue: products, stock and categories.

Building a WordPress shop? Don't write a client — install the ZIRA-MARKET plugin, which does all of this for you. This page is for everyone else.

Start now, without a token

Send DEVTEST as the token and you get 20 sample products in exactly the real response shape. No account, no supplier, no setup.

curl "http://masa.website/api/feed/products?token=DEVTEST&limit=5"

Authentication

A token is issued by the supplier whose catalogue you want to read. It names exactly one supplier and grants read-only access to that supplier's feed. Send it as a bearer token:

Authorization: Bearer zm1.eyJjIjoi...

A query parameter ?token= also works and is handy in a browser, but prefer the header in production: URLs end up in access logs, proxies and error reports.

Every request also names the supplier, so the server knows which catalogue you mean:

?dataSite=<supplier code>

Endpoints

Method & path	What it returns
GET /api/feed	Handshake: is the token valid, which supplier, what limits.
GET /api/feed/products	A page of the catalogue.
GET /api/feed/stock	SKU and quantity only. Cheap; use this for frequent polling.
GET /api/feed/categories	The supplier's category tree.
POST /api/feed/aimap	Suggests a mapping from the supplier's categories onto yours.

Parameters

Name	Meaning
start	Page index, 0-based — not a row offset. start=2&limit=50 is rows 100-149.
limit	Page size. Capped at 200; a larger value is clamped, not rejected.
category	Filter to one supplier category id.
instock	1 = only rows with stock.
sku	Fetch a single product.
shape	lite (default) or full, which adds description and dimensions.

A product

{
  "success": true,
  "supplier": "artmaroc",
  "count": 1594,          // total rows matching, so you can page to the end
  "page": 0,
  "limit": 50,
  "items": [
    {
      "id": 181292,
      "sku": "92090",
      "title": "מתלה עץ + ווי ברזל",
      "category": 9348,
      "categoryName": "מדפים ופרזול",
      "price": 95,          // the supplier's WHOLESALE price
      "instock": 10,
      "status": "active",   // "inactive" = do not sell, do not delete
      "image": "https://.../181292/photo.jpg"
    }
  ]
}

Rules of the road

These are not suggestions. A client that ignores them gets throttled, and a client that keeps ignoring them gets its token revoked.

1. Use ETags

Every response carries an ETag. Send it back as If-None-Match and an unchanged page answers 304 with no body. This is the single biggest thing you can do for both of us.

curl -H "If-None-Match: \"a1b2c3…\"" \
     "http://masa.website/api/feed/stock?dataSite=CODE&token=TOKEN"
# → HTTP/1.1 304 Not Modified

2. Poll at a sane rate

Stock every few hours, the full catalogue once or twice a day. Nothing in a wholesale catalogue changes fast enough to justify more, and the response is served from a snapshot that only refreshes every few minutes anyway.

3. Honour 429

A 429 carries Retry-After in seconds. Stop until it passes. Retrying immediately spends the rest of your quota on refusals.

Header	Meaning
X-RateLimit-Limit	Requests allowed in the window.
X-RateLimit-Remaining	How many you have left.
Retry-After	Seconds to wait. Sent with a 429.

4. Match on SKU

SKU is the stable identity of a product. Ids are ours and can differ between environments.

Status codes

Code	Meaning	What to do
200	Fine.	—
304	Unchanged since your ETag.	Skip the import. This is a success.
401	Token missing, malformed, expired or revoked.	Ask the supplier for a new one. Do not retry.
403	Valid token, wrong supplier.	Check dataSite. Do not retry.
429	Too many requests.	Wait Retry-After seconds.

Getting a real token

Tokens are issued by the supplier, not by us. Ask them for your supplier code and your token — you need both. They arrive by email along with the plugin download.

Sandbox token DEVTEST · 20 sample rows · no supplier data · try it in your browser