API Dokumentation

Vollstaendige Referenz der Priceivy REST API. Verwalte Produkte, Preise, Kategorien und mehr programmatisch.

Basis

Base URL

https://app.priceivy.com/api/v1

Format

Alle Requests und Responses verwenden application/json

Pagination

Alle Listen-Endpoints verwenden offset-basierte Pagination mit zwei Query-Parametern:

Feld	Typ	Status	Beschreibung
`limit`	integer	Optional	Anzahl Ergebnisse pro Seite. Min: 1, Max: 10.000, Default: 50
`offset`	integer	Optional	Anzahl zu ueberspringender Ergebnisse. Min: 0, Default: 0

Werte ausserhalb des gueltigen Bereichs werden automatisch auf den naechsten gueltigen Wert begrenzt (z.B. limit=15000 wird zu limit=10000).

Die Response enthaelt immer ein pagination Objekt mit limit, offset und total. Ergebnisse werden standardmaessig nach Erstelldatum sortiert (neueste zuerst).

Grosse Datenmengen: Der Bulk-Upsert-Endpoint akzeptiert bis zu 10.000 Produkte pro Request. Ab 500 Items wird automatisch nur eine Summary zurueckgegeben (ohne vollstaendige Produktdaten pro Item). Bei ≤500 Items kann der Response-Modus ueber den Query-Parameter response_mode gesteuert werden. Hinweis: response_mode=full wird bei >500 Items ignoriert — es wird immer eine Summary zurueckgegeben.

Authentifizierung

Die API verwendet Bearer-Token-Authentifizierung. API-Keys koennen im Dashboard unter Einstellungen → API-Keys erstellt werden.

Format

Alle API-Keys beginnen mit dem Prefix rp_

Header

Authorization: Bearer rp_dein_api_key

Sicherheitshinweis: API-Keys werden als SHA256-Hash gespeichert. Der vollstaendige Key wird nur bei der Erstellung einmalig angezeigt. Bewahre ihn sicher auf.

Auth-Fehlercodes

Code	Beschreibung
`401`	Kein API-Key im Header oder Key ungueltig / nicht gefunden
`403`	API-Key ist abgelaufen

Produkte

Die Produkt-Endpoints ermoeglichen das vollstaendige Management deiner Produkte — inklusive Preise, Bilder, Identifier, Attribute und Kategorie-Zuordnungen. Produkte werden ueber ihre eindeutige external_id identifiziert (z.B. die Produkt-ID aus deinem Shopsystem wie Shopify, WooCommerce, etc.).

GET/v1/products

Gibt eine paginierte Liste aller Produkte zurueck, inklusive aller Sub-Daten (Preise, Bilder, Identifier, Attribute, Kategorien).

Query-Parameter

Feld	Typ	Status	Beschreibung
`limit`	integer	Optional	Ergebnisse pro Seite (1–10.000, Default: 50)
`offset`	integer	Optional	Anzahl zu ueberspringender Ergebnisse (Default: 0)

Beispiel

curl -X GET "https://app.priceivy.com/api/v1/products?limit=50&offset=0" \
  -H "Authorization: Bearer rp_dein_api_key"

Response (200)

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organization_id": "...",
      "external_id": "WM-2024",
      "sku": "WM-2024",
      "name": "Wireless Maus Pro",
      "gtin": "4012345678901",
      "import_excluded": false,
      "export_excluded": false,
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z",
      "prices": [...],
      "images": [...],
      "identifiers": [...],
      "attributes": [...],
      "categories": [...]
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 127
  }
}

GET/v1/products/{external_id}

Gibt ein einzelnes Produkt per external_id zurueck, inklusive aller Sub-Daten.

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`external_id`	string	Pflicht	Eindeutige external_id des Produkts (URL-encoded)

Beispiel

curl -X GET "https://app.priceivy.com/api/v1/products/WM-2024" \
  -H "Authorization: Bearer rp_dein_api_key"

Response (200)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "...",
    "external_id": "WM-2024",
    "sku": "WM-2024",
    "name": "Wireless Maus Pro",
    "gtin": "4012345678901",
    "import_excluded": false,
    "export_excluded": false,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "prices": [...],
    "images": [...],
    "identifiers": [...],
    "attributes": [...],
    "categories": [...]
  }
}

PUT/v1/products/{external_id}

Idempotenter Upsert per external_id. Erstellt das Produkt falls es nicht existiert (201) oder aktualisiert es (200). Alle Sub-Ressourcen werden bei Angabe vollstaendig ersetzt (Replace-All).

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`external_id`	string	Pflicht	external_id des Produkts (URL-encoded)

Beispiel

curl -X PUT "https://app.priceivy.com/api/v1/products/WM-2024" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wireless Maus Pro v2",
    "sku": "WM-2024-V2",
    "prices": [
      {
        "price_type": "vk_current",
        "price_net": 2499,
        "price_gross": 2974
      }
    ],
    "images": [
      {
        "url": "https://example.com/maus-pro-v2.jpg",
        "sort": 0
      }
    ]
  }'

Response (200 oder 201)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "...",
    "external_id": "WM-2024",
    "sku": "WM-2024-V2",
    "name": "Wireless Maus Pro v2",
    "gtin": null,
    "import_excluded": false,
    "export_excluded": false,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-16T08:00:00.000Z",
    "prices": [...],
    "images": [...],
    "identifiers": [...],
    "attributes": [...],
    "categories": [...]
  }
}

Hinweis: Bei Angabe von prices, images, identifiers oder attributes werden alle bestehenden Eintraege ersetzt (Replace-All).

import_excluded: Wenn das Produkt import_excluded = true hat, gibt dieser Endpoint 403 zurueck. Geschuetzte Produkte koennen nur direkt im Backend geaendert werden.

DELETE/v1/products/{external_id}

Loescht ein Produkt per external_id.

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`external_id`	string	Pflicht	external_id des Produkts (URL-encoded)

Beispiel

curl -X DELETE "https://app.priceivy.com/api/v1/products/WM-2024" \
  -H "Authorization: Bearer rp_dein_api_key"

Response (200)

{
  "data": {
    "success": true
  }
}

import_excluded: Wenn das Produkt import_excluded = true hat, gibt dieser Endpoint 403 zurueck. Geschuetzte Produkte koennen nur direkt im Backend geloescht werden.

POST/v1/products/bulk-upsert

Erstellt oder aktualisiert bis zu 10.000 Produkte per external_id in einem Request. Alle Items werden vorab validiert — bei Fehlern wird kein Item verarbeitet.

Query-Parameter

Feld	Typ	Status	Beschreibung
`response_mode`	string	Optional	"full" = vollstaendige Produktdaten pro Item (Default bei ≤500 Items). "summary" = nur Zusammenfassung + Fehler-Liste (Default bei >500 Items).

Beispiel

curl -X POST "https://app.priceivy.com/api/v1/products/bulk-upsert" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "WM-2024",
        "name": "Wireless Maus Pro",
        "sku": "WM-PRO-2024",
        "prices": [
          { "price_type": "vk_current", "price_net": 1999, "price_gross": 2379 }
        ]
      },
      {
        "external_id": "KB-2024",
        "name": "Mechanische Tastatur"
      }
    ]
  }'

