API d'ingestion
L'API d'ingestion permet à un vendeur accrédité de pousser ses annonces et ses stocks depuis son ERP. Elle passe par la même chaîne que l'import de fichier : mêmes contrôles, mêmes valeurs par défaut.
La description OpenAPI de l'API, à importer dans Postman, Insomnia ou un éditeur Swagger : openapi.json, openapi.yaml (OpenAPI 3.1.0)
Authentification
Chaque appel porte le jeton du vendeur dans l'en-tête Authorization. Le jeton range tout ce qu'il pousse sous l'entreprise vendeuse qui l'a créé.
Authorization: Bearer sqh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Les jetons se créent et se révoquent dans Mon espace, Intégration, par un administrateur de l'équipe.
Essayer sans rien écrire
Ajoutez dry_run=1 à un appel d'écriture : le lot est contrôlé comme il le serait, et la réponse rend le même rapport (créations, mises à jour, refus détaillés), mais rien n'est écrit, ni annonce, ni stock, ni passage au journal. Tout jeton le permet : c'est le jeton d'essai du premier branchement.
Créez un jeton dans Mon espace, enregistrez le lot d'exemple ci-dessous dans lot.json, puis lancez :
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
Règles
- 60 appels par minute et par jeton ; au-delà, réponse 429 avec l'en-tête Retry-After.
- 500 articles au plus par appel.
- La référence vendeur est obligatoire. Une référence déjà connue chez vous met à jour son annonce : rejouer un appel ne crée jamais de doublon.
- Une annonce créée par l'API naît en brouillon et passe par la modération de la place avant publication. Seuls les champs envoyés sont modifiés.
POST https://sqhubb.com/api/v1/ingestion/listings
Crée ou met à jour des annonces, par lot.
Un lot d'exemple (lot.json) : une annonce complète, puis la mise à jour du prix et du stock d'une référence déjà connue.
{
"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
Quand la place a ouvert Janus sur import, ajoutez janus=1 : les articles deviennent un import Janus reçu (rattachement à la taxonomie, enrichissement), que vous lancez depuis Mon espace après avoir vu son coût.
POST https://sqhubb.com/api/v1/ingestion/listings?janus=1
Champs d'un article
| Champ | Type | Description |
|---|---|---|
reference * |
string |
Votre référence, obligatoire et unique chez vous. |
title |
string |
Le titre de l'annonce, obligatoire à la création. |
description |
string |
Le descriptif, en français. |
summary |
string |
Un résumé d'une ligne. |
category |
string |
La famille : son nom ou son identifiant (slug). |
condition |
string |
L'état du bien (valeurs ci-dessous). |
price |
number |
Le prix unitaire hors taxes. |
reference_price |
number |
Le prix de référence (neuf ou marché), supérieur au prix. |
currency |
string |
La devise, EUR par défaut. |
quantity |
integer |
La quantité disponible. |
sale_unit |
string |
L'unité de vente (unit, lot, tonne, kilogram, pallet...). |
lot_size |
integer |
La taille du lot. |
minimum_order_quantity |
integer |
La quantité minimale de commande. |
packaging |
string |
Le conditionnement (pallet, wooden_crate, big_bag...). |
incoterm |
string |
L'incoterm 2020 (valeurs ci-dessous). |
pickup_country |
string |
Le pays d'enlèvement, code ISO à deux lettres. |
pickup_region |
string |
La région d'enlèvement. |
pickup_city |
string |
La ville d'enlèvement. |
pickup_postal_code |
string |
Le code postal d'enlèvement. |
origin_country |
string |
Le pays d'origine, code ISO à deux lettres. |
brand |
string |
La marque. |
model |
string |
Le modèle ou la référence constructeur. |
year_of_manufacture |
integer |
L'année de fabrication. |
unit_weight_kg |
number |
Le poids unitaire en kilogrammes. |
length_cm |
integer |
La longueur en centimètres. |
width_cm |
integer |
La largeur en centimètres. |
height_cm |
integer |
La hauteur en centimètres. |
seo_title |
string |
Le titre pour les moteurs de recherche. |
seo_description |
string |
La description pour les moteurs de recherche. |
certifications |
array |
La liste des certifications et labels, par exemple ["CE", "ISO 9001"]. |
price_tiers |
array |
Les paliers de prix dégressifs HT, par exemple [{"min_quantity": 10, "unit_price": 95}]. Un palier au moins égal au prix de base est écarté. |
images |
array |
Les adresses web des photos (JPEG, PNG ou WebP, 10 Mo au plus), cinq au plus. La première devient la photo principale. Elles sont téléchargées après l'enregistrement. |
specifications |
object |
Les caractéristiques de la famille, en objet clé et valeur. |
États : 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
Met à jour la quantité disponible, et le prix s'il est fourni, par référence. Une référence inconnue est refusée, jamais créée.
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
Relit une annonce par sa référence : statut, prix, stock, traductions.
curl "https://sqhubb.com/api/v1/ingestion/listings/SKU-001" -H "Authorization: Bearer $SQH_TOKEN"
GET https://sqhubb.com/api/v1/ingestion/runs
Les vingt derniers passages, par l'API comme par la synchronisation quotidienne.
Réponse
{"run": {"id": 42, "channel": "api", "kind": "listings", "status": "partial",
"received": 2, "created": 1, "updated": 0, "rejected": 1,
"rejections": [{"reference": "SKU-002", "reasons": ["…"]}]}}
En mode à blanc, la réponse porte aussi "dry_run": true, et le passage n'a pas d'identifiant : il n'est pas enregistré.
ok: tout est passé.partial: une partie est passée, les refus sont détaillés.failed: rien n'est passé.unchanged: le flux quotidien n'a pas changé, rien n'est rejoué.janus_received: l'import Janus est reçu, à lancer depuis Mon espace.
Erreurs
| HTTP | error | Description |
|---|---|---|
400 | invalid_json | Le corps n'est pas un JSON lisible. |
401 | unauthorized | Jeton absent, invalide ou révoqué. |
403 | suspended | Le vendeur est suspendu sur la place : son jeton ne publie plus jusqu'à sa réintégration. |
403 | closed | L'API n'est pas ouverte sur cette place. |
404 | not_found | Aucune annonce de ce vendeur ne porte cette référence. |
422 | invalid_payload | Corps invalide : pas de liste, liste vide, trop d'articles, ou janus et dry_run ensemble. |
429 | rate_limited | Trop d'appels : réessayez après le délai de l'en-tête Retry-After. |
503 | rate_limiter_unavailable | Le contrôle du débit est momentanément indisponible : réessayez après le délai indiqué. |
Synchronisation quotidienne
Plutôt qu'appeler l'API, vous pouvez déclarer dans Mon espace l'adresse HTTPS d'un flux CSV ou XLSX, avec les colonnes du modèle d'import. La place le relit chaque nuit, ne rejoue pas un fichier inchangé, et note chaque passage au journal.