Documentation de l'API

Accès programmatique à votre catalogue de produits. REST, JSON, une seule clé API — créez vos propres intégrations sur CatalogCompass.

Pour commencer

1. Créer une clé API

Dans votre tableau de bord CatalogCompass, allez dans Paramètres → Clés API et créez une nouvelle clé API. Copiez-la immédiatement — vous ne pourrez plus la revoir ensuite.

2. Authentifier chaque requête

Envoyez votre clé en tant que jeton bearer dans l'en-tête Authorization.

curl https://catalogcompass.com/api/v1/products \
  -H "Authorization: Bearer cc_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

3. URL de base

Chaque point de terminaison ci-dessous est relatif à cette URL de base.

https://catalogcompass.com

Les requêtes et réponses sont en JSON partout — envoyez Content-Type: application/json pour toute requête avec un corps.

Télécharger la spécification OpenAPI

Importez-la directement dans Postman, Insomnia, ou tout autre outil compatible OpenAPI 3.1.

Télécharger la spécification OpenAPI

Scopes

Chaque clé API possède un ou plusieurs scopes. Une clé avec le scope générique * a accès à tout.

Scope	Donne accès à
*	Tous les scopes — accès complet.
categories:read	Lire les catégories.
channels:read	Lire les canaux connectés.
fields:read	Lire les définitions de champs.
products:read	Lire les produits (liste et détail).
products:write	Créer, modifier et archiver des produits.

Points de terminaison

Products

GET/api/v1/products

List products

Requires scope `products:read`. Paginated and filterable.

Scope requis: products:read

Paramètres

Nom	Dans	Type	Requis	Description
page	query	integer — default 1	Non
limit	query	integer — default 50	Non
sort	query	string — default "-updated_at"	Non	Column to sort by, optionally prefixed with `-` for descending. One of updated_at, created_at, title, sku, brand, ean, retail_price, wholesale_price, status. Unrecognised values fall back to updated_at.
search	query	string	Non	Case-insensitive substring match against title, sku, ean, and brand.
status	query	string: draft \| active \| archived	Non
include_variants	query	string: true \| false	Non	Set to "true" to include child variants (rows with a parentId). Default excludes them.

Exemple de réponse (200)

{
  "data": [
    {
      "id": "b6b3b6a0-9b0a-4e63-8e2b-2b8f6a1d7c44",
      "ean": "8712345678906",
      "sku": "WM-BLK-001",
      "title": "Wireless Ergonomic Mouse",
      "brand": "Logitech",
      "retailPrice": "24.99",
      "wholesalePrice": "14.50",
      "status": "draft",
      "descriptionShort": "Compact wireless mouse with USB-C fast charging.",
      "descriptionLong": "A compact, ergonomic wireless mouse with USB-C fast charging, silent clicks, and a 2.4GHz + Bluetooth dual connection.",
      "condition": "NEW",
      "countryOfOrigin": "CN",
      "customFields": {
        "giftwrap_available": true
      },
      "isParent": false,
      "createdAt": "2026-06-01T09:12:00.000Z",
      "updatedAt": "2026-08-01T14:30:00.000Z"
    }
  ],
  "total": 128,
  "page": 1,
  "limit": 50
}

POST/api/v1/products

Create a product

Requires scope `products:write`. Blocked with 403 if the org's subscription is inactive or its SKU limit has been reached; blocked with 409 if the EAN is already used by another product in the org.

Scope requis: products:write

Corps de la requête

{
  "title": "Wireless Ergonomic Mouse",
  "brand": "Logitech",
  "ean": "8712345678906",
  "sku": "WM-BLK-001",
  "retailPrice": "24.99",
  "wholesalePrice": "14.50",
  "wholesalePriceUsa": "15.00",
  "status": "draft",
  "descriptionShort": "Compact wireless mouse with USB-C fast charging.",
  "descriptionLong": "A compact, ergonomic wireless mouse with USB-C fast charging, silent clicks, and a 2.4GHz + Bluetooth dual connection.",
  "condition": "NEW",
  "countryOfOrigin": "CN"
}

