Identification¶

Two things on this page: how your integration names itself to us, and how you point us at one request when you ask for help. Neither is required. Both make a support case much shorter.

The integration label¶

A label says which plugin, module or script sent a try-on. Its form is name/version:

Example	Who sends it
`woocommerce/1.4.0`	The WooCommerce plugin.
`bitrix/0.1.4`	The 1C-Bitrix module.
`widget/1.2.0`	The widget, when you set nothing (`widget/<TryOn.version>`).
`custom/acme-shop`	Your own integration.

Rules for a value:

The name is 1 to 32 characters: lower-case letters and digits first, then lower-case letters, digits, _, . and -.
A /.
The version is 1 to 32 characters from 0-9, A-Z, a-z, ., + and -.
The whole value is at most 64 characters. Spaces around it are trimmed.

The pattern is ^[a-z0-9][a-z0-9_.-]{0,31}/[0-9A-Za-z.+-]{1,32}$.

A bad label is never an error

A value that does not fit - wrong form, too long, not a string - is dropped silently and the request goes ahead as if you had sent nothing. A label can never turn a try-on into a 422. We note in our logs that a value was dropped and why, never the value itself.

How to send it¶

The label travels in one of three places: the JSON body of POST /api/v1/tryon, the X-Ziex-Integration header or the ?integration= query parameter. Pick the one that matches where the call is made.

Where	How	Notes
Browser, through the widget	The `integration` option of `TryOn.init()`; the widget puts it into the body of `POST /api/v1/tryon`	Without the option the widget sends `widget/<TryOn.version>`. See the Widget reference.
Browser, your own code	The `integration` field in the JSON body of `POST /api/v1/tryon`	A body field needs no extra request header.
Your server	The `X-Ziex-Integration` request header on any call	Server-to-server only. See below.
A `GET` without a preflight	The `?integration=` query parameter	For a browser call that must stay a simple request.

{
  "model_image": "data:image/jpeg;base64,...",
  "garment_image": "https://shop.example/images/linen-shirt.jpg",
  "category": "tops",
  "integration": "acme-shop/2.4.1"
}

curl https://api.ziex-tryon.com/api/v1/tryon/jobs \
  -H 'X-API-Key: tryon_YOUR_SECRET_KEY' \
  -H 'User-Agent: acme-shop/2.4.1' \
  -H 'X-Ziex-Integration: acme-shop/2.4.1'

Do not send X-Ziex-Integration from a browser

The header is not on the list of headers our API accepts in a browser preflight. A page that adds it makes its own request fail before it is sent. In a browser use the body field or the widget option.

Which value counts when more than one is present:

On POST /api/v1/tryon: the body field first, then the header. ?integration= is ignored on a POST.
On a GET: the header first, then ?integration=.

Whatever was sent in a valid form is remembered, so you do not need to send it with every call to be seen.

Where the label shows¶

On the job: the label of the request that created it is stored with the job. GET /api/v1/tryon/jobs returns it as integration for each job (null when none was sent or it was dropped). The public status of a single job does not carry it.
On the key: the client portal, on the API Keys page, shows the last label the key was used with ("Last seen") and when. GET /api/v1/tryon/integration returns the same value as key.last_integration.
In our logs and admin tools, which is what we read when you write to us.

A label that changes (for example after you update a plugin) is noted on the key once, at the moment it changes.

Name the request when you ask for help¶

Every answer of the API has an X-Request-ID response header. Quote it when you contact us (see Contact), together with the label, the job id (X-Job-Id or the job_id of the body) and the time. With the request id we find that one request without guessing.

A browser page can read X-Request-ID on the try-on endpoints. Answers produced by the edge in front of the API (413, 429, 502, 503, 504) are not made by the application and carry no request id; for those quote the time and the job id. See Errors.

Your own `User-Agent`¶

From a server, always send your own User-Agent that names your shop and version. Python's default (Python-urllib/3.x) is refused by the edge with an HTML 403 and error 1010. See Quickstart B.