Response — Full Mode (200)

Enthaelt vollstaendige Produktdaten pro Item. Default bei ≤500 Items.

{
  "items": [
    {
      "success": true,
      "status": 201,
      "data": { "id": "...", "external_id": "WM-2024", "name": "Wireless Maus Pro", ... }
    },
    {
      "success": true,
      "status": 200,
      "data": { "id": "...", "external_id": "KB-2024", "name": "Mechanische Tastatur", ... }
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 2,
    "failed": 0
  },
  "warnings": ["Sub-Daten konnten nicht aktualisiert werden: org_product_prices"]  // Optional
}

Response — Summary Mode (200)

Nur Zusammenfassung ohne Einzeldaten. Default bei >500 Items. Die Summary enthaelt hier eine detailliertere Aufschluesselung mit created und updated statt succeeded.

{
  "summary": {
    "total": 10000,
    "created": 8500,
    "updated": 1450,
    "failed": 50
  },
  "errors": [
    { "external_id": "DEFEKT-001", "error": "Unbekannte category_external_id: xyz" }
  ],
  "warnings": ["Sub-Daten konnten nicht aktualisiert werden: org_product_prices"]  // Optional
}

Limit: Maximal 10.000 Items pro Request (Body-Size-Limits koennen je nach Infrastruktur variieren). Jedes Item benoetigt ein external_id Feld. Alle Items werden vorab validiert — bei Validierungsfehlern wird ein 422 mit allen Fehlern auf einmal zurueckgegeben. Soft-deleted Produkte werden bei erneutem Upsert automatisch reaktiviert.

Struktur-Validierung (422)

Wenn der Request-Body nicht die erwartete Struktur hat:

// items fehlt oder ist kein Array
{
  "error": "items muss als Array gesendet werden"
}

// Array leer oder mehr als 10.000 Items
{
  "error": "items muss zwischen 1 und 10000 Eintraegen enthalten"
}

Item-Validierungsfehler (422)

Alle Items werden vorab validiert. Bei Fehlern wird kein Item verarbeitet — stattdessen werden alle Fehler gesammelt und auf einmal zurueckgegeben:

{
  "error": "2 von 5 Items haben Validierungsfehler",
  "details": {
    "validation_errors": [
      {
        "index": 1,
        "external_id": null,
        "error": "external_id ist erforderlich"
      },
      {
        "index": 3,
        "external_id": "X",
        "error": "prices[0].price_type ist ungueltig"
      }
    ]
  }
}

Doppelte external_ids: Wenn im selben Batch mehrere Items die gleiche external_id haben, wird nur das letzte Item mit dieser external_id verarbeitet. Im Full-Response (≤500 Items) werden fruehere Duplikate mit 409 als uebersprungen markiert.

import_excluded: Items, deren bestehendes Produkt import_excluded = true hat, werden mit Status 403 markiert und uebersprungen. Alle anderen Items werden normal verarbeitet.

POST/v1/products/bulk-delete

Loescht bis zu 10.000 Produkte per external_id in einem Request. Nicht gefundene external_ids werden mit Fehler markiert.

Beispiel

curl -X POST "https://app.priceivy.com/api/v1/products/bulk-delete" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ids": ["WM-2024", "KB-2024", "NICHT-VORHANDEN"]
  }'

Response — Full Mode (200)

Enthaelt Einzelergebnisse pro Item. Default bei ≤500 Items.

{
  "items": [
    { "success": true, "status": 200, "data": { "external_id": "WM-2024" } },
    { "success": true, "status": 200, "data": { "external_id": "KB-2024" } },
    { "success": false, "status": 404, "error": "Produkt nicht gefunden" }
  ],
  "summary": {
    "total": 3,
    "succeeded": 2,
    "failed": 1
  },
  "warnings": ["Sub-Daten konnten nicht geloescht werden: org_product_prices"]  // Optional
}

Response — Summary Mode (200)

Nur Zusammenfassung ohne Einzelergebnisse. Default bei >500 Items.

{
  "summary": {
    "total": 10000,
    "succeeded": 9999,
    "failed": 1
  },
  "errors": [
    { "external_id": "prod-999", "error": "Produkt nicht gefunden" }
  ],
  "warnings": ["Sub-Daten konnten nicht geloescht werden: org_product_prices"]  // Optional
}

Limit: Maximal 10.000 external_ids pro Request. Ab 500 Items wird automatisch nur eine Summary zurueckgegeben.

import_excluded: Produkte mit import_excluded = true werden mit Status 403 markiert und nicht geloescht. Alle anderen Produkte werden normal verarbeitet.

Validierungsfehler-Response (422)

Bei ungueltigem Input wird der Request abgelehnt, bevor Items verarbeitet werden:

// external_ids ist kein Array
{
  "error": "external_ids muss als Array gesendet werden"
}

// Array leer oder mehr als 10.000 Items
{
  "error": "external_ids muss zwischen 1 und 10000 Eintraegen enthalten"
}

// Ein Item ist kein String oder leer (mit Index)
{
  "error": "external_ids[0] muss ein nicht-leerer String sein"
}

Warnings-Feld bei Bulk-Responses: Das optionale warnings-Array erscheint nur, wenn bei Sub-Daten (Preise, Bilder, Identifier, etc.) Teilfehler aufgetreten sind. Die Hauptoperation (Produkt erstellen/aktualisieren/loeschen) war trotzdem erfolgreich.

Payload-Schema

Das folgende Schema gilt fuer PUT-Requests und Bulk-Upsert Items auf Produkt-Endpoints.

Strikte Validierung: Unbekannte Felder im Body werden abgelehnt (422). Nur die unten aufgefuehrten Felder sind erlaubt.

Basis-Felder

Feld	Typ	Status	Beschreibung
`external_id`	string	Pflicht	Eindeutige ID aus deinem System (bei Bulk-Upsert im Item, bei PUT im Pfad)
`sku`	string \| null	Optional	Optionale Artikelnummer (SKU)
`name`	string \| null	Optional	Produktname
`gtin`	string \| null	Optional	GTIN / Barcode

prices

Array von Preis-Objekten. Bei Angabe werden alle bestehenden Preise ersetzt.

Feld	Typ	Status	Beschreibung
`price_type`	string	Pflicht	Preistyp — Kern-Typen: "ek_avg" (Durchschnittlicher EK), "vk_current" (Aktueller VK). Die Kern-Typen werden hauptsaechlich zur Auswertung und Anzeige im Dashboard verwendet. Eigene Typen erlaubt (z.B. "uvp", "min", "ek_best"). Max. 50 Zeichen.
`price_net`	integer	Pflicht	Nettopreis in Cent, nicht-negative Ganzzahl (z.B. 2499 fuer 24,99 EUR)
`price_gross`	integer	Pflicht	Bruttopreis in Cent, nicht-negative Ganzzahl (z.B. 2974 fuer 29,74 EUR)

