Open API endpoints and limits

Before you start

You need Open API access before any call works: a client that e-tailize approved, and the key and secret that belong to it.

Version 1 of the API sits under https://app.e-tailize.eu/public/api/v1 and holds 17 endpoints in three areas: Auth, Connections and Products. The full list, with the fields of every call, is on the Swagger page at https://app.e-tailize.eu/swagger/index.html.

The API speaks JSON only, and it hands you an error as application/problem+json.

Steps

1. Pick the area your call belongs to. Auth requests access and generates, validates and revokes a key. Connections holds the catalogue of what you can connect, your connections, orders, shipments and forwarding targets. Products holds your products and their stock.
2. Set the credential headers of that area: X-Api-ClientId on Auth, and X-Api-Key plus X-Api-Secret on Connections and Products, where both are required. The first access request is the exception, it carries no header at all.
3. Send Accept: */* on every call. A client that accepts application/json only gets a 406 back instead of the error it needs to read.
4. Call GET /Connections/definitions before you create a connection. It returns the fields each marketplace asks for, and the names in connectionFields are case sensitive, so copy them exactly.
5. Match your own SKUs to the e-tailize product ids with GET /Products. It answers with a page object, so you page through the result.
6. Update one stock level with PUT /Products/{id}/stock and a body that carries the new stock, for example 25 pieces. Read succeeded in the response, because data is always false, on a successful call too.
7. Keep every route inside its own budget: Auth and Connections 10 requests per 60 seconds, GET /Products 30 per 60 seconds, PUT /Products/{id}/stock 25 per 10 seconds. The count runs per route, per IP address and per key, and it does not drain gradually: each call restarts the clock of that period. The Retry-After header says how long that period still has to run.
8. Wait out the whole period when a call answers 429 with the title "Too many requests." and, under errors.general, the message "Rate limit exceeded. Try again in 60 seconds.", where the number matches the period of that route. Wait the seconds the Retry-After header names, a plain number of seconds and the only header the limiter adds. Trying again earlier only restarts the clock.

What happens next

What you send in is normal platform data. A connection you post shows up on the "API connections" page like any other one, and a stock update follows the forwarding rules of that connection, the rules you read back with GET /Connections/mutation-propagation-targets.

Those rules decide the direction: stock goes from you to the marketplace, orders come from the marketplace to you, and track and trace goes out per connection, or per despatch with POST /Connections/{id}/shipment.

Common problems

A call that leaves out the key header answers 400, not 401. The title is "One or more validation errors occurred." and errors.general says what is wrong: "X-Api-Key header is missing." for a missing key, "X-Api-Secret header is missing." for a blank secret, and "Invalid X-Api-Key header value." for a key that is not a GUID. The message always sits under errors.general, never in a detail field.

A 401 means the header is there and well formed, but not accepted: the client is not approved yet, the key or the secret is wrong, or the key expired.

A connection id that is not yours answers 404, the same as an id that does not exist, so the answer never confirms which ids exist.

A POST /Connections that fails validation, a duplicate connection name for example, can come back as a 500. Read the message in that body, it names the real cause.

FAQ

Where do I find every endpoint and its fields?

On the Swagger page at https://app.e-tailize.eu/swagger/index.html, with the parameters and the responses of all 17 endpoints. Check a real response before you rely on the shape of an error body, so your client follows the live behaviour.

Can I have two API keys at the same time?

No. Generating refuses a second active key for the same user. Rotating means revoking the key you have first, and generating a new one after that.

Is an order id unique?

Only inside one marketplace. Two marketplaces can hand you the same order id, so key your own records on the connection definition together with the order id, never on the id alone.

Related

• Open API access and keys
• Forward orders and keep track and trace flowing
• Synchronise stock to your marketplaces
• Edit, resave or delete a connection