Catalogue de produits

Envoyez et maintenez votre catalogue par SKU depuis votre propre système (ERP, PIM, boutique).

Endpoints

Endpoint	Rôle
`GET /v1/products`	Liste paginée (limit ≤ 200, offset, recherche q, status). Scope catalog:read.
`GET /v1/products/{id}`	Détail d'un produit, y compris son source_data. Scope catalog:read.
`POST /v1/products`	Upsert en masse par SKU, jusqu'à 500 par requête. Scope catalog:write.
`PATCH /v1/products/{id}`	Modification partielle de sku, name, brand ou category. Scope catalog:write.
`DELETE /v1/products/{id}`	Suppression douce (204). Conserve l'historique ; masqué des listes et de l'export. Scope catalog:write.
`GET /v1/products/{id}/revisions`	Ce qui a changé dans la fiche : versions, avec ce qui a changé dans chacune. Scope catalog:read.

Upsert en masse par SKU

Le POST est idempotent par (organisation, SKU) : renvoyer le même lot laisse le catalogue inchangé, et un SKU supprimé auparavant est ressuscité. La réponse détaille combien ont été créés, mis à jour ou ignorés.

POST /v1/products
{
  "products": [
    {
      "sku": "CAMISA-001",
      "name": "Camisa de lino",
      "brand": "Acme",
      "category": "Ropa/Camisas",
      "source_data": { "color": "azul", "talla": "M" }
    }
  ]
}

{ "total": 1, "created": 1, "updated": 0, "skipped": 0 }

Un nouvel upsert REMPLACE le produit entier par SKU (y compris son source_data). Envoyez toujours le produit complet, pas seulement les champs modifiés — pour des retouches ponctuelles, utilisez PATCH.

source_data

source_data vous appartient : un objet JSON libre avec les attributs supplémentaires de votre produit (couleur, taille, matière, spécifications…). Le moteur de génération s'en sert comme contexte pour écrire de meilleures descriptions — plus il est riche, meilleur est le résultat.

Modifier et supprimer

PATCH modifie des champs isolés sans toucher au reste. Le status du produit n'est PAS modifiable via l'API (le cycle de génération s'en charge). Si le nouveau SKU existe déjà sur un autre produit, la réponse est 409.

DELETE est une suppression douce : le produit disparaît des listes et de l'export mais son historique est conservé, et un upsert ultérieur avec le même SKU le ressuscite. Répéter le DELETE répond 404.

L'historique d'une fiche

Si vous synchronisez avec votre boutique, ceci vous dit quoi regarder sans retélécharger toute la fiche : chaque version porte ce qui a changé par rapport à la précédente — champs, attributs (par code et par langue), catégories et famille. Des données importées, on indique les noms des colonnes qui ont changé, jamais leur contenu.

GET /v1/products/7f3a…/revisions

{
  "revisions": [
    {
      "version": 7,
      "reason": "import",
      "created_at": "2026-09-12T05:03:11Z",
      "changes": {
        "base": { "name": ["Crema hidratante", "Crema hidratante 50 ml"] },
        "values": { "tamano": { "": [["1.7 OZ"], ["50 ml"]] } },
        "source_data": { "changed": ["precio"] }
      }
    }
  ],
  "total": 7,
  "limit": 20
}

La pagination va vers l'arrière : limit (1–50, 20 par défaut) et before_version, auquel vous passez la version la plus basse reçue. changes est vide à la première version d'un produit, qui n'a rien à quoi se comparer ; et si un changement est énorme, il arrive tronqué, avec _truncated et des compteurs.

Il ne contient ni qui a fait le changement —c'est interne à votre organisation et cela s'affiche dans l'application— ni l'état complet de la fiche à chaque version, que vous obtenez avec le détail du produit. Revenir à une version antérieure n'est pas non plus possible via l'API : cela se fait dans l'application, où un rôle d'administrateur est requis.