images

Array von Bild-Objekten. Bei Angabe werden alle bestehenden Bilder ersetzt.

Feld	Typ	Status	Beschreibung
`url`	string	Pflicht	URL des Bildes
`sort`	number	Optional	Sortierreihenfolge (Default: Array-Index)

identifiers

Array von Key-Value-Paaren fuer zusaetzliche Produktkennungen. Bei Angabe werden alle bestehenden Identifier ersetzt. Eigene Keys sind weiterhin erlaubt.

Die folgenden Kern-Identifier werden von Priceivy zum automatischen Scraping verwendet (Preisvergleich auf Marktplaetzen wie Amazon, Idealo, eBay etc.).

Key	Beschreibung
`asin`	Amazon Standard Identification Number
`isbn`	International Standard Book Number
`mpn`	Manufacturer Part Number (Herstellernummer)

Feld	Typ	Status	Beschreibung
`key`	string	Pflicht	Schluessel — Kern-Keys: "asin", "isbn", "mpn". Eigene Keys sind ebenfalls erlaubt.
`value`	string	Pflicht	Wert

attributes

Array von Key-Value-Paaren fuer Produkteigenschaften (z.B. Farbe, Gewicht). Bei Angabe werden alle bestehenden Attribute ersetzt.

Feld	Typ	Status	Beschreibung
`key`	string	Pflicht	Schluessel (z.B. "farbe", "gewicht", "material")
`value`	string	Pflicht	Wert

exclusions

Steuert, ob ein Produkt vom Import oder Export ausgeschlossen wird. Sende null um beide Flags auf false zurueckzusetzen.

Feld	Typ	Status	Beschreibung
`import`	boolean	Optional	Produkt vom Import ausschliessen
`export`	boolean	Optional	Produkt vom Export ausschliessen

Schreibschutz: Wenn import auf true gesetzt ist, kann das Produkt ueber die API nicht mehr aktualisiert oder geloescht werden (403). Aenderung nur direkt im Backend moeglich. Produkte mit export auf true werden bei zukuenftigen Export-Endpoints nicht enthalten sein.

category_external_ids

Array von externen Kategorie-IDs. Bei Angabe werden alle bestehenden Kategorie-Zuordnungen ersetzt. Die Kategorien muessen vorher ueber den Kategorien-Endpoint erstellt werden.

Feld	Typ	Status	Beschreibung
`category_external_ids`	string[]	Optional	Array von externen Kategorie-IDs
`category_ids`	string[]	Optional	Alternativ: Array von Kategorie-UUIDs

Wichtig: category_ids und category_external_ids koennen nicht gleichzeitig in einem Request verwendet werden.

Update-Verhalten bei Sub-Ressourcen (prices, images, identifiers, attributes, categories):

Feld weglassen — bestehende Daten bleiben unveraendert
Leeres Array senden ([]) — alle bestehenden Eintraege werden geloescht
Array mit Daten senden — bestehende Eintraege werden komplett ersetzt (Replace-All)

Vollstaendiges Payload-Beispiel

{
  "external_id": "WM-2024",
  "sku": "WM-PRO-2024",
  "name": "Wireless Maus Pro",
  "gtin": "4012345678901",
  "prices": [
    {
      "price_type": "vk_current",
      "price_net": 1999,
      "price_gross": 2379
    },
    {
      "price_type": "ek_avg",
      "price_net": 850,
      "price_gross": 1012
    }
  ],
  "images": [
    { "url": "https://example.com/maus-front.jpg", "sort": 0 },
    { "url": "https://example.com/maus-side.jpg", "sort": 1 }
  ],
  "identifiers": [
    { "key": "mpn", "value": "WM-PRO-2024" },
    { "key": "asin", "value": "B0XXXXXXXXX" }
  ],
  "attributes": [
    { "key": "farbe", "value": "Schwarz" },
    { "key": "gewicht", "value": "85g" }
  ],
  "exclusions": {
    "import": false,
    "export": false
  },
  "category_external_ids": ["elektronik", "peripherie"]
}

Kategorien

Kategorien ermoeglichen die hierarchische Organisation deiner Produkte. Jede Kategorie wird ueber eine eindeutige external_id pro Organisation identifiziert.

GET/v1/categories

Gibt eine paginierte Liste aller Kategorien zurueck, inklusive Attributes.

Query-Parameter

Feld	Typ	Status	Beschreibung
`limit`	integer	Optional	Ergebnisse pro Seite (1–10.000, Default: 50)
`offset`	integer	Optional	Anzahl zu ueberspringender Ergebnisse (Default: 0)

Beispiel

curl -X GET "https://app.priceivy.com/api/v1/categories?limit=50&offset=0" \
  -H "Authorization: Bearer rp_dein_api_key"

Response (200)

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organization_id": "...",
      "external_id": "elektronik",
      "name": "Elektronik",
      "parent_id": null,
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z",
      "attributes": [
        { "id": "...", "key": "idealo_id", "value": "12345" }
      ]
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 12
  }
}

GET/v1/categories/{ref}

Gibt eine einzelne Kategorie per UUID oder external_id zurueck, inklusive Attributes.

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`ref`	UUID \| string	Pflicht	UUID oder external_id der Kategorie

Beispiel

curl -X GET "https://app.priceivy.com/api/v1/categories/elektronik" \
  -H "Authorization: Bearer rp_dein_api_key"

Response (200)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "...",
    "external_id": "elektronik",
    "name": "Elektronik",
    "parent_id": null,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "attributes": []
  }
}

PUT/v1/categories/{ref}

Idempotenter Upsert einer Kategorie per UUID oder external_id. Erstellt die Kategorie falls sie nicht existiert (201) oder aktualisiert sie (200). Attributes werden bei Angabe vollstaendig ersetzt.

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`ref`	UUID \| string	Pflicht	UUID oder external_id der Kategorie

Beispiel

curl -X PUT "https://app.priceivy.com/api/v1/categories/elektronik" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "elektronik",
    "name": "Elektronik & Zubehoer",
    "attributes": [
      { "key": "idealo_id", "value": "12345" }
    ]
  }'

Response (200 oder 201)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "...",
    "external_id": "elektronik",
    "name": "Elektronik & Zubehoer",
    "parent_id": null,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-16T08:00:00.000Z",
    "attributes": [
      { "id": "...", "key": "idealo_id", "value": "12345" }
    ]
  }
}

Body/Pfad-Abgleich: Wenn der ref Pfad-Parameter eine external_id ist (kein UUID) und im Body ebenfalls eine external_id angegeben wird, muessen beide uebereinstimmen. Bei einem Mismatch wird ein 422-Fehler zurueckgegeben.

DELETE/v1/categories/{ref}

Löscht eine Kategorie per UUID oder external_id.

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`ref`	UUID \| string	Pflicht	UUID oder external_id der Kategorie

Beispiel

curl -X DELETE "https://app.priceivy.com/api/v1/categories/elektronik" \
  -H "Authorization: Bearer rp_dein_api_key"

