Actualité Ouverture aux acheteurs le 1er décembre. Vendeurs, référencez vos actifs dès maintenant.

Accueil · API d'ingestion

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

ChampTypeDescription
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

HTTPerrorDescription
400invalid_jsonLe corps n'est pas un JSON lisible.
401unauthorizedJeton absent, invalide ou révoqué.
403suspendedLe vendeur est suspendu sur la place : son jeton ne publie plus jusqu'à sa réintégration.
403closedL'API n'est pas ouverte sur cette place.
404not_foundAucune annonce de ce vendeur ne porte cette référence.
422invalid_payloadCorps invalide : pas de liste, liste vide, trop d'articles, ou janus et dry_run ensemble.
429rate_limitedTrop d'appels : réessayez après le délai de l'en-tête Retry-After.
503rate_limiter_unavailableLe 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.