Documentation API

API publique v1 — accédez à vos fiches produits générées depuis n'importe quel système : PIM, site e-commerce, ERP, middleware.

Authentification

Créez une clé API dans l'application : menu utilisateur → API & Intégrations → Nouvelle clé. La clé n'est affichée qu'une seule fois. Envoyez-la à chaque requête :

curl https://synqio.io/api/v1/listings \
  -H "Authorization: Bearer sk_synqio_VOTRE_CLE"

# ou avec l'en-tête alternatif :
curl https://synqio.io/api/v1/listings -H "X-Api-Key: sk_synqio_VOTRE_CLE"

Limite : 600 requêtes / heure par compte. Maximum 5 clés actives ; révoquez une clé à tout moment depuis l'application.

Endpoints

GET/listings

La dernière version de chacune de vos fiches générées, avec les URLs des visuels IA.

{
  "total": 42, "count": 2, "offset": 0,
  "listings": [{
    "sku": "UHU-SCOTCH-01",
    "title": "UHU Ruban Adhésif Transparent 33m x 19mm",
    "item_highlights": "Adhésif invisible longue durée…",
    "bullet_points": ["ADHÉSION FORTE — …", "…"],
    "description": "<b>Le ruban adhésif UHU</b>…",
    "backend_keywords": "scotch ruban adhesif…",
    "brand": "UHU", "category": "Fournitures de bureau",
    "price": 3.49, "ean": "4026700567892",
    "seo_score": 87, "marketplace": "amazon_fr",
    "batch_id": "…", "generated_at": "2026-07-24 10:12:00",
    "images": [
      {"slot": "hero", "url": "https://…/gen_UHU-SCOTCH-01_hero.png"},
      {"slot": "lifestyle_1", "url": "https://…"}
    ]
  }]
}

GET/listings/{sku}

Une fiche précise par SKU (404 si inconnue).

GET/batches

L'historique de vos lots de génération (id, date, marché, nombre de produits, score SEO moyen).

GET/batches/{batch_id}

Un lot complet avec toutes ses fiches.

Webhooks

Recevez vos fiches automatiquement : SynqIO appelle votre URL en POST à chaque génération terminée. Gérez vos webhooks depuis l'application ou par API :

POST/webhooks

curl -X POST https://synqio.io/api/v1/webhooks \
  -H "Authorization: Bearer sk_synqio_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://votre-site.com/webhooks/synqio"}'

# Réponse — conservez le secret, il n'est affiché qu'une fois :
# {"id": "wh_…", "secret": "whsec_…", "events": ["listing.generated"]}

GET/webhooks  ·  DELETE/webhooks/{id}

Lister / supprimer vos webhooks (maximum 10 par compte).

Événement listing.generated

POST https://votre-site.com/webhooks/synqio
X-Synqio-Event: listing.generated
X-Synqio-Signature: sha256=3f7a…
X-Synqio-Webhook-Id: wh_…

{
  "event": "listing.generated",
  "batch_id": "…",
  "marketplace": "amazon_fr",
  "product_count": 12,
  "listings": [ { …fiches complètes… } ]
}

Vérifier la signature

Chaque livraison est signée HMAC-SHA256 avec le secret du webhook. Vérifiez-la avant de traiter le contenu :

# Python
import hmac, hashlib
expected = "sha256=" + hmac.new(SECRET.encode(), raw_body, hashlib.sha256).hexdigest()
valid = hmac.compare_digest(expected, request.headers["X-Synqio-Signature"])

// Node.js
const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex");
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers["x-synqio-signature"]));

En cas d'échec (erreur réseau ou 5xx), une nouvelle tentative unique a lieu après 3 secondes. Répondez 2xx rapidement (traitez en asynchrone si besoin).

Flux automatiques (pull)

Pour les consommateurs qui tirent un fichier à intervalle régulier (Google Merchant Center, jobs de synchronisation PIM, sites), SynqIO fournit des URLs de flux permanentes — aucune clé ni en-tête requis, le jeton dans l'URL fait office d'authentification. Récupérez vos URLs dans API & Intégrations → Flux automatiques.

GET https://synqio.io/api/feed/{jeton}/{canal}

# Canaux : google-merchant · shopify · woocommerce · prestashop · akeneo · pim
# Filtre optionnel : ?marketplace=amazon_fr

# Exemple — flux Google Merchant Center à coller dans
# Merchant Center → Produits → Flux → Ajouter un flux (récupération planifiée) :
https://synqio.io/api/feed/feed_VOTRE_JETON/google-merchant

Le contenu est toujours la dernière version de chaque fiche (même source que /api/v1/listings). Le jeton est révocable : « Régénérer l'URL » dans l'application invalide immédiatement les anciennes URLs. Limite : 120 requêtes/heure par flux.

Exports fichiers

Besoin d'un fichier ponctuel plutôt que d'une API ou d'un flux ? L'application exporte aussi vos fiches aux formats PIM universel (Excel), Shopify, WooCommerce, PrestaShop, Akeneo et Google Shopping — menu Exports après génération.

Codes d'erreur

Une question, un besoin d'intégration spécifique (connecteur PIM, flux personnalisé) ? Écrivez-nous : hello@solutionstmf.com