Response (200)

{
  "data": {
    "success": true
  }
}

POST/v1/categories/bulk-upsert

Erstellt oder aktualisiert bis zu 200 Kategorien per external_id in einem Request. Parent-Referenzen innerhalb des Batches werden aufgeloest.

Beispiel

curl -X POST "https://app.priceivy.com/api/v1/categories/bulk-upsert" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "elektronik",
        "name": "Elektronik"
      },
      {
        "external_id": "peripherie",
        "name": "Peripheriegeraete",
        "parent_external_id": "elektronik",
        "attributes": [
          { "key": "idealo_id", "value": "67890" }
        ]
      }
    ]
  }'

Response (200)

{
  "items": [
    {
      "success": true,
      "status": 201,
      "data": {
        "id": "...",
        "organization_id": "...",
        "external_id": "elektronik",
        "name": "Elektronik",
        "parent_id": null,
        "created_at": "2025-01-15T10:30:00.000Z",
        "updated_at": "2025-01-15T10:30:00.000Z",
        "attributes": []
      }
    },
    {
      "success": true,
      "status": 201,
      "data": {
        "id": "...",
        "organization_id": "...",
        "external_id": "peripherie",
        "name": "Peripheriegeraete",
        "parent_id": "...",
        "created_at": "2025-01-15T10:30:00.000Z",
        "updated_at": "2025-01-15T10:30:00.000Z",
        "attributes": [
          { "id": "...", "key": "idealo_id", "value": "67890" }
        ]
      }
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 2,
    "failed": 0
  }
}

Limit: Maximal 200 Items pro Request. Parent-Kategorien koennen im gleichen Batch referenziert werden — sie werden in der Reihenfolge des Arrays verarbeitet.

Struktur-Validierung (422)

Wenn der Request-Body nicht die erwartete Struktur hat:

// items fehlt oder ist kein Array
{
  "error": "items muss als Array gesendet werden"
}

// Array leer oder mehr als 200 Items
{
  "error": "items muss zwischen 1 und 200 Eintraegen enthalten"
}

Item-Validierungsfehler (422)

Alle Items werden vorab validiert — bei Fehlern wird kein Item verarbeitet. Stattdessen werden alle Fehler gesammelt und auf einmal zurueckgegeben:

{
  "error": "1 von 3 Items haben Validierungsfehler",
  "details": {
    "validation_errors": [
      {
        "index": 2,
        "external_id": null,
        "error": "external_id ist erforderlich"
      }
    ]
  }
}

POST/v1/categories/bulk-delete

Loescht bis zu 200 Kategorien per external_id in einem Request. Attributes werden automatisch mitgeloescht. Nicht gefundene external_ids werden mit Fehler markiert.

Beispiel

curl -X POST "https://app.priceivy.com/api/v1/categories/bulk-delete" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ids": ["elektronik", "peripherie", "nicht-vorhanden"]
  }'

Response (200)

{
  "items": [
    { "success": true, "status": 200, "data": { "external_id": "elektronik" } },
    { "success": true, "status": 200, "data": { "external_id": "peripherie" } },
    { "success": false, "status": 404, "error": "Kategorie nicht gefunden" }
  ],
  "summary": {
    "total": 3,
    "succeeded": 2,
    "failed": 1
  },
  "warnings": ["Sub-Daten konnten nicht geloescht werden: org_product_category_attributes"]  // Optional
}

Limit: Maximal 200 external_ids pro Request.

Validierungsfehler-Response (422)

Bei ungueltigem Input wird der Request abgelehnt, bevor Items verarbeitet werden:

// external_ids ist kein Array
{
  "error": "external_ids muss als Array gesendet werden"
}

// Array leer oder mehr als 200 Items
{
  "error": "external_ids muss zwischen 1 und 200 Eintraegen enthalten"
}

// Ein Item ist kein String oder leer (mit Index)
{
  "error": "external_ids[0] muss ein nicht-leerer String sein"
}

Payload-Schema

Das folgende Schema gilt fuer PUT-Requests und Bulk-Upsert Items auf Kategorie-Endpoints.

Strikte Validierung: Unbekannte Felder im Body werden abgelehnt (422). Nur die unten aufgefuehrten Felder sind erlaubt.

Felder

Feld	Typ	Status	Beschreibung
`external_id`	string	Pflicht	Eindeutige externe ID innerhalb der Organisation (z.B. Slug oder Nummer aus deinem System)
`name`	string	Pflicht	Anzeigename der Kategorie
`parent_external_id`	string \| null	Optional	external_id der uebergeordneten Kategorie (fuer Hierarchien)
`attributes`	array	Optional	Array von Key-Value-Paaren fuer zusaetzliche Kennungen. Bei Angabe werden alle bestehenden Attribute ersetzt.

attributes

Struktur der Key-Value-Paare innerhalb des attributes-Arrays.

Feld	Typ	Status	Beschreibung
`key`	string	Pflicht	Schluesselname (z.B. "idealo_id", "google_id")
`value`	string	Pflicht	Wert

Payload-Beispiel

{
  "external_id": "peripherie",
  "name": "Peripheriegeraete",
  "parent_external_id": "elektronik",
  "attributes": [
    { "key": "idealo_id", "value": "67890" },
    { "key": "google_id", "value": "cat-123" }
  ]
}

Hierarchien: Unterkategorien werden ueber parent_external_id verknuepft. Beim Bulk-Upsert koennen Parent-Kategorien im gleichen Batch referenziert werden — sie muessen nur vor ihren Kind-Kategorien im Array stehen.

Response-Formate

Standard-Response (Einzelnes Objekt)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "external_id": "WM-2024",
    "name": "Wireless Maus Pro"
  }
}

Listen-Response (mit Pagination)

{
  "data": [
    { "id": "...", "external_id": "WM-2024", "name": "Wireless Maus Pro" },
    { "id": "...", "external_id": "KB-2024", "name": "Mechanische Tastatur" }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 127
  }
}

Bulk-Response

Bulk-Endpoints verarbeiten jedes Item einzeln und geben eine Zusammenfassung zurueck.