Exemple de réponse (201)

{
  "data": {
    "id": "b6b3b6a0-9b0a-4e63-8e2b-2b8f6a1d7c44",
    "orgId": "4f8e2c31-7a1d-4b9e-9c3a-1e5f8d2a6b90",
    "ean": "8712345678906",
    "sku": "WM-BLK-001",
    "title": "Wireless Ergonomic Mouse",
    "brand": "Logitech",
    "retailPrice": "24.99",
    "status": "draft",
    "descriptionShort": "Compact wireless mouse with USB-C fast charging.",
    "descriptionLong": "A compact, ergonomic wireless mouse with USB-C fast charging, silent clicks, and a 2.4GHz + Bluetooth dual connection.",
    "wholesalePrice": "14.50",
    "wholesalePriceUsa": "15.00",
    "customFields": {
      "giftwrap_available": true
    },
    "marketplaceData": {
      "bolcom": {
        "ean": "8712345678906"
      }
    },
    "isParent": false,
    "createdAt": "2026-06-01T09:12:00.000Z",
    "updatedAt": "2026-08-01T14:30:00.000Z"
  },
  "warning": "You are approaching your plan's SKU limit (98/100 used)."
}

GET/api/v1/products/{id}

Get a product

Requires scope `products:read`. Includes the product's images and per-channel sync status.

Scope requis: products:read

Paramètres

Nom	Dans	Type	Requis	Description
id	path	string (uuid)	Oui

Exemple de réponse (200)

{
  "data": {
    "id": "b6b3b6a0-9b0a-4e63-8e2b-2b8f6a1d7c44",
    "orgId": "4f8e2c31-7a1d-4b9e-9c3a-1e5f8d2a6b90",
    "ean": "8712345678906",
    "sku": "WM-BLK-001",
    "title": "Wireless Ergonomic Mouse",
    "brand": "Logitech",
    "retailPrice": "24.99",
    "status": "draft",
    "descriptionShort": "Compact wireless mouse with USB-C fast charging.",
    "descriptionLong": "A compact, ergonomic wireless mouse with USB-C fast charging, silent clicks, and a 2.4GHz + Bluetooth dual connection.",
    "wholesalePrice": "14.50",
    "wholesalePriceUsa": "15.00",
    "customFields": {
      "giftwrap_available": true
    },
    "marketplaceData": {
      "bolcom": {
        "ean": "8712345678906"
      }
    },
    "isParent": false,
    "createdAt": "2026-06-01T09:12:00.000Z",
    "updatedAt": "2026-08-01T14:30:00.000Z",
    "images": [
      {
        "id": "b6b3b6a0-9b0a-4e63-8e2b-2b8f6a1d7c44",
        "cdnUrl": "https://cdn.catalogcompass.com/img/b6b3b6a0-front.jpg",
        "filename": "wireless-mouse-front.jpg",
        "position": 0,
        "altText": "Wireless mouse, front view",
        "mimeType": "image/jpeg",
        "fileSize": 184320,
        "width": 1200,
        "height": 1200
      }
    ],
    "channelStatuses": [
      {
        "channelId": "2d5a7e93-4c1b-4f6e-9a8d-3b7c1e9f0a52",
        "enabled": true,
        "syncStatus": "pending",
        "lastSyncedAt": "2026-08-05T08:00:00.000Z",
        "channelName": "bol.com",
        "channelType": "bolcom"
      }
    ]
  }
}

PUT/api/v1/products/{id}

Update a product

Requires scope `products:write`. Body fields are all optional (partial update); at least one recognised field must be present or the request is rejected with 400. Note: productType, supplier, supplierSku, costPrice, taxClass, tags, metaTitle, metaDescription, seoKeywords, and urlSlug are accepted by validation but are NOT persisted by this endpoint (not in its column allow-list) — sending them has no effect. Blocked with 403 if the org's subscription is inactive; blocked with 409 if the EAN is already used by another product in the org.

