Make your first call to the E-commerce API
The E-commerce API lets your own tools fill the shop you run with Ultineo E-commerce and read it back. This guide goes from the health check to one answered call, and shows how to read the answer.
What you need before the first call
- A key for your shop
The key starts with sk-project- and holds the scopes of the resources you call, for reading, for writing or for both. An administrator of the project creates it in the workspace, on the "API Access" tab.
- A tool that sends requests
You need a way to send an HTTP request with a JSON body, such as curl. The reference gives a complete curl example.
- The HTTPS address
Every request goes to https://api.ultineo.com/v1/. Only HTTPS is served.
From the health check to an answered call
-
1
Check that the host answers Call https://api.ultineo.com/health, the one endpoint that needs no key. An answer with the code 200 and the title OK shows that the host is reachable.
-
2
Authenticate with your key Send the key as a Bearer token in the Authorization header of every call. Add the Content-Type header application/json only when you send a body.
-
3
Read one record back Start with a read: a GET on the import path of a resource reads back one record, named by its key or by its identifier. The example of the reference reads one category by its name, on /v1/category/import.
-
4
Read the status, then response The answer is one envelope of three keys: code, title and response. Read the HTTP status code first, then response, which holds the record when the read succeeded.
-
5
Prepare a first import Every import follows the same POST contract, whatever the resource. The guide "Import in batches" describes this contract.
One request and its answer
This request reads back one category of the shop by its name. The answer is the envelope every endpoint returns.
Request
curl "https://api.ultineo.com/v1/category/import?name=Smartphones" \
-H "Authorization: Bearer sk-project-YOUR_KEY" The key travels in the Authorization header, after the word Bearer.
Answer
{
"code": 200,
"title": "OK",
"response": {
"object": "category",
"id": "cate_4be1a07f93c2d58e6a10",
"name": "Smartphones",
...
"status": "activated",
...
"created_at": 1789143990,
"updated_at": 1789143990
}
} The envelope holds code, title and response, and here response holds the category.
What to watch on a first call
- A request over plain HTTP
A request on http:// is answered with a 301 redirect to the same path on https://, and by then the key in its header has travelled in plaintext. Always call the https:// address directly rather than relying on the redirect.
- A refused key
A key that is disabled or expired is refused, and so is a call whose key lacks the scope it needs. Read the message in response, then the guide "Handle errors and limits", which says what each status asks of your client.
- A read naming no record
A read that gives neither the key of the record nor its identifier is answered with 400: the read parameter is missing. The reference article of each resource lists its read parameters.
The articles behind this page
This page restates the following articles of the help center. They hold every field, every value and every answer.
Product pages to read next
- API access
Connect your systems through scoped shop access
- Products
Product records, images and categories
- Import & export
Make bulk catalogue changes with a readable result
Continue in this section
- Manage keys and access
Who creates a key, what it may reach, when it expires and how to rename, disable or delete it.
- Import in batches
The contract every import shares: batches, the dry run, replays without duplicates and the report.
- Handle errors and limits
What each status of the API asks of your client, and what you can safely send again.
- Connect an ERP or a supplier feed
A typical connection from another system: the keys to map, a first dry run, the sync and its checks.
- Move an existing shop
Bring your catalogue, your sales history and your domain to a new shop, and check each step.
- AI inside your software
A reasoning step added to a screen of your own software, launched through the API and read back.
Your key is created inside an open shop
Ultineo E-commerce accounts are opened after a review: send your application, and our team replies by e-mail.
Questions
No record of your shop matches the key or the identifier you read: check the spelling of the record’s own reference, such as the category name in the example. A record of another shop answers the same way. When the path itself does not exist, check it against the endpoint tables of the API reference.
Yes, for imports: a batch sent with dry_run set to true is checked in full and nothing is written. The guide "Import in batches" shows the request and how to read its report.
Do not assume that. The article "Your first API call" lists every resource with its scopes, and the page "Catalogue, orders and vouchers" says what a program sends and reads back for each; parcels, addresses and carriers are the API of Ultineo Logistics.
It is in the E-commerce help center, in the section on the E-commerce API. It is public and written in English and in French. You need no account to read it.