{
  "items": [
    {
      "success": true,
      "status": 201,
      "data": { "id": "...", "external_id": "WM-2024" }
    },
    {
      "success": false,
      "status": 422,
      "error": "Validierungsfehler: ..."
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 1,
    "failed": 1
  },
  "warnings": ["Sub-Daten konnten nicht aktualisiert werden: org_product_prices"]  // Optional
}

Fehler-Response

Einfacher Fehler:

{
  "error": "Beschreibung des Fehlers"
}

Fehler mit Details (z.B. bei Bulk-Validierung):

{
  "error": "2 von 5 Items haben Validierungsfehler",
  "details": {
    "validation_errors": [
      { "index": 0, "external_id": null, "error": "external_id ist erforderlich" }
    ]
  }
}

Delete-Response

{
  "data": {
    "success": true
  }
}

Fehlercodes

Code	Titel	Beschreibung
`400`	Bad Request	Ungueltiges JSON im Request-Body
`401`	Unauthorized	Kein API-Key im Authorization-Header oder Key ist ungueltig
`403`	Forbidden	API-Key ist abgelaufen
`404`	Not Found	Ressource nicht gefunden (Produkt, Kategorie, etc.)
`409`	Conflict	Duplikat — ein Eintrag mit gleicher external_id existiert bereits
`422`	Unprocessable	Validierungsfehler — fehlende Pflichtfelder, unbekannte Felder oder ungueltige Referenzen
`500`	Server Error	Interner Serverfehler — bitte kontaktiere den Support

Fehler-Response Format

Alle Fehler werden als JSON mit einem error Feld zurueckgegeben:

// 422 — Validierungsfehler (Einzel-Endpoint)
{
  "error": "external_id ist erforderlich"
}

// 422 — Validierungsfehler (Bulk mit Details)
{
  "error": "2 von 5 Items haben Validierungsfehler",
  "details": {
    "validation_errors": [
      { "index": 1, "external_id": null, "error": "external_id ist erforderlich" },
      { "index": 3, "external_id": "X", "error": "prices[0].price_type ist ungueltig" }
    ]
  }
}

// 409 — Duplikat
{
  "error": "Produkt mit dieser external_id existiert bereits"
}

// 401 — Nicht autorisiert
{
  "error": "API-Key ist ungueltig"
}

API Dokumentation

Vollstaendige Referenz der Priceivy REST API. Verwalte Produkte, Preise, Kategorien und mehr programmatisch.

Basis

Base URL

https://app.priceivy.com/api/v1

Format

Alle Requests und Responses verwenden application/json

Pagination

Alle Listen-Endpoints verwenden offset-basierte Pagination mit zwei Query-Parametern:

Feld	Typ	Status	Beschreibung
`limit`	integer	Optional	Anzahl Ergebnisse pro Seite. Min: 1, Max: 10.000, Default: 50
`offset`	integer	Optional	Anzahl zu ueberspringender Ergebnisse. Min: 0, Default: 0

Werte ausserhalb des gueltigen Bereichs werden automatisch auf den naechsten gueltigen Wert begrenzt (z.B. limit=15000 wird zu limit=10000).

Die Response enthaelt immer ein pagination Objekt mit limit, offset und total. Ergebnisse werden standardmaessig nach Erstelldatum sortiert (neueste zuerst).

Authentifizierung

Die API verwendet Bearer-Token-Authentifizierung. API-Keys koennen im Dashboard unter Einstellungen → API-Keys erstellt werden.

Format

Alle API-Keys beginnen mit dem Prefix rp_

Header

Authorization: Bearer rp_dein_api_key

Sicherheitshinweis: API-Keys werden als SHA256-Hash gespeichert. Der vollstaendige Key wird nur bei der Erstellung einmalig angezeigt. Bewahre ihn sicher auf.

Auth-Fehlercodes

Code	Beschreibung
`401`	Kein API-Key im Header oder Key ungueltig / nicht gefunden
`403`	API-Key ist abgelaufen

Produkte

GET/v1/products

Gibt eine paginierte Liste aller Produkte zurueck, inklusive aller Sub-Daten (Preise, Bilder, Identifier, Attribute, Kategorien).

Query-Parameter

Feld	Typ	Status	Beschreibung
`limit`	integer	Optional	Ergebnisse pro Seite (1–10.000, Default: 50)
`offset`	integer	Optional	Anzahl zu ueberspringender Ergebnisse (Default: 0)

Beispiel

curl -X GET "https://app.priceivy.com/api/v1/products?limit=50&offset=0" \
  -H "Authorization: Bearer rp_dein_api_key"

Response (200)

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organization_id": "...",
      "external_id": "WM-2024",
      "sku": "WM-2024",
      "name": "Wireless Maus Pro",
      "gtin": "4012345678901",
      "import_excluded": false,
      "export_excluded": false,
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z",
      "prices": [...],
      "images": [...],
      "identifiers": [...],
      "attributes": [...],
      "categories": [...]
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 127
  }
}

GET/v1/products/{external_id}

Gibt ein einzelnes Produkt per external_id zurueck, inklusive aller Sub-Daten.

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`external_id`	string	Pflicht	Eindeutige external_id des Produkts (URL-encoded)

Beispiel

curl -X GET "https://app.priceivy.com/api/v1/products/WM-2024" \
  -H "Authorization: Bearer rp_dein_api_key"

Response (200)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "...",
    "external_id": "WM-2024",
    "sku": "WM-2024",
    "name": "Wireless Maus Pro",
    "gtin": "4012345678901",
    "import_excluded": false,
    "export_excluded": false,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "prices": [...],
    "images": [...],
    "identifiers": [...],
    "attributes": [...],
    "categories": [...]
  }
}

PUT/v1/products/{external_id}

Idempotenter Upsert per external_id. Erstellt das Produkt falls es nicht existiert (201) oder aktualisiert es (200). Alle Sub-Ressourcen werden bei Angabe vollstaendig ersetzt (Replace-All).

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`external_id`	string	Pflicht	external_id des Produkts (URL-encoded)

Beispiel

curl -X PUT "https://app.priceivy.com/api/v1/products/WM-2024" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wireless Maus Pro v2",
    "sku": "WM-2024-V2",
    "prices": [
      {
        "price_type": "vk_current",
        "price_net": 2499,
        "price_gross": 2974
      }
    ],
    "images": [
      {
        "url": "https://example.com/maus-pro-v2.jpg",
        "sort": 0
      }
    ]
  }'

Response (200 oder 201)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "...",
    "external_id": "WM-2024",
    "sku": "WM-2024-V2",
    "name": "Wireless Maus Pro v2",
    "gtin": null,
    "import_excluded": false,
    "export_excluded": false,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-16T08:00:00.000Z",
    "prices": [...],
    "images": [...],
    "identifiers": [...],
    "attributes": [...],
    "categories": [...]
  }
}

Hinweis: Bei Angabe von prices, images, identifiers oder attributes werden alle bestehenden Eintraege ersetzt (Replace-All).

import_excluded: Wenn das Produkt import_excluded = true hat, gibt dieser Endpoint 403 zurueck. Geschuetzte Produkte koennen nur direkt im Backend geaendert werden.

DELETE/v1/products/{external_id}

Loescht ein Produkt per external_id.

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`external_id`	string	Pflicht	external_id des Produkts (URL-encoded)

Beispiel

curl -X DELETE "https://app.priceivy.com/api/v1/products/WM-2024" \
  -H "Authorization: Bearer rp_dein_api_key"

Response (200)

{
  "data": {
    "success": true
  }
}

import_excluded: Wenn das Produkt import_excluded = true hat, gibt dieser Endpoint 403 zurueck. Geschuetzte Produkte koennen nur direkt im Backend geloescht werden.

POST/v1/products/bulk-upsert

Erstellt oder aktualisiert bis zu 10.000 Produkte per external_id in einem Request. Alle Items werden vorab validiert — bei Fehlern wird kein Item verarbeitet.

Query-Parameter