Scope requis: products:write

Paramètres

Nom	Dans	Type	Requis	Description
id	path	string (uuid)	Oui

Corps de la requête

{
  "title": "Wireless Ergonomic Mouse",
  "brand": "Logitech",
  "ean": "8712345678906",
  "sku": "WM-BLK-001",
  "retailPrice": "24.99",
  "wholesalePrice": "14.50",
  "wholesalePriceUsa": "15.00",
  "status": "draft",
  "descriptionShort": "Compact wireless mouse with USB-C fast charging.",
  "descriptionLong": "A compact, ergonomic wireless mouse with USB-C fast charging, silent clicks, and a 2.4GHz + Bluetooth dual connection.",
  "condition": "NEW",
  "countryOfOrigin": "CN"
}

Exemple de réponse (200)

{
  "data": {
    "id": "b6b3b6a0-9b0a-4e63-8e2b-2b8f6a1d7c44",
    "orgId": "4f8e2c31-7a1d-4b9e-9c3a-1e5f8d2a6b90",
    "ean": "8712345678906",
    "sku": "WM-BLK-001",
    "title": "Wireless Ergonomic Mouse",
    "brand": "Logitech",
    "retailPrice": "24.99",
    "status": "draft",
    "descriptionShort": "Compact wireless mouse with USB-C fast charging.",
    "descriptionLong": "A compact, ergonomic wireless mouse with USB-C fast charging, silent clicks, and a 2.4GHz + Bluetooth dual connection.",
    "wholesalePrice": "14.50",
    "wholesalePriceUsa": "15.00",
    "customFields": {
      "giftwrap_available": true
    },
    "marketplaceData": {
      "bolcom": {
        "ean": "8712345678906"
      }
    },
    "isParent": false,
    "createdAt": "2026-06-01T09:12:00.000Z",
    "updatedAt": "2026-08-01T14:30:00.000Z"
  }
}

DELETE/api/v1/products/{id}

Archive a product

Requires scope `products:write`. This is a soft delete: the product's status is set to "archived", the row is not removed. Blocked with 403 if the org's subscription is inactive.

Scope requis: products:write

Paramètres

Nom	Dans	Type	Requis	Description
id	path	string (uuid)	Oui

Exemple de réponse (200)

{
  "data": {
    "id": "b6b3b6a0-9b0a-4e63-8e2b-2b8f6a1d7c44",
    "status": "archived"
  }
}

Nom	Dans	Type	Requis	Description
format	query	string — default "tree"	Non	"tree" (default) nests categories under their parent via `children`. Any other value returns a flat list.

Fields

GET/api/v1/fields

List field definitions

Requires scope `fields:read`. Returns the org's mandatory, standard, and custom field definitions, plus a merged `enabled` list.

Scope requis: fields:read

Exemple de réponse (200)

{
  "data": {
    "mandatory": [
      {
        "key": "warrantyPeriod",
        "name": "Warranty Period",
        "type": "text",
        "category": "mandatory",
        "propertyName": "warrantyPeriod",
        "mandatory": false,
        "description": "string",
        "options": [
          "S",
          "M",
          "L"
        ],
        "gridWidth": 6
      }
    ],
    "standard": [
      {
        "key": "warrantyPeriod",
        "name": "Warranty Period",
        "type": "text",
        "category": "mandatory",
        "propertyName": "warrantyPeriod",
        "mandatory": false,
        "description": "string",
        "options": [
          "S",
          "M",
          "L"
        ],
        "gridWidth": 6,
        "enabled": true
      }
    ],
    "custom": [
      {
        "id": "b6b3b6a0-9b0a-4e63-8e2b-2b8f6a1d7c44",
        "orgId": "4f8e2c31-7a1d-4b9e-9c3a-1e5f8d2a6b90",
        "name": "Warranty Period",
        "key": "warrantyPeriod",
        "fieldType": "text",
        "options": [
          "S",
          "M",
          "L"
        ],
        "defaultValue": null,
        "required": false,
        "position": 0,
        "createdAt": "2026-06-01T09:12:00.000Z",
        "updatedAt": "2026-08-01T14:30:00.000Z"
      }
    ],
    "enabled": [
      {
        "key": "warrantyPeriod",
        "name": "Warranty Period",
        "type": "text",
        "category": "mandatory",
        "propertyName": "warrantyPeriod",
        "mandatory": false,
        "description": "string",
        "options": [
          "S",
          "M",
          "L"
        ],
        "gridWidth": 6
      }
    ]
  }
}

