Zum Inhalt springen
CatalogCompass

API-Dokumentation

Programmatischer Zugriff auf Ihren Produktkatalog. REST, JSON, ein API-Schlüssel — bauen Sie Ihre eigenen Integrationen auf CatalogCompass auf.

Erste Schritte

1. API-Schlüssel erstellen

Gehen Sie in Ihrem CatalogCompass-Dashboard zu Einstellungen → API-Schlüssel und erstellen Sie einen neuen API-Schlüssel. Kopieren Sie ihn sofort — Sie können ihn danach nicht mehr einsehen.

2. Jede Anfrage authentifizieren

Senden Sie Ihren Schlüssel als Bearer-Token im Authorization-Header.

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

3. Basis-URL

Jeder Endpunkt unten ist relativ zu dieser Basis-URL.

https://catalogcompass.com

Anfragen und Antworten sind durchgehend JSON — senden Sie Content-Type: application/json bei jeder Anfrage mit einem Body.

OpenAPI-Spezifikation herunterladen

Direkt in Postman, Insomnia oder ein anderes OpenAPI-3.1-kompatibles Tool importieren.

OpenAPI-Spezifikation herunterladen

Scopes

Jeder API-Schlüssel hat einen oder mehrere Scopes. Ein Schlüssel mit dem Wildcard-Scope * hat Zugriff auf alles.

ScopeGewährt Zugriff auf
*Alle Scopes — vollständiger Zugriff.
categories:readKategorien lesen.
channels:readVerbundene Kanäle lesen.
fields:readFelddefinitionen lesen.
products:readProdukte lesen (Liste und Abruf).
products:writeProdukte erstellen, aktualisieren und archivieren.

Endpunkte

Products

GET/api/v1/products

List products

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

Erforderlicher Scope: products:read

Parameter

NameInTypErforderlichBeschreibung
pagequeryinteger — default 1Nein
limitqueryinteger — default 50Nein
sortquerystring — default "-updated_at"NeinColumn 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.
searchquerystringNeinCase-insensitive substring match against title, sku, ean, and brand.
statusquerystring: draft | active | archivedNein
include_variantsquerystring: true | falseNeinSet to "true" to include child variants (rows with a parentId). Default excludes them.

Beispielantwort (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.

Erforderlicher Scope: products:write

Request Body

{
  "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"
}

Beispielantwort (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.

Erforderlicher Scope: products:read

Parameter

NameInTypErforderlichBeschreibung
idpathstring (uuid)Ja

Beispielantwort (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.

Erforderlicher Scope: products:write

Parameter

NameInTypErforderlichBeschreibung
idpathstring (uuid)Ja

Request Body

{
  "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"
}

Beispielantwort (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.

Erforderlicher Scope: products:write

Parameter

NameInTypErforderlichBeschreibung
idpathstring (uuid)Ja

Beispielantwort (200)

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

Categories

GET/api/v1/categories

List categories

Requires scope `categories:read`.

Erforderlicher Scope: categories:read

Parameter

NameInTypErforderlichBeschreibung
formatquerystring — default "tree"Nein"tree" (default) nests categories under their parent via `children`. Any other value returns a flat list.

Beispielantwort (200)

{
  "data": [
    {
      "id": "b6b3b6a0-9b0a-4e63-8e2b-2b8f6a1d7c44",
      "name": "Computer Accessories",
      "slug": "computer-accessories",
      "parentId": null,
      "googleProductCategory": "Electronics > Computers > Computer Accessories",
      "position": 0,
      "createdAt": "2026-06-01T09:12:00.000Z",
      "updatedAt": "2026-08-01T14:30:00.000Z",
      "children": []
    }
  ]
}

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.

Erforderlicher Scope: fields:read

Beispielantwort (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.

Erforderlicher Scope: channels:read

Beispielantwort (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"
    }
  ]
}

Fehler

Jede Fehlerantwort ist JSON mit mindestens einem error-Feld. Validierungsfehler enthalten zusätzlich fieldErrors, nach Feldname.

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 — zurückgegeben von 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_..."
}

Bereit zum Entwickeln?

Starten Sie Ihre 14-tägige kostenlose Testphase und erhalten Sie in wenigen Minuten Ihren ersten API-Schlüssel.

Kostenlose Testphase starten