Ingestion API
The ingestion API lets an accredited seller push listings and stocks from their ERP. It goes through the same chain as the file import: same checks, same defaults.
The OpenAPI description of the API, to import into Postman, Insomnia or a Swagger editor: openapi.json, openapi.yaml (OpenAPI 3.1.0)
Authentication
Each call carries the seller's token in the Authorization header. The token files everything it pushes under the seller company that created it.
Authorization: Bearer sqh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Tokens are created and revoked in My Space, Integration, by an administrator of the team.
Try without writing anything
Add dry_run=1 to a write call: the batch is checked as it would be, and the response returns the same report (creations, updates, detailed rejections), but nothing is written, no listing, no stock, no run in the log. Any token allows it: it is the trial token of your first integration.
Create a token in My Space, save the sample batch below as lot.json, then run:
export SQH_TOKEN="sqh_..."
curl -X POST "https://sqhubb.com/api/v1/ingestion/listings?dry_run=1" \
-H "Authorization: Bearer $SQH_TOKEN" -H "Content-Type: application/json" \
--data @lot.json
Rules
- 60 calls per minute and per token; beyond that, a 429 response with the Retry-After header.
- At most 500 items per call.
- The seller reference is mandatory. A reference you already use updates its listing: replaying a call never creates a duplicate.
- A listing created through the API starts as a draft and goes through the marketplace moderation before publication. Only the fields sent are changed.
POST https://sqhubb.com/api/v1/ingestion/listings
Creates or updates listings, in batches.
A sample batch (lot.json): a complete listing, then a price and stock update of a reference already known.
{
"listings": [
{
"reference": "SKU-001",
"title": "Réducteur SEW R97",
"price": 1850,
"currency": "EUR",
"quantity": 3,
"condition": "new_unused",
"incoterm": "EXW",
"brand": "SEW",
"model": "R97",
"origin_country": "DE",
"pickup_country": "FR",
"unit_weight_kg": 120,
"certifications": [
"CE"
],
"price_tiers": [
{
"min_quantity": 2,
"unit_price": 1750
}
],
"images": [
"https://images.example.com/sku-001-face.jpg"
],
"specifications": {
"puissance": "7,5 kW",
"hs_code": "8483.40"
}
},
{
"reference": "SKU-002",
"price": 940,
"quantity": 0
}
]
}
curl -X POST "https://sqhubb.com/api/v1/ingestion/listings" \
-H "Authorization: Bearer $SQH_TOKEN" -H "Content-Type: application/json" \
--data @lot.json
When the marketplace has opened Janus on import, add janus=1: the items become a received Janus import (taxonomy matching, enrichment), which you launch from My Space after seeing its cost.
POST https://sqhubb.com/api/v1/ingestion/listings?janus=1
Item fields
| Field | Type | Description |
|---|---|---|
reference * |
string |
Your reference, mandatory and unique on your side. |
title |
string |
The listing title, mandatory on creation. |
description |
string |
The description, in French. |
summary |
string |
A one-line summary. |
category |
string |
The family: its name or identifier (slug). |
condition |
string |
The condition of the item (values below). |
price |
number |
The unit price excluding tax. |
reference_price |
number |
The reference price (new or market), higher than the price. |
currency |
string |
The currency, EUR by default. |
quantity |
integer |
The available quantity. |
sale_unit |
string |
The sale unit (unit, lot, tonne, kilogram, pallet...). |
lot_size |
integer |
The lot size. |
minimum_order_quantity |
integer |
The minimum order quantity. |
packaging |
string |
The packaging (pallet, wooden_crate, big_bag...). |
incoterm |
string |
The Incoterm 2020 (values below). |
pickup_country |
string |
The pickup country, two-letter ISO code. |
pickup_region |
string |
The pickup region. |
pickup_city |
string |
The pickup city. |
pickup_postal_code |
string |
The pickup postal code. |
origin_country |
string |
The country of origin, two-letter ISO code. |
brand |
string |
The brand. |
model |
string |
The model or manufacturer reference. |
year_of_manufacture |
integer |
The year of manufacture. |
unit_weight_kg |
number |
The unit weight in kilograms. |
length_cm |
integer |
The length in centimetres. |
width_cm |
integer |
The width in centimetres. |
height_cm |
integer |
The height in centimetres. |
seo_title |
string |
The title for search engines. |
seo_description |
string |
The description for search engines. |
certifications |
array |
The list of certifications and labels, for example ["CE", "ISO 9001"]. |
price_tiers |
array |
Volume price tiers excl. VAT, for example [{"min_quantity": 10, "unit_price": 95}]. A tier at or above the base price is discarded. |
images |
array |
The web addresses of the photos (JPEG, PNG or WebP, 10 MB at most), five at most. The first one becomes the main photo. They are downloaded after the listing is saved. |
specifications |
object |
The family specifications, as a key and value object. |
Conditions: new_unused, new_surplus, workshop_checked, audited, good_condition, dismantled_tagged, for_parts. Incoterms: EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DAP, DPU, DDP.
POST https://sqhubb.com/api/v1/ingestion/stocks
Updates the available quantity, and the price when provided, by reference. An unknown reference is rejected, never created.
curl -X POST "https://sqhubb.com/api/v1/ingestion/stocks" \
-H "Authorization: Bearer $SQH_TOKEN" -H "Content-Type: application/json" \
-d '{"stocks":[{"reference":"SKU-001","quantity":2},{"reference":"SKU-002","quantity":5,"price":900}]}'
GET https://sqhubb.com/api/v1/ingestion/listings/:reference
Reads a listing by its reference: status, price, stock, translations.
curl "https://sqhubb.com/api/v1/ingestion/listings/SKU-001" -H "Authorization: Bearer $SQH_TOKEN"
GET https://sqhubb.com/api/v1/ingestion/runs
The last twenty runs, through the API and through the daily synchronisation.
Response
{"run": {"id": 42, "channel": "api", "kind": "listings", "status": "partial",
"received": 2, "created": 1, "updated": 0, "rejected": 1,
"rejections": [{"reference": "SKU-002", "reasons": ["…"]}]}}
In dry run mode, the response also carries "dry_run": true, and the run has no identifier: it is not recorded.
ok: everything went through.partial: part went through, the rejections are detailed.failed: nothing went through.unchanged: the daily feed has not changed, nothing is replayed.janus_received: the Janus import is received, to launch from My Space.
Errors
| HTTP | error | Description |
|---|---|---|
400 | invalid_json | The body is not readable JSON. |
401 | unauthorized | Token missing, invalid or revoked. |
403 | suspended | The seller is suspended on the marketplace: its token no longer publishes until reinstatement. |
403 | closed | The API is not open on this marketplace. |
404 | not_found | No listing of this seller has this reference. |
422 | invalid_payload | Invalid body: no list, empty list, too many items, or janus and dry_run together. |
429 | rate_limited | Too many calls: retry after the delay given by the Retry-After header. |
503 | rate_limiter_unavailable | Rate limiting is temporarily unavailable: retry after the given delay. |
Daily synchronisation
Instead of calling the API, you can declare in My Space the HTTPS address of a CSV or XLSX feed, with the columns of the import template. The marketplace reads it every night, does not replay an unchanged file, and logs every run.