API Canaux de vente

Vue d'ensemble

Les canaux de vente sont les plateformes externes où vos produits sont listés et vendus. Kataio connecte 16 plateformes avec un seul contrat : créez le canal, puis appelez POST /channels/{id}/connect. Selon la plateforme, la connexion envoie le marchand vers l'écran de consentement de la plateforme (redirection) ou valide les identifiants auprès de la plateforme et les enregistre (identifiants client / clé API).

• Se connecter et approuver (redirection) — Shopify, WooCommerce, Amazon, eBay, Etsy, TikTok Shop, Mercado Libre, Allegro
• Client ID + secret — Walmart, bol.com, Zalando, OTTO, Cdiscount
• Clé API / jeton — PrestaShop, Magento, Meta

Les identifiants de canal sont des UUID ; les exemples ci-dessous utilisent 3f9d2c1a-7b4e-4c8d-9e2f-1a2b3c4d5e6f.

Lister les canaux

GET https://app.kataio.com/api/v1/channels
Authorization: Bearer {accessToken}

Réponse (200)

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4c8d-9e2f-1a2b3c4d5e6f",
      "name": "Boutique Shopify FR",
      "platform": "SHOPIFY",
      "storeUrl": "https://ma-boutique.myshopify.com",
      "isActive": true,
      "syncFrequency": "HOURLY",
      "lastSyncAt": "2026-09-19T08:00:00.000Z",
      "credentials": {
        "clientId": "a1b2c3d4e5f6",
        "clientSecret": "••••••••"
      },
      "settings": {
        "oauthStatus": "connected"
      },
      "totalProducts": 34,
      "createdAt": "2026-02-20T10:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 8,
    "totalPages": 1
  }
}

Créer un canal

La création enregistre le nom, la plateforme, l'URL de la boutique et les champs dont la plateforme a besoin. Elle ne contacte pas encore la plateforme — c'est le rôle de connect.

POST https://app.kataio.com/api/v1/channels
Authorization: Bearer {accessToken}
Content-Type: application/json

{
  "name": "WooCommerce Europe",
  "platform": "WOOCOMMERCE",
  "storeUrl": "https://shop.example.com",
  "credentials": {
    "consumerKey": "ck_abc123...",
    "consumerSecret": "cs_def456..."
  },
  "syncFrequency": "HOURLY"
}

Plateformes et champs requis

platform prend l'un des codes ci-dessous. « Votre propre application » signifie que le marchand crée une application sur la plateforme et colle ses identifiants ; « application Kataio » signifie qu'il se contente de se connecter — les identifiants d'application sont ceux de Kataio.

Se connecter et approuver — connect renvoie une URL de redirection

• SHOPIFY — storeUrl ; votre propre application Dev Dashboard : clientId, clientSecret
• WOOCOMMERCE — storeUrl ; consumerKey, consumerSecret (facultatifs — laissés vides, connect passe par le flux /wc-auth/v1/authorize de la boutique)
• AMAZON — marketplaceId (sellerId facultatif, rempli lors du consentement) ; application Kataio ; ré-autorisation tous les 365 jours
• EBAY — marketplaceId ; application Kataio
• ETSY — rien à saisir ; application Kataio ; autorisation de 90 jours
• TIKTOK_SHOP — votre propre application Partner Center : appKey, appSecret, serviceId ; region (global ou us). La boutique est découverte après le consentement.
• MERCADO_LIBRE — votre propre application : appId, clientSecret ; siteId (MLA, MLB, MLM…) ; autorisation de 180 jours
• ALLEGRO — votre propre application : clientId, clientSecret ; autorisation de 90 jours

Client ID + secret — validés et enregistrés par connect

• WALMART — clientId, clientSecret
• BOL_COM — clientId, clientSecret
• ZALANDO — clientId, clientSecret, merchantId
• OTTO — clientId, clientSecret
• CDISCOUNT — clientId, clientSecret, sellerId

Clé API / jeton — validés et enregistrés par connect

