API Synchronisation

Vue d'ensemble

L'API Synchronisation vous permet de suivre les changements, surveiller les tâches de synchronisation et pousser des données vers les canaux de vente connectés. Elle prend en charge la synchronisation incrémentale (récupérer uniquement ce qui a changé depuis votre dernière sync) et les opérations push pour envoyer l'inventaire, les prix, les images et les catégories vers n'importe quelle plateforme connectée.

Changements incrémentaux des produits

Récupérez les produits qui ont été créés, mis à jour ou supprimés depuis un horodatage donné. C'est la méthode la plus efficace pour maintenir un système externe synchronisé.

GET https://app.kataio.com/api/v1/sdk/products/changes?since=2026-03-30T00:00:00.000Z
X-API-Key: your_api_key

Paramètres de requête

• since (obligatoire) — Horodatage ISO 8601. Retourne les produits modifiés après cette date.
• page / limit — Pagination (par défaut : page 1, limite 100).

Réponse (200)

{
  "data": [
    {
      "id": "prod_01H8X...",
      "sku": "CHM-OXF-BLU-001",
      "name": "Chemise Oxford Bleue",
      "changeType": "UPDATED",
      "updatedFields": ["price", "stock"],
      "updatedAt": "2026-03-30T14:22:00.000Z"
    },
    {
      "id": "prod_02Y9Z...",
      "sku": "PNT-CHN-BEG-001",
      "name": "Pantalon Chino Beige",
      "changeType": "CREATED",
      "updatedFields": null,
      "createdAt": "2026-03-30T10:15:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 100,
    "total": 12,
    "totalPages": 1,
    "since": "2026-03-30T00:00:00.000Z"
  }
}

Types de changement

• CREATED — Nouveau produit ajouté depuis l'horodatage donné.
• UPDATED — Produit existant modifié. Le tableau updatedFields liste les champs modifiés.
• DELETED — Produit supprimé (soft delete). Seuls id, sku et deletedAt sont retournés.

Statut de synchronisation

Vérifiez le statut des tâches de synchronisation actives et la dernière synchronisation terminée pour chaque canal.

GET https://app.kataio.com/api/v1/sdk/sync/status
X-API-Key: your_api_key

Réponse (200)

{
  "data": {
    "activeJobs": [
      {
        "jobId": "job_sync_01H9X...",
        "channelId": "ch_shopify_01...",
        "channelName": "Shopify FR",
        "type": "FULL_SYNC",
        "status": "IN_PROGRESS",
        "progress": {
          "step": "products",
          "stepsCompleted": ["categories", "attributes"],
          "stepsRemaining": ["products", "orders", "carriers"],
          "itemsProcessed": 245,
          "itemsTotal": 500
        },
        "startedAt": "2026-03-31T08:00:00.000Z"
      }
    ],
    "lastCompleted": [
      {
        "channelId": "ch_shopify_01...",
        "channelName": "Shopify FR",
        "type": "INCREMENTAL",
        "status": "COMPLETED",
        "itemsSynced": 12,
        "duration": 4500,
        "completedAt": "2026-03-31T06:00:00.000Z"
      }
    ]
  }
}

Orchestration en 5 étapes

Les synchronisations complètes de canal suivent un pipeline d'orchestration en 5 étapes. Chaque étape se termine avant que la suivante ne commence :

1. Catégories — Synchroniser l'arborescence des catégories vers le canal.
2. Attributs — Synchroniser les attributs produit et les champs personnalisés.
3. Produits — Synchroniser les données produit, variantes, images et descriptions.
4. Commandes — Importer les nouvelles commandes du canal dans le PIM.
5. Transporteurs — Synchroniser les méthodes d'expédition et configurations de transporteurs.

Vous pouvez surveiller chaque étape via l'objet progress dans la réponse du statut de synchronisation.

Opérations Push

Poussez des types de données spécifiques du PIM vers n'importe quel canal connecté. Les 6 plateformes marketplace (Shopify, Amazon, WooCommerce, PrestaShop, eBay, Cdiscount) prennent en charge ces endpoints push.

Push Inventaire

Synchronisez les niveaux de stock vers un canal connecté.

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

{
  "productIds": ["prod_01...", "prod_02..."],
  "allProducts": false
}

Push Prix

Synchronisez les prix (y compris les prix barrés et les tarifs par devise) vers un canal.

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

{
  "productIds": ["prod_01...", "prod_02..."],
  "allProducts": false
}

Push Images

Synchronisez les images produit vers un canal. Les images sont envoyées dans l'ordre défini par leur champ position.

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

{
  "productIds": ["prod_01..."],
  "allProducts": false
}

Push Catégories

Créez ou mettez à jour des catégories sur les plateformes CMS (Shopify, WooCommerce, PrestaShop).

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

{
  "categoryIds": ["cat_01...", "cat_02..."],
  "allCategories": false
}

Réponse Push (202 Accepted)

{
  "data": {
    "jobId": "job_push_01H9X...",
    "channelId": "ch_shopify_01...",
    "type": "PUSH_INVENTORY",
    "status": "QUEUED",
    "itemCount": 2,
    "startedAt": "2026-03-31T10:00:00.000Z"
  }
}

Annuler une tâche de synchronisation

Arrêtez une tâche de synchronisation en cours. Les éléments déjà traités sont conservés ; les éléments restants sont ignorés.

POST https://app.kataio.com/api/v1/sdk/sync/{jobId}/cancel
X-API-Key: your_api_key

Réponse (200)

{
  "data": {
    "jobId": "job_sync_01H9X...",
    "status": "CANCELLED",
    "itemsProcessed": 245,
    "itemsSkipped": 255,
    "cancelledAt": "2026-03-31T08:15:00.000Z"
  }
}