API Produits

Lister les produits

Récupérez une liste paginée de produits avec recherche et filtres optionnels.

GET https://app.kataio.com/api/v1/products?page=1&limit=20&search=chemise&status=ACTIVE&categoryId=cat_001
Authorization: Bearer {accessToken}

Paramètres de requête

• page — Numéro de page (par défaut : 1)
• limit — Éléments par page (par défaut : 20, max : 100)
• search — Recherche plein texte sur le nom, SKU et la description
• status — Filtrer par statut : ACTIVE, DRAFT, ARCHIVED
• categoryId — Filtrer par ID de catégorie
• type — Filtrer par type de produit : SIMPLE, VARIABLE, BUNDLE
• sortBy — Champ de tri : name, price, createdAt, updatedAt
• sortOrder — Direction du tri : asc ou desc

Réponse (200)

{
  "data": [
    {
      "id": "prod_01H8X...",
      "name": "Chemise Oxford Bleue",
      "sku": "CHM-OXF-BLU-001",
      "type": "VARIABLE",
      "status": "ACTIVE",
      "price": 49.90,
      "compareAtPrice": 69.90,
      "currency": "EUR",
      "categoryId": "cat_001",
      "description": "Chemise Oxford en coton premium...",
      "weight": 0.35,
      "weightUnit": "kg",
      "variantCount": 3,
      "createdAt": "2026-03-10T14:30:00.000Z",
      "updatedAt": "2026-03-15T09:12:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "totalPages": 3
  }
}

Obtenir un produit

Récupérez un produit par son ID, incluant ses variantes et attributs personnalisés.

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

Réponse (200)

{
  "data": {
    "id": "prod_01H8X...",
    "name": "Chemise Oxford Bleue",
    "sku": "CHM-OXF-BLU-001",
    "type": "VARIABLE",
    "status": "ACTIVE",
    "price": 49.90,
    "compareAtPrice": 69.90,
    "currency": "EUR",
    "categoryId": "cat_001",
    "description": "Chemise Oxford en coton premium...",
    "weight": 0.35,
    "weightUnit": "kg",
    "images": [
      { "url": "https://cdn.kataio.com/products/chm-oxf-blu-001.jpg", "position": 0, "alt": "Chemise Oxford Bleue" }
    ],
    "variants": [
      { "id": "var_01...", "sku": "CHM-OXF-BLU-S", "name": "Taille S", "price": 49.90, "stock": 24 },
      { "id": "var_02...", "sku": "CHM-OXF-BLU-M", "name": "Taille M", "price": 49.90, "stock": 38 },
      { "id": "var_03...", "sku": "CHM-OXF-BLU-L", "name": "Taille L", "price": 49.90, "stock": 15 }
    ],
    "customAttributes": {
      "matiere": "Coton 100%",
      "coupe": "Regular fit",
      "col": "Boutonné"
    },
    "createdAt": "2026-03-10T14:30:00.000Z",
    "updatedAt": "2026-03-15T09:12:00.000Z"
  }
}

Créer un produit

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

{
  "name": "Pantalon Chino Beige",
  "sku": "PNT-CHN-BEG-001",
  "type": "SIMPLE",
  "status": "DRAFT",
  "price": 59.90,
  "currency": "EUR",
  "categoryId": "cat_003",
  "description": "Pantalon chino coupe droite en coton stretch.",
  "weight": 0.5,
  "weightUnit": "kg"
}

Mettre à jour un produit

Mettez à jour un ou plusieurs champs d'un produit existant. Incluez uniquement les champs que vous souhaitez modifier.

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

{
  "price": 44.90,
  "status": "ACTIVE",
  "compareAtPrice": 59.90
}

Supprimer un produit

Suppression douce d'un produit. Le produit est marqué comme supprimé mais conservé dans la base de données à des fins d'audit.

DELETE https://app.kataio.com/api/v1/products/prod_01H8X...
Authorization: Bearer {accessToken}

Produits associés

Depuis v2.12. Liens à sens unique d'un produit vers ceux qu'il recommande. Types : RELATED, UPSELL, CROSS_SELL, ACCESSORY. Un lien par (cible, type). GET /products/{id} les renvoie dans relationsFrom[] avec l'id, le sku, le nameI18n, le price et le status de la cible. Les boutiques qui le gèrent les reçoivent au push (WooCommerce upsell_ids / cross_sell_ids, pour les cibles déjà publiées sur cette boutique).

POST   /api/v1/products/{id}/relations                 { "relatedProductId": "…", "type": "UPSELL", "position": 0 }
PATCH  /api/v1/products/{id}/relations/{relationId}    { "type": "ACCESSORY", "position": 2 }
DELETE /api/v1/products/{id}/relations/{relationId}

• 400 si un produit est lié à lui-même, 404 produit inconnu, 409 déjà lié avec ce type.
• Permission products:update (write:products pour les clés API).

Dupliquer & modèles

Depuis v2.12. POST /products/{id}/duplicate accepte un corps optionnel. Sans corps, comportement inchangé (copie DRAFT, SKU généré, pas d'EAN, liens copiés).

{
  "sku": "TEE-BLK-M-2",
  "nameI18n": { "fr": "T-shirt noir M", "en": "Black tee M" },
  "copyChannels": false,
  "copyMedia": true,
  "copyRelations": true,
  "asTemplate": false
}

• sku — 409 s'il existe. copyChannels copie uniquement les activations de canaux (jamais les identifiants distants). copyMedia rattache les mêmes fichiers.
• asTemplate: true marque la copie comme modèle : un produit qui sert de point de départ et n'est jamais poussé vers un canal. Les modèles apparaissent dans GET /products avec "isTemplate": true ; filtre ?filter[isTemplate]=true|false.
• « Partir d'un modèle » = dupliquer un modèle avec vos propres sku / nameI18n.