Feld	Typ	Status	Beschreibung
`response_mode`	string	Optional	"full" = vollstaendige Produktdaten pro Item (Default bei ≤500 Items). "summary" = nur Zusammenfassung + Fehler-Liste (Default bei >500 Items).

Beispiel

curl -X POST "https://app.priceivy.com/api/v1/products/bulk-upsert" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "WM-2024",
        "name": "Wireless Maus Pro",
        "sku": "WM-PRO-2024",
        "prices": [
          { "price_type": "vk_current", "price_net": 1999, "price_gross": 2379 }
        ]
      },
      {
        "external_id": "KB-2024",
        "name": "Mechanische Tastatur"
      }
    ]
  }'

Response — Full Mode (200)

Enthaelt vollstaendige Produktdaten pro Item. Default bei ≤500 Items.

{
  "items": [
    {
      "success": true,
      "status": 201,
      "data": { "id": "...", "external_id": "WM-2024", "name": "Wireless Maus Pro", ... }
    },
    {
      "success": true,
      "status": 200,
      "data": { "id": "...", "external_id": "KB-2024", "name": "Mechanische Tastatur", ... }
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 2,
    "failed": 0
  },
  "warnings": ["Sub-Daten konnten nicht aktualisiert werden: org_product_prices"]  // Optional
}

Response — Summary Mode (200)

Nur Zusammenfassung ohne Einzeldaten. Default bei >500 Items. Die Summary enthaelt hier eine detailliertere Aufschluesselung mit created und updated statt succeeded.

{
  "summary": {
    "total": 10000,
    "created": 8500,
    "updated": 1450,
    "failed": 50
  },
  "errors": [
    { "external_id": "DEFEKT-001", "error": "Unbekannte category_external_id: xyz" }
  ],
  "warnings": ["Sub-Daten konnten nicht aktualisiert werden: org_product_prices"]  // Optional
}

Struktur-Validierung (422)

Wenn der Request-Body nicht die erwartete Struktur hat:

// items fehlt oder ist kein Array
{
  "error": "items muss als Array gesendet werden"
}

// Array leer oder mehr als 10.000 Items
{
  "error": "items muss zwischen 1 und 10000 Eintraegen enthalten"
}

Item-Validierungsfehler (422)

Alle Items werden vorab validiert. Bei Fehlern wird kein Item verarbeitet — stattdessen werden alle Fehler gesammelt und auf einmal zurueckgegeben:

{
  "error": "2 von 5 Items haben Validierungsfehler",
  "details": {
    "validation_errors": [
      {
        "index": 1,
        "external_id": null,
        "error": "external_id ist erforderlich"
      },
      {
        "index": 3,
        "external_id": "X",
        "error": "prices[0].price_type ist ungueltig"
      }
    ]
  }
}

import_excluded: Items, deren bestehendes Produkt import_excluded = true hat, werden mit Status 403 markiert und uebersprungen. Alle anderen Items werden normal verarbeitet.

POST/v1/products/bulk-delete

Loescht bis zu 10.000 Produkte per external_id in einem Request. Nicht gefundene external_ids werden mit Fehler markiert.

Beispiel

curl -X POST "https://app.priceivy.com/api/v1/products/bulk-delete" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ids": ["WM-2024", "KB-2024", "NICHT-VORHANDEN"]
  }'

Response — Full Mode (200)

Enthaelt Einzelergebnisse pro Item. Default bei ≤500 Items.

{
  "items": [
    { "success": true, "status": 200, "data": { "external_id": "WM-2024" } },
    { "success": true, "status": 200, "data": { "external_id": "KB-2024" } },
    { "success": false, "status": 404, "error": "Produkt nicht gefunden" }
  ],
  "summary": {
    "total": 3,
    "succeeded": 2,
    "failed": 1
  },
  "warnings": ["Sub-Daten konnten nicht geloescht werden: org_product_prices"]  // Optional
}

Response — Summary Mode (200)

Nur Zusammenfassung ohne Einzelergebnisse. Default bei >500 Items.

{
  "summary": {
    "total": 10000,
    "succeeded": 9999,
    "failed": 1
  },
  "errors": [
    { "external_id": "prod-999", "error": "Produkt nicht gefunden" }
  ],
  "warnings": ["Sub-Daten konnten nicht geloescht werden: org_product_prices"]  // Optional
}

Limit: Maximal 10.000 external_ids pro Request. Ab 500 Items wird automatisch nur eine Summary zurueckgegeben.

import_excluded: Produkte mit import_excluded = true werden mit Status 403 markiert und nicht geloescht. Alle anderen Produkte werden normal verarbeitet.

Validierungsfehler-Response (422)

Bei ungueltigem Input wird der Request abgelehnt, bevor Items verarbeitet werden:

// external_ids ist kein Array
{
  "error": "external_ids muss als Array gesendet werden"
}

// Array leer oder mehr als 10.000 Items
{
  "error": "external_ids muss zwischen 1 und 10000 Eintraegen enthalten"
}

// Ein Item ist kein String oder leer (mit Index)
{
  "error": "external_ids[0] muss ein nicht-leerer String sein"
}

Payload-Schema

Das folgende Schema gilt fuer PUT-Requests und Bulk-Upsert Items auf Produkt-Endpoints.

Strikte Validierung: Unbekannte Felder im Body werden abgelehnt (422). Nur die unten aufgefuehrten Felder sind erlaubt.

Basis-Felder

Feld	Typ	Status	Beschreibung
`external_id`	string	Pflicht	Eindeutige ID aus deinem System (bei Bulk-Upsert im Item, bei PUT im Pfad)
`sku`	string \| null	Optional	Optionale Artikelnummer (SKU)
`name`	string \| null	Optional	Produktname
`gtin`	string \| null	Optional	GTIN / Barcode

prices

Array von Preis-Objekten. Bei Angabe werden alle bestehenden Preise ersetzt.

Feld	Typ	Status	Beschreibung
`price_type`	string	Pflicht	Preistyp — Kern-Typen: "ek_avg" (Durchschnittlicher EK), "vk_current" (Aktueller VK). Die Kern-Typen werden hauptsaechlich zur Auswertung und Anzeige im Dashboard verwendet. Eigene Typen erlaubt (z.B. "uvp", "min", "ek_best"). Max. 50 Zeichen.
`price_net`	integer	Pflicht	Nettopreis in Cent, nicht-negative Ganzzahl (z.B. 2499 fuer 24,99 EUR)
`price_gross`	integer	Pflicht	Bruttopreis in Cent, nicht-negative Ganzzahl (z.B. 2974 fuer 29,74 EUR)

images

Array von Bild-Objekten. Bei Angabe werden alle bestehenden Bilder ersetzt.

Feld	Typ	Status	Beschreibung
`url`	string	Pflicht	URL des Bildes
`sort`	number	Optional	Sortierreihenfolge (Default: Array-Index)

identifiers

Array von Key-Value-Paaren fuer zusaetzliche Produktkennungen. Bei Angabe werden alle bestehenden Identifier ersetzt. Eigene Keys sind weiterhin erlaubt.

