API Opérations en masse

Vue d'ensemble

L'API Opérations en masse fournit des endpoints à haut débit pour importer et mettre à jour de grands volumes de données. Ces endpoints sont disponibles sous /api/v1/sdk/ et nécessitent une authentification par clé API via l'en-tête X-API-Key.

Import de produits en masse

Importez jusqu'à 1 000 produits en une seule requête, y compris les variantes, images, niveaux de stock et assignations de catégories.

POST https://app.kataio.com/api/v1/sdk/products/bulk-import
X-API-Key: your_api_key
Content-Type: application/json

{
  "products": [
    {
      "sku": "CHM-OXF-BLU-001",
      "name": "Chemise Oxford Bleue",
      "description": "Chemise en coton Oxford, coupe classique",
      "price": 49.90,
      "compareAtPrice": 69.90,
      "status": "ACTIVE",
      "categoryIds": ["cat_shirts"],
      "images": [
        { "url": "https://cdn.example.com/img/chemise-oxford.jpg", "position": 1 }
      ],
      "variants": [
        { "sku": "CHM-OXF-BLU-S", "name": "Taille S", "price": 49.90, "stock": 25 },
        { "sku": "CHM-OXF-BLU-M", "name": "Taille M", "price": 49.90, "stock": 40 }
      ],
      "stock": {
        "warehouseCode": "WH-PAR",
        "quantity": 65
      }
    }
  ]
}

Réponse (202 Accepted)

{
  "data": {
    "jobId": "job_bulk_01H9X...",
    "status": "PROCESSING",
    "totalItems": 1,
    "accepted": 1,
    "rejected": 0,
    "errors": []
  }
}

Limites

• Maximum 1 000 produits par requête
• Maximum 50 variantes par produit
• Maximum 20 images par produit
• Taille maximale du corps de requête : 10 Mo

Exemple TypeScript

const response = await fetch(
  "https://app.kataio.com/api/v1/sdk/products/bulk-import",
  {
    method: "POST",
    headers: {
      "X-API-Key": "your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      products: [
        {
          sku: "CHM-OXF-BLU-001",
          name: "Chemise Oxford Bleue",
          price: 49.90,
          status: "ACTIVE",
          variants: [
            { sku: "CHM-OXF-BLU-S", name: "Taille S", price: 49.90, stock: 25 },
          ],
        },
      ],
    }),
  }
);

const { data } = await response.json();
console.log("Job ID:", data.jobId);

Exemple PHP

$products = [
    [
        'sku' => 'CHM-OXF-BLU-001',
        'name' => 'Chemise Oxford Bleue',
        'price' => 49.90,
        'status' => 'ACTIVE',
    ],
];

$ch = curl_init('https://app.kataio.com/api/v1/sdk/products/bulk-import');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: your_api_key',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['products' => $products]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
echo "Job ID: " . $response['data']['jobId'];

Exemple Python

import requests

response = requests.post(
    "https://app.kataio.com/api/v1/sdk/products/bulk-import",
    headers={
        "X-API-Key": "your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "products": [
            {
                "sku": "CHM-OXF-BLU-001",
                "name": "Chemise Oxford Bleue",
                "price": 49.90,
                "status": "ACTIVE",
            },
        ],
    },
)

data = response.json()
print(f"Job ID: {data['data']['jobId']}")

Import de catégories en masse

Importez une arborescence complète de catégories en une seule requête. Les relations parent-enfant sont résolues automatiquement.

POST https://app.kataio.com/api/v1/sdk/categories/bulk-import
X-API-Key: your_api_key
Content-Type: application/json

{
  "categories": [
    {
      "externalId": "cat_clothing",
      "name": "Vêtements",
      "slug": "vetements",
      "parentExternalId": null
    },
    {
      "externalId": "cat_shirts",
      "name": "Chemises",
      "slug": "chemises",
      "parentExternalId": "cat_clothing"
    }
  ]
}

Réponse (200)

{
  "data": {
    "created": 2,
    "updated": 0,
    "errors": []
  }
}

Mise à jour d'inventaire en masse

Mettez à jour les niveaux de stock pour jusqu'à 5 000 SKUs en une seule requête. Idéal pour la synchronisation depuis un ERP ou un système de gestion d'entrepôt.

PATCH https://app.kataio.com/api/v1/sdk/inventory/bulk-update
X-API-Key: your_api_key
Content-Type: application/json

{
  "updates": [
    { "sku": "CHM-OXF-BLU-S", "warehouseCode": "WH-PAR", "quantity": 120 },
    { "sku": "CHM-OXF-BLU-M", "warehouseCode": "WH-PAR", "quantity": 85 }
  ]
}

Réponse (200)

{
  "data": {
    "updated": 2,
    "notFound": 0,
    "errors": []
  }
}

Mise à jour des prix en masse

Mettez à jour les prix pour jusqu'à 5 000 SKUs en une seule requête.

PATCH https://app.kataio.com/api/v1/sdk/prices/bulk-update
X-API-Key: your_api_key
Content-Type: application/json

{
  "updates": [
    { "sku": "CHM-OXF-BLU-001", "price": 54.90, "compareAtPrice": 74.90 },
    { "sku": "PNT-CHN-BEG-001", "price": 39.90, "compareAtPrice": null }
  ]
}

Réponse (200)

{
  "data": {
    "updated": 2,
    "notFound": 0,
    "errors": []
  }
}

Gestion des erreurs

Les endpoints en masse traitent les éléments individuellement. Si certains éléments échouent à la validation, les éléments valides sont tout de même traités. Vérifiez le tableau errors pour les détails sur les éléments rejetés :

{
  "data": {
    "updated": 48,
    "notFound": 2,
    "errors": [
      { "sku": "INVALID-001", "error": "Produit non trouvé" },
      { "sku": "CHM-DUP-001", "error": "SKU en double dans la requête" }
    ]
  }
}

Limites de débit

• Import de produits en masse : 10 requêtes par minute
• Import de catégories en masse : 10 requêtes par minute
• Mise à jour d'inventaire en masse : 30 requêtes par minute
• Mise à jour des prix en masse : 30 requêtes par minute