Developer overview - Omnilinker

Omnilinker has a REST API at https://omnilinker.pl/api/. It is the same API the web app uses, so most of what you can do on a screen you can also do from a script, a middleware such as n8n or Make, or your own service. Every request is authenticated with an API key that acts as the person who created it.

What you can integrate today

You want to	Use
Read or change catalog, prices, orders, stock, shipments and contacts	The REST API, with an API key
React when orders change	The order journal feed; see Webhooks and change feeds
Add or remove stock in bulk from a spreadsheet	The stock import; see File formats
Load products and prices from a spreadsheet	The Catalog imports; see Importing products, prices and images
Take data out as Excel or CSV	The exports; see File formats

Not available yet:

Outbound webhooks. Omnilinker does not call your endpoint when something changes. Poll the order journal instead; see Webhooks and change feeds.
OAuth clients for your own apps. You cannot register an OAuth or OpenID Connect client in Omnilinker. Use an API key; see Authentication.
Client libraries. There is no official SDK. Generate a client from the OpenAPI document if you need one; see API reference.

API reference

The reference lists every endpoint with its parameters and response schema:

What	Where
Swagger UI	`https://omnilinker.pl/swagger`
ReDoc	`https://omnilinker.pl/api-docs`
OpenAPI document (JSON)	`https://omnilinker.pl/swagger/v1/swagger.json`

On the API keys page, the API reference button opens the Swagger UI. The reference describes the whole API, including endpoints an API key cannot use (managing users, roles, settings and keys). What a key can do explains which.

Make your first request

Create an API key

In Omnilinker, open API keys and click New API key. Pick what will use the key, give it a name and click Create key. Copy the key when it is shown: it is shown once. See Get a key.

Check the key

Call GET /api/api-key-management/whoami with the key in the X-Api-Key header:

curl https://omnilinker.pl/api/api-key-management/whoami \
  -H "X-Api-Key: $OMNILINKER_API_KEY"

The answer names the key, the person it acts as, your organization and the permissions the key really has. If grantedPermissions is empty, the key can do nothing yet.

Call an endpoint

For example, list the latest orders (the key needs the Orders permission):

curl "https://omnilinker.pl/api/ordering/order?MaxResultCount=20" \
  -H "X-Api-Key: $OMNILINKER_API_KEY"

Call the API from a server or a script, not from code that runs in a web browser: anyone who can open the page can read a key placed there.

API areas

Each module has its own route prefix. The table lists the areas an integration is most likely to use; the reference lists them all.

Route prefix	Module	Read more
`/api/catalog/`	Products, brands, categories, tags, price levels	Products
`/api/pricing-intelligence/`	Offers, merchants, price history, product overview, repricer	Pricing Intelligence
`/api/ordering/`	Orders, order statuses and sources, extra fields, order journal	Orders
`/api/contacts/`	Customers and their order statistics	Contacts
`/api/inventory/`	Warehouses, stock levels, stock movements, stock import	Stock levels and movements
`/api/shipping/`	Shipments, labels and tracking	Shipments
`/api/marketplaces/`	Allegro and OLX accounts and listings	Create listings
`/api/automation/`	Custom triggers and automation runs	Custom triggers
`/api/devices/`, `/api/printing/`	Stations, printers and print jobs	Print jobs
`/api/fiscal/`	Fiscal receipts	Fiscal receipts
`/api/erp-integration/`	ERP connections and commands	ERP integration

The endpoints of a module that is not enabled for your organization answer 403 Forbidden. Which modules you have depends on your plan; see Modules and feature availability.

Conventions

Requests and responses

Request and response bodies are JSON. Property names are camelCase: totalCount, items, orderId.
Enumerations are sent and returned as numbers. The reference lists the numbers each one takes.
Ids are GUIDs, except where the reference says otherwise (for example the order journal’s id, a number).
Times are returned in UTC, in ISO 8601. Send times in UTC too, with a Z or an offset, so they are not read in another time zone.
A product’s dimensions and weight are in the product’s own unit, in a response and in a request alike: a box 15 cm high reads "height": 15 with the centimetre unit, and sending that back keeps it 15 cm. Despite its name, weight.amountInGrams is the amount in weight.unit. They are sent rounded to 15 significant digits, so a value sent back unchanged, even through a double, keeps the stored amount exactly.
Endpoints that return a file (an export, an import template) answer with the file itself, not with JSON.

Lists and paging

List endpoints take three query parameters:

Parameter	Meaning
`SkipCount`	How many items to skip. Default `0`.
`MaxResultCount`	How many items to return. Default `10`, at most `1000` unless the reference says less.
`Sorting`	A sort expression, where the endpoint supports one, for example a field name followed by `asc` or `desc`.

A paged list answers with the total and one page:

{
  "totalCount": 1284,
  "items": [ ]
}

Page through by raising SkipCount by MaxResultCount until you have totalCount items. Some endpoints have their own paging, such as the order journal’s cursor; their reference entry says so.

Your organization

A key belongs to one organization, and every call made with it reads and writes that organization’s data only. You do not send a tenant header or a tenant id: the key decides. To work with two organizations, use one key from each.

Creating orders safely

When you create an order with POST /api/ordering/order, send an Idempotency-Key header with a value that is unique to that order in your system, up to 128 characters. If the call times out and you send it again with the same value, Omnilinker returns the order it already created instead of creating a second one. You can also send the value as idempotencyKey in the body; the body wins when both are present.

Errors

When a call fails, the body describes the error in one shape, whatever the endpoint:

{
  "error": {
    "code": "Inventory:NegativeStockNotAllowed",
    "message": "A readable description of what went wrong.",
    "details": null,
    "data": { },
    "validationErrors": null
  }
}

code identifies the error. It is present when the error has one; base your handling on it rather than on the message.
message is meant for people, and follows the request’s language: send Accept-Language: pl-PL for Polish or Accept-Language: en for English.
validationErrors lists each invalid field, as message and members (the field names), when the request did not pass validation.
data carries values that belong to the error, such as the limit that was exceeded.

The status code tells you what kind of failure it is:

Status	Meaning
`400 Bad Request`	The request did not pass validation. See `validationErrors`.
`401 Unauthorized`	No key was sent, or the key is not valid: unknown, expired, deactivated, deleted, replaced, or its owner can no longer sign in.
`403 Forbidden`	The key is valid but may not do this: it lacks the permission, the permission is one keys can never hold, or the module is not enabled for your organization. Many business rules are also refused with `403` and a `code`.
`404 Not Found`	The record does not exist, or not in your organization.
`409 Conflict`	Someone changed the record since you read it, or the change conflicts with its current state. Read it again and retry.
`500 Internal Server Error`	An unexpected error. Retry later; if it persists, contact support with the time of the call.

Omnilinker does not limit how many requests an API key makes today.

Authentication

Send the key, test it, and see what it can do.

Webhooks and change feeds

Follow order changes with the order journal.

File formats

Columns for the stock import and the exports.

API keys

Create, rotate and revoke keys.

​What you can integrate today

​API reference

​Make your first request

​API areas

​Conventions

​Requests and responses

​Lists and paging

​Your organization

​Creating orders safely

​Errors