Die folgenden Kern-Identifier werden von Priceivy zum automatischen Scraping verwendet (Preisvergleich auf Marktplaetzen wie Amazon, Idealo, eBay etc.).

Key	Beschreibung
`asin`	Amazon Standard Identification Number
`isbn`	International Standard Book Number
`mpn`	Manufacturer Part Number (Herstellernummer)

Feld	Typ	Status	Beschreibung
`key`	string	Pflicht	Schluessel — Kern-Keys: "asin", "isbn", "mpn". Eigene Keys sind ebenfalls erlaubt.
`value`	string	Pflicht	Wert

attributes

Array von Key-Value-Paaren fuer Produkteigenschaften (z.B. Farbe, Gewicht). Bei Angabe werden alle bestehenden Attribute ersetzt.

Feld	Typ	Status	Beschreibung
`key`	string	Pflicht	Schluessel (z.B. "farbe", "gewicht", "material")
`value`	string	Pflicht	Wert

exclusions

Steuert, ob ein Produkt vom Import oder Export ausgeschlossen wird. Sende null um beide Flags auf false zurueckzusetzen.

Feld	Typ	Status	Beschreibung
`import`	boolean	Optional	Produkt vom Import ausschliessen
`export`	boolean	Optional	Produkt vom Export ausschliessen

category_external_ids

Array von externen Kategorie-IDs. Bei Angabe werden alle bestehenden Kategorie-Zuordnungen ersetzt. Die Kategorien muessen vorher ueber den Kategorien-Endpoint erstellt werden.

Feld	Typ	Status	Beschreibung
`category_external_ids`	string[]	Optional	Array von externen Kategorie-IDs
`category_ids`	string[]	Optional	Alternativ: Array von Kategorie-UUIDs

Wichtig: category_ids und category_external_ids koennen nicht gleichzeitig in einem Request verwendet werden.

Update-Verhalten bei Sub-Ressourcen (prices, images, identifiers, attributes, categories):

Feld weglassen — bestehende Daten bleiben unveraendert
Leeres Array senden ([]) — alle bestehenden Eintraege werden geloescht
Array mit Daten senden — bestehende Eintraege werden komplett ersetzt (Replace-All)

Vollstaendiges Payload-Beispiel

{
  "external_id": "WM-2024",
  "sku": "WM-PRO-2024",
  "name": "Wireless Maus Pro",
  "gtin": "4012345678901",
  "prices": [
    {
      "price_type": "vk_current",
      "price_net": 1999,
      "price_gross": 2379
    },
    {
      "price_type": "ek_avg",
      "price_net": 850,
      "price_gross": 1012
    }
  ],
  "images": [
    { "url": "https://example.com/maus-front.jpg", "sort": 0 },
    { "url": "https://example.com/maus-side.jpg", "sort": 1 }
  ],
  "identifiers": [
    { "key": "mpn", "value": "WM-PRO-2024" },
    { "key": "asin", "value": "B0XXXXXXXXX" }
  ],
  "attributes": [
    { "key": "farbe", "value": "Schwarz" },
    { "key": "gewicht", "value": "85g" }
  ],
  "exclusions": {
    "import": false,
    "export": false
  },
  "category_external_ids": ["elektronik", "peripherie"]
}

Kategorien

Kategorien ermoeglichen die hierarchische Organisation deiner Produkte. Jede Kategorie wird ueber eine eindeutige external_id pro Organisation identifiziert.

GET/v1/categories

Gibt eine paginierte Liste aller Kategorien zurueck, inklusive Attributes.

Query-Parameter

Feld	Typ	Status	Beschreibung
`limit`	integer	Optional	Ergebnisse pro Seite (1–10.000, Default: 50)
`offset`	integer	Optional	Anzahl zu ueberspringender Ergebnisse (Default: 0)

Beispiel

curl -X GET "https://app.priceivy.com/api/v1/categories?limit=50&offset=0" \
  -H "Authorization: Bearer rp_dein_api_key"

Response (200)

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organization_id": "...",
      "external_id": "elektronik",
      "name": "Elektronik",
      "parent_id": null,
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z",
      "attributes": [
        { "id": "...", "key": "idealo_id", "value": "12345" }
      ]
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 12
  }
}

GET/v1/categories/{ref}

Gibt eine einzelne Kategorie per UUID oder external_id zurueck, inklusive Attributes.

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`ref`	UUID \| string	Pflicht	UUID oder external_id der Kategorie

Beispiel

curl -X GET "https://app.priceivy.com/api/v1/categories/elektronik" \
  -H "Authorization: Bearer rp_dein_api_key"

Response (200)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "...",
    "external_id": "elektronik",
    "name": "Elektronik",
    "parent_id": null,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "attributes": []
  }
}

PUT/v1/categories/{ref}

Idempotenter Upsert einer Kategorie per UUID oder external_id. Erstellt die Kategorie falls sie nicht existiert (201) oder aktualisiert sie (200). Attributes werden bei Angabe vollstaendig ersetzt.

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`ref`	UUID \| string	Pflicht	UUID oder external_id der Kategorie

Beispiel

curl -X PUT "https://app.priceivy.com/api/v1/categories/elektronik" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "elektronik",
    "name": "Elektronik & Zubehoer",
    "attributes": [
      { "key": "idealo_id", "value": "12345" }
    ]
  }'

Response (200 oder 201)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "...",
    "external_id": "elektronik",
    "name": "Elektronik & Zubehoer",
    "parent_id": null,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-16T08:00:00.000Z",
    "attributes": [
      { "id": "...", "key": "idealo_id", "value": "12345" }
    ]
  }
}

DELETE/v1/categories/{ref}

Löscht eine Kategorie per UUID oder external_id.

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`ref`	UUID \| string	Pflicht	UUID oder external_id der Kategorie

Beispiel

curl -X DELETE "https://app.priceivy.com/api/v1/categories/elektronik" \
  -H "Authorization: Bearer rp_dein_api_key"

Response (200)

{
  "data": {
    "success": true
  }
}

POST/v1/categories/bulk-upsert

Erstellt oder aktualisiert bis zu 200 Kategorien per external_id in einem Request. Parent-Referenzen innerhalb des Batches werden aufgeloest.

Beispiel

curl -X POST "https://app.priceivy.com/api/v1/categories/bulk-upsert" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "elektronik",
        "name": "Elektronik"
      },
      {
        "external_id": "peripherie",
        "name": "Peripheriegeraete",
        "parent_external_id": "elektronik",
        "attributes": [
          { "key": "idealo_id", "value": "67890" }
        ]
      }
    ]
  }'

Response (200)

