Canaux personnalisés

Qu'est-ce qu'un canal personnalisé

Un canal personnalisé est un canal de vente nommé (plateforme CUSTOM) pour un système sans connecteur Kataio : un ERP, une boutique développée en interne, une place de marché non prise en charge. Sa création vous donne deux choses en une étape :

• le canal — il apparaît dans la liste des canaux, les commandes et publications produit peuvent lui être rattachées ;
• une clé API dédiée (pk_live_…) avec accès en lecture et écriture aux produits, catégories, stock, commandes et clients.

Rien ne se synchronise automatiquement. Kataio n'appelle jamais votre système : c'est votre système qui appelle l'API Kataio avec cette clé.

Quand l'utiliser (plutôt qu'un connecteur)

Situation	Solution
Shopify, WooCommerce, PrestaShop, Amazon, eBay… (16 plateformes)	Le connecteur intégré — Kataio pousse les produits et récupère les commandes lui-même
Votre ERP est la source de vérité pour les prix et le stock	Un canal personnalisé — l'ERP pousse avec les endpoints en masse
Une boutique sur mesure a besoin du catalogue et crée des commandes	Un canal personnalisé — interrogez les flux de changements, créez les commandes via l'API
Vous voulez seulement lire des données depuis un script	Une simple clé API avec des scopes de lecture (Intégrations → Clés API)

Le parcours

1. Créer le canal

Dans le tableau de bord, ouvrez Intégrations → Canaux personnalisés → Ajouter un canal personnalisé, donnez-lui un nom et copiez la clé API — elle n'est affichée qu'une fois. L'identifiant du canal est visible sur la carte et peut être copié à tout moment.

2. Envoyer les produits avec l'identifiant du canal

Les produits sont créés ou mis à jour par SKU, par lots de 1 000 maximum. Passez options.channelId pour que chaque produit importé soit publié sur votre canal :

curl -X POST "https://app.kataio.com/api/v1/sdk/products/bulk-import" \
  -H "X-API-Key: pk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      { "sku": "SKU-001", "name": "Produit exemple", "price": 19.9, "stock": 12 }
    ],
    "options": { "channelId": "3f9d2c1a-7b4e-4c8d-9e2f-1a2b3c4d5e6f" }
  }'

Seuls sku, name et price sont obligatoires. La réponse compte ce qui s'est passé et liste les erreurs par SKU :

{ "total": 1, "created": 1, "updated": 0, "errors": [] }

Le stock et les prix se mettent à jour en masse sans renvoyer tout le produit : PATCH /api/v1/sdk/inventory/bulk-update et PATCH /api/v1/sdk/prices/bulk-update. Catégories : POST /api/v1/sdk/categories/bulk-import.

3. Créer des commandes

curl -X POST "https://app.kataio.com/api/v1/orders" \
  -H "X-API-Key: pk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-order-10042" \
  -d '{
    "channelId": "769b96b8-a1a1-46aa-b149-514e5a3c227b",
    "customerName": "Marie Dupont",
    "customerEmail": "marie.dupont@exemple.fr",
    "externalReference": "ERP-10042",
    "items": [ { "sku": "SKU-001", "quantity": 2, "unitPrice": 19.9 } ]
  }'

L'en-tête Idempotency-Key rend les rejeux sûrs pendant 24 heures. Les changements de statut de ces commandes émettent order.status_changed (et order.shipped, order.delivered…) comme pour toute autre commande.

4. Interroger les changements

Plutôt que de relire tout le catalogue, demandez ce qui a changé depuis votre dernière exécution (ISO 8601, 1 000 éléments maximum par appel) :

GET /api/v1/sdk/products/changes?since=2026-09-20T06:00:00Z
GET /api/v1/sdk/categories/changes?since=…
GET /api/v1/sdk/inventory/changes?since=…

{ "data": [ { "id": "…", "sku": "SKU-001", "variants": [ … ], "media": [ … ] } ],
  "meta": { "total": 1, "since": "2026-09-20T06:00:00Z" } }

Conservez l'horodatage de chaque exécution réussie et passez-le comme prochain since. Pour être notifié plutôt que d'interroger, enregistrez un webhook sur product.updated et stock.updated.

5. État de synchronisation

GET /api/v1/sdk/sync/status renvoie les jobs de synchronisation en attente ou en cours et le dernier terminé sur les canaux à connecteur du compte (activeJobs[], lastSync). Il exige le scope read:channels, que la clé du canal personnalisé ne porte pas — appelez-le avec une clé API classique disposant de ce scope.

Scopes accordés

La clé créée avec un canal personnalisé porte exactement : read:products, write:products, read:categories, write:categories, read:inventory, write:inventory, read:orders, write:orders, read:customers, write:customers. Un scope write: accorde aussi la lecture, la création, la modification et la suppression sur la ressource. Aucun scope analytics, channels, webhooks, attributes ni users.

Limites

• Pas de synchronisation automatique. Le canal n'a pas de connecteur : Kataio ne pousse ni ne récupère rien. Sa carte dans Intégrations n'affiche jamais d'état de synchronisation.
• La clé vaut pour tout le compte. Elle est rattachée au canal pour le suivi, mais elle peut lire et écrire tous les produits, commandes et clients de votre compte, pas seulement ce qui est publié sur ce canal. Gardez-la côté serveur.
• Pas de webhook par canal. Les endpoints webhook valent pour tout le compte et les événements ne sont pas filtrés par canal.
• Attribuez les commandes explicitement. Envoyez channelId dans POST /api/v1/orders ; sans lui, la commande est rattachée à votre premier canal actif. Le canal doit appartenir à votre compte (sinon 404). Utilisez externalReference pour conserver votre propre identifiant de commande.
• Supprimer le canal révoque immédiatement ses clés API et supprime les commandes et publications qui lui sont rattachées. Les produits restent dans le catalogue.

Prochaines étapes

• Authentification — X-API-Key ou Bearer, scopes
• Webhooks — notifications push plutôt qu'interrogation
• Limites de débit — 600 requêtes/minute par clé par défaut