Channels

GET/api/v1/channels

List connected channels

Requires scope `channels:read`. Read-only.

Scope requis: channels:read

Exemple de réponse (200)

{
  "data": [
    {
      "id": "b6b3b6a0-9b0a-4e63-8e2b-2b8f6a1d7c44",
      "type": "bolcom",
      "name": "Computer Accessories",
      "status": "active",
      "lastSyncAt": "2026-08-05T08:00:00.000Z",
      "autoSync": true,
      "syncIntervalMinutes": 60,
      "createdAt": "2026-06-01T09:12:00.000Z",
      "updatedAt": "2026-08-01T14:30:00.000Z"
    }
  ]
}

Erreurs

Chaque réponse d'erreur est en JSON avec au moins un champ error. Les erreurs de validation incluent également fieldErrors, par nom de champ.

400

Invalid query parameters.

{
  "error": "Unauthorized",
  "message": "Missing or invalid Authorization header. Use: Bearer cc_live_...",
  "fieldErrors": {
    "title": "Title is required"
  },
  "details": {
    "fieldErrors": {
      "title": [
        "Title is required"
      ]
    },
    "formErrors": []
  }
}

401

Missing/malformed Authorization header, unrecognised key, or an expired key. See `requireApiKey` in src/lib/auth/api-key-middleware.ts.

{
  "error": "Unauthorized",
  "message": "Missing or invalid Authorization header. Use: Bearer cc_live_..."
}

403

One of: the key is missing the required scope; the org's subscription is inactive; or the org's trial has expired.

{
  "error": "Unauthorized",
  "message": "Missing or invalid Authorization header. Use: Bearer cc_live_..."
}

403SkuLimitError

Missing scope, inactive subscription, expired trial, or the org's SKU limit has been reached (in which case the body is a SkuLimitError).

Variante : SkuLimitError — renvoyée par POST /api/v1/products.

{
  "error": "Unauthorized",
  "message": "Missing or invalid Authorization header. Use: Bearer cc_live_...",
  "used": 98,
  "limit": 50
}

404

No product with this id exists in the caller's organization.

{
  "error": "Unauthorized",
  "message": "Missing or invalid Authorization header. Use: Bearer cc_live_..."
}

409

The given EAN already exists in the org.

{
  "error": "Unauthorized",
  "message": "Missing or invalid Authorization header. Use: Bearer cc_live_...",
  "fieldErrors": {
    "title": "Title is required"
  },
  "details": {
    "fieldErrors": {
      "title": [
        "Title is required"
      ]
    },
    "formErrors": []
  }
}

429

The key's per-minute rate limit (api_keys.rate_limit) was exceeded.

{
  "error": "Unauthorized",
  "message": "Missing or invalid Authorization header. Use: Bearer cc_live_..."
}

500

Unexpected server error.

{
  "error": "Unauthorized",
  "message": "Missing or invalid Authorization header. Use: Bearer cc_live_..."
}

Prêt à développer ?

Démarrez votre essai gratuit de 14 jours et obtenez votre première clé API en quelques minutes.

Démarrer l'essai gratuit

Documentation de l'API

Pour commencer

1. Créer une clé API

2. Authentifier chaque requête

3. URL de base

Scopes

Points de terminaison

Products

Categories

Fields

Channels

Erreurs

Prêt à développer ?