{
  "items": [
    {
      "success": true,
      "status": 201,
      "data": {
        "id": "...",
        "organization_id": "...",
        "external_id": "elektronik",
        "name": "Elektronik",
        "parent_id": null,
        "created_at": "2025-01-15T10:30:00.000Z",
        "updated_at": "2025-01-15T10:30:00.000Z",
        "attributes": []
      }
    },
    {
      "success": true,
      "status": 201,
      "data": {
        "id": "...",
        "organization_id": "...",
        "external_id": "peripherie",
        "name": "Peripheriegeraete",
        "parent_id": "...",
        "created_at": "2025-01-15T10:30:00.000Z",
        "updated_at": "2025-01-15T10:30:00.000Z",
        "attributes": [
          { "id": "...", "key": "idealo_id", "value": "67890" }
        ]
      }
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 2,
    "failed": 0
  }
}

Limit: Maximal 200 Items pro Request. Parent-Kategorien koennen im gleichen Batch referenziert werden — sie werden in der Reihenfolge des Arrays verarbeitet.

Struktur-Validierung (422)

Wenn der Request-Body nicht die erwartete Struktur hat:

// items fehlt oder ist kein Array
{
  "error": "items muss als Array gesendet werden"
}

// Array leer oder mehr als 200 Items
{
  "error": "items muss zwischen 1 und 200 Eintraegen enthalten"
}

Item-Validierungsfehler (422)

Alle Items werden vorab validiert — bei Fehlern wird kein Item verarbeitet. Stattdessen werden alle Fehler gesammelt und auf einmal zurueckgegeben:

{
  "error": "1 von 3 Items haben Validierungsfehler",
  "details": {
    "validation_errors": [
      {
        "index": 2,
        "external_id": null,
        "error": "external_id ist erforderlich"
      }
    ]
  }
}

POST/v1/categories/bulk-delete

Loescht bis zu 200 Kategorien per external_id in einem Request. Attributes werden automatisch mitgeloescht. Nicht gefundene external_ids werden mit Fehler markiert.

Beispiel

curl -X POST "https://app.priceivy.com/api/v1/categories/bulk-delete" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ids": ["elektronik", "peripherie", "nicht-vorhanden"]
  }'

Response (200)

{
  "items": [
    { "success": true, "status": 200, "data": { "external_id": "elektronik" } },
    { "success": true, "status": 200, "data": { "external_id": "peripherie" } },
    { "success": false, "status": 404, "error": "Kategorie nicht gefunden" }
  ],
  "summary": {
    "total": 3,
    "succeeded": 2,
    "failed": 1
  },
  "warnings": ["Sub-Daten konnten nicht geloescht werden: org_product_category_attributes"]  // Optional
}

Limit: Maximal 200 external_ids pro Request.

Validierungsfehler-Response (422)

Bei ungueltigem Input wird der Request abgelehnt, bevor Items verarbeitet werden:

// external_ids ist kein Array
{
  "error": "external_ids muss als Array gesendet werden"
}

// Array leer oder mehr als 200 Items
{
  "error": "external_ids muss zwischen 1 und 200 Eintraegen enthalten"
}

// Ein Item ist kein String oder leer (mit Index)
{
  "error": "external_ids[0] muss ein nicht-leerer String sein"
}

Payload-Schema

Das folgende Schema gilt fuer PUT-Requests und Bulk-Upsert Items auf Kategorie-Endpoints.

Strikte Validierung: Unbekannte Felder im Body werden abgelehnt (422). Nur die unten aufgefuehrten Felder sind erlaubt.

Felder

Feld	Typ	Status	Beschreibung
`external_id`	string	Pflicht	Eindeutige externe ID innerhalb der Organisation (z.B. Slug oder Nummer aus deinem System)
`name`	string	Pflicht	Anzeigename der Kategorie
`parent_external_id`	string \| null	Optional	external_id der uebergeordneten Kategorie (fuer Hierarchien)
`attributes`	array	Optional	Array von Key-Value-Paaren fuer zusaetzliche Kennungen. Bei Angabe werden alle bestehenden Attribute ersetzt.

attributes

Struktur der Key-Value-Paare innerhalb des attributes-Arrays.

Feld	Typ	Status	Beschreibung
`key`	string	Pflicht	Schluesselname (z.B. "idealo_id", "google_id")
`value`	string	Pflicht	Wert

Payload-Beispiel

{
  "external_id": "peripherie",
  "name": "Peripheriegeraete",
  "parent_external_id": "elektronik",
  "attributes": [
    { "key": "idealo_id", "value": "67890" },
    { "key": "google_id", "value": "cat-123" }
  ]
}

Response-Formate

Standard-Response (Einzelnes Objekt)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "external_id": "WM-2024",
    "name": "Wireless Maus Pro"
  }
}

Listen-Response (mit Pagination)

{
  "data": [
    { "id": "...", "external_id": "WM-2024", "name": "Wireless Maus Pro" },
    { "id": "...", "external_id": "KB-2024", "name": "Mechanische Tastatur" }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 127
  }
}

Bulk-Response

Bulk-Endpoints verarbeiten jedes Item einzeln und geben eine Zusammenfassung zurueck.

{
  "items": [
    {
      "success": true,
      "status": 201,
      "data": { "id": "...", "external_id": "WM-2024" }
    },
    {
      "success": false,
      "status": 422,
      "error": "Validierungsfehler: ..."
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 1,
    "failed": 1
  },
  "warnings": ["Sub-Daten konnten nicht aktualisiert werden: org_product_prices"]  // Optional
}

Fehler-Response

Einfacher Fehler:

{
  "error": "Beschreibung des Fehlers"
}

Fehler mit Details (z.B. bei Bulk-Validierung):

{
  "error": "2 von 5 Items haben Validierungsfehler",
  "details": {
    "validation_errors": [
      { "index": 0, "external_id": null, "error": "external_id ist erforderlich" }
    ]
  }
}

Delete-Response

{
  "data": {
    "success": true
  }
}

Fehlercodes

Code	Titel	Beschreibung
`400`	Bad Request	Ungueltiges JSON im Request-Body
`401`	Unauthorized	Kein API-Key im Authorization-Header oder Key ist ungueltig
`403`	Forbidden	API-Key ist abgelaufen
`404`	Not Found	Ressource nicht gefunden (Produkt, Kategorie, etc.)
`409`	Conflict	Duplikat — ein Eintrag mit gleicher external_id existiert bereits
`422`	Unprocessable	Validierungsfehler — fehlende Pflichtfelder, unbekannte Felder oder ungueltige Referenzen
`500`	Server Error	Interner Serverfehler — bitte kontaktiere den Support

Fehler-Response Format

Alle Fehler werden als JSON mit einem error Feld zurueckgegeben:

// 422 — Validierungsfehler (Einzel-Endpoint)
{
  "error": "external_id ist erforderlich"
}

// 422 — Validierungsfehler (Bulk mit Details)
{
  "error": "2 von 5 Items haben Validierungsfehler",
  "details": {
    "validation_errors": [
      { "index": 1, "external_id": null, "error": "external_id ist erforderlich" },
      { "index": 3, "external_id": "X", "error": "prices[0].price_type ist ungueltig" }
    ]
  }
}

// 409 — Duplikat
{
  "error": "Produkt mit dieser external_id existiert bereits"
}

// 401 — Nicht autorisiert
{
  "error": "API-Key ist ungueltig"
}