• PRESTASHOP — storeUrl ; apiKey (idShop facultatif en multi-boutique)
• MAGENTO — storeUrl ; accessToken (storeCode facultatif)
• META — storeUrl ; votre propre application Business : appId, appSecret ; un accessToken d'utilisateur système et le catalogId — ou envoyez le jeton via POST /channels/{id}/meta/token. Catalogue uniquement, pas de commandes. ?mode=oauth sur connect bascule vers Facebook Login.

Connecter un canal

Un seul point d'entrée pour toutes les plateformes. Pas de corps ; les deux paramètres de requête sont facultatifs.

POST https://app.kataio.com/api/v1/channels/{id}/connect?returnTo=onboarding&mode=oauth
Authorization: Bearer {accessToken}

• returnTo — page sur laquelle le navigateur revient après un consentement OAuth (plateformes à redirection uniquement)
• mode — oauth force le flux de redirection, credentials le flux valider-et-enregistrer (utilisé pour le Facebook Login de Meta)

curl -X POST "https://app.kataio.com/api/v1/channels/3f9d2c1a-7b4e-4c8d-9e2f-1a2b3c4d5e6f/connect?returnTo=onboarding" \
  -H "X-API-Key: votre_cle_api"

Réponse (201) — plateformes à redirection

Envoyez le marchand vers authorizationUrl. Kataio reçoit le retour de la plateforme, enregistre les jetons et active le canal.

{
  "status": "redirect",
  "authorizationUrl": "https://my-store.myshopify.com/admin/oauth/authorize?client_id=..."
}

Réponse (201) — plateformes à clé

Les identifiants ont été validés auprès de la plateforme, enregistrés chiffrés, et le canal est actif.

{
  "status": "connected",
  "shopName": "My Store"
}

Erreurs

• 400 — un champ requis manque (« Client ID required »), l'application n'est pas configurée, ou la plateforme a refusé les identifiants
• 404 — canal introuvable

Jeton d'utilisateur système Meta

Pour Meta, la voie recommandée est un jeton d'utilisateur système généré dans les paramètres Business — pas de consentement navigateur, et le jeton peut être configuré pour ne jamais expirer. Le jeton est validé auprès de l'API Graph, puis enregistré chiffré sur le canal.

POST https://app.kataio.com/api/v1/channels/{id}/meta/token
Authorization: Bearer {accessToken}
Content-Type: application/json

{
  "accessToken": "EAAGm0PX4ZCpsBO...",
  "catalogId": "987654321098765",
  "appId": "1234567890123456",
  "appSecret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}

appId et appSecret sont facultatifs et reprennent les valeurs enregistrées sur le canal.

Réponse (201)

{
  "success": true,
  "shopName": "Acme Catalog",
  "message": "Meta system token validated and stored"
}

400 si Graph rejette le jeton ou si le catalogue n'est pas accessible ; 404 si le canal n'existe pas.

Tester la connexion

Validez des identifiants auprès d'une plateforme sans créer ni modifier de canal. Passez channelId pour réutiliser les secrets déjà enregistrés sur un canal existant : tout champ envoyé comme •••••••• ou omis est complété depuis la valeur enregistrée.

POST https://app.kataio.com/api/v1/channels/test-connection
Authorization: Bearer {accessToken}
Content-Type: application/json

{
  "platform": "PRESTASHOP",
  "storeUrl": "https://shop.example.com",
  "credentials": { "apiKey": "••••••••" },
  "channelId": "3f9d2c1a-7b4e-4c8d-9e2f-1a2b3c4d5e6f"
}

Réponse (201)

{
  "success": true,
  "message": "Connected to PrestaShop 8.1.2"
}

Si la plateforme refuse, success vaut false et message en donne la raison.

Mettre à jour un canal

PATCH https://app.kataio.com/api/v1/channels/{id}
Authorization: Bearer {accessToken}
Content-Type: application/json

{
  "name": "Boutique Shopify FR (Principal)",
  "syncFrequency": "EVERY_30MIN"
}

Les identifiants sont masqués

GET /channels et GET /channels/{id} ne renvoient jamais un secret. Les champs secrets de la plateforme (clientSecret, appSecret, apiKey, consumerSecret…) reviennent sous la forme de la sentinelle •••••••• ; les jetons OAuth (accessToken, refreshToken) sont entièrement omis. Tout le reste (clientId, marketplaceId, catalogId, region, authExpiresAt…) est renvoyé tel quel.

PATCH /channels/{id} ignore tout identifiant dont la valeur est la sentinelle : un aller-retour lecture → modification → écriture n'efface donc jamais un secret enregistré :

PATCH https://app.kataio.com/api/v1/channels/{id}
Content-Type: application/json

{
  "credentials": {
    "clientId": "nouveau-client-id",
    "clientSecret": "••••••••"
  }
}
// clientId est mis à jour, clientSecret conserve sa valeur enregistrée

État de la connexion

Une fois un canal connecté, settings.oauthStatus indique où il en est et credentials.authExpiresAt (ISO 8601, null = jamais) quand l'autorisation accordée par la plateforme expire :

• connected — synchronisation normale.
• expiring — l'autorisation expire dans moins de 7 jours (authExpiresAt est aussi recopié dans settings.authExpiresAt). Les synchronisations continuent. Rappelez POST /channels/{id}/connect avant la date pour renouveler sans interruption.
• needs_reauth — la plateforme a révoqué ou laissé expirer l'autorisation ; le canal est déconnecté (isActive: false) et settings.disconnectReason explique pourquoi. Rappelez POST /channels/{id}/connect (ou cliquez sur Reconnecter dans le tableau de bord) et, pour une plateforme à redirection, faites repasser le marchand par l'écran de consentement.

Un balayage quotidien fait passer connected → expiring → needs_reauth à l'approche de la date ; un rafraîchissement refusé par la plateforme (invalid_grant) bascule immédiatement le canal en needs_reauth.

Supprimer un canal

DELETE https://app.kataio.com/api/v1/channels/{id}
Authorization: Bearer {accessToken}

Déclencher une synchronisation

Met en file d'attente un job de synchronisation pour un canal. Le corps est facultatif ; type vaut PUSH_PRODUCTS par défaut.

POST https://app.kataio.com/api/v1/channels/{id}/sync/trigger
Authorization: Bearer {accessToken}
Content-Type: application/json

{
  "type": "PULL_ORDERS"
}

Types de synchronisation

• PUSH_PRODUCTS — envoie les données produit vers le canal (défaut).
• PULL_PRODUCTS — importe les produits du canal dans Kataio.
• PULL_ORDERS — récupère les nouvelles commandes.
• PUSH_INVENTORY — envoie les niveaux de stock uniquement.
• FULL_SYNC — tout ce qui précède.

Réponse (201)

{
  "jobId": "6b1f0e2d-5c3a-4f7e-8d9a-0b1c2d3e4f5a",
  "status": "QUEUED"
}

400 si le canal est inactif ou si un job est déjà en cours. Suivez le job avec GET /channels/{id}/sync/jobs/{jobId} ; les webhooks channel.sync_completed / channel.sync_failed sont émis à la fin.

Lister les produits d'un canal

Consultez quels produits sont publiés sur un canal spécifique et leur statut de synchronisation.

GET https://app.kataio.com/api/v1/channels/{id}/products
Authorization: Bearer {accessToken}

Réponse (200)

{
  "data": [
    {
      "productId": "prod_01...",
      "channelId": "3f9d2c1a-7b4e-4c8d-9e2f-1a2b3c4d5e6f",
      "externalId": "7654321098",
      "status": "SYNCED",
      "lastSyncAt": "2026-03-15T08:00:00.000Z",
      "product": {
        "name": "Chemise Oxford Bleue",
        "sku": "CHM-OXF-BLU-001",
        "price": 49.90
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 34,
    "totalPages": 2
  }
}