API Dokumentation

Vollständige 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: 200, Default: 50
`offset`	integer	Optional	Anzahl zu überspringender Ergebnisse. Min: 0, Default: 0

Die Response enthält immer ein pagination Objekt mit limit, offset und total.

Soft-Delete

Alle DELETE-Operationen führen ein Soft-Delete durch: Der Datensatz wird nicht physisch gelöscht, sondern das Feld deleted_at wird auf den aktuellen Zeitstempel gesetzt. Gelöschte Datensätze erscheinen nicht mehr in Listen-Abfragen.

Authentifizierung

Die API verwendet Bearer-Token-Authentifizierung. API-Keys können 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 vollständige Key wird nur bei der Erstellung einmalig angezeigt. Bewahre ihn sicher auf.

Auth-Fehlercodes

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

Products

Die Product-Endpoints ermöglichen das vollständige Management deiner Produkte — inklusive Preise, Bilder, Identifier, Attribute und Kategorie-Zuordnungen.

GET/v1/products

Gibt eine paginierte Liste aller Produkte zurück.

Query-Parameter

Feld	Typ	Status	Beschreibung
`limit`	integer	Optional	Ergebnisse pro Seite (1–200, Default: 50)
`offset`	integer	Optional	Anzahl zu überspringender 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",
      "sku": "WM-2024",
      "name": "Wireless Maus Pro",
      "ean": "4012345678901"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 127
  }
}

POST/v1/products?sku={sku}

Erstellt ein neues Produkt mit der angegebenen SKU. Die SKU muss als Query-Parameter übergeben werden und darf noch nicht existieren.

Query-Parameter

Feld	Typ	Status	Beschreibung
`sku`	string	Pflicht	Eindeutige SKU des Produkts

Beispiel

curl -X POST "https://app.priceivy.com/api/v1/products?sku=WM-2024" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wireless Maus Pro",
    "ean": "4012345678901",
    "prices": [
      {
        "price_type": "vk",
        "price_net": 19.99,
        "price_gross": 23.79
      }
    ]
  }'

Response (201)

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

GET/v1/products/{id}

Gibt ein einzelnes Produkt per UUID zurück, inklusive aller verknüpften Preise, Bilder, Identifier und Attribute.

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`id`	UUID	Pflicht	Produkt-UUID

Beispiel

curl -X GET "https://app.priceivy.com/api/v1/products/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer rp_dein_api_key"

Response (200)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "sku": "WM-2024",
    "name": "Wireless Maus Pro",
    "ean": "4012345678901",
    "prices": [...],
    "images": [...],
    "identifiers": [...],
    "attributes": [...]
  }
}

PUT/v1/products/{sku}

Idempotenter Upsert per SKU. Erstellt das Produkt falls es nicht existiert (201) oder aktualisiert es (200). Alle Sub-Ressourcen (Preise, Bilder, etc.) werden bei Angabe vollständig ersetzt.

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`sku`	string	Pflicht	SKU des Produkts

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",
    "prices": [
      {
        "price_type": "vk",
        "price_net": 24.99,
        "price_gross": 29.74
      }
    ],
    "images": [
      {
        "url": "https://example.com/maus-pro-v2.jpg",
        "sort": 0
      }
    ]
  }'

Response (200 oder 201)

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

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

PATCH/v1/products/{id}

Teilupdate eines Produkts per UUID. Nur die übergebenen Felder werden aktualisiert. Sub-Ressourcen (Preise, Bilder, etc.) werden bei Angabe vollständig ersetzt.

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`id`	UUID	Pflicht	Produkt-UUID

Beispiel

curl -X PATCH "https://app.priceivy.com/api/v1/products/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wireless Maus Pro (aktualisiert)"
  }'

Response (200)

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

DELETE/v1/products/{id}

Soft-Delete eines Produkts per UUID. Das Produkt wird nicht physisch gelöscht, sondern mit einem deleted_at Timestamp versehen.

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`id`	UUID	Pflicht	Produkt-UUID

Beispiel

curl -X DELETE "https://app.priceivy.com/api/v1/products/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer rp_dein_api_key"

Response (200)

{
  "success": true
}

POST/v1/products/bulk-upsert

Erstellt oder aktualisiert bis zu 100 Produkte in einem Request per SKU. Jedes Item wird einzeln verarbeitet — Fehler bei einem Item stoppen nicht die anderen.

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": [
      {
        "sku": "WM-2024",
        "name": "Wireless Maus Pro",
        "prices": [
          { "price_type": "vk", "price_net": 19.99, "price_gross": 23.79 }
        ]
      },
      {
        "sku": "KB-2024",
        "name": "Mechanische Tastatur"
      }
    ]
  }'

Response (200)

{
  "items": [
    {
      "sku": "WM-2024",
      "success": true,
      "status": 201,
      "data": { "id": "...", "sku": "WM-2024", "name": "Wireless Maus Pro" }
    },
    {
      "sku": "KB-2024",
      "success": true,
      "status": 200,
      "data": { "id": "...", "sku": "KB-2024", "name": "Mechanische Tastatur" }
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 2,
    "failed": 0
  }
}

Limit: Maximal 100 Items pro Request. Jedes Item benötigt ein sku Feld. Status 201 = neu erstellt, 200 = aktualisiert.

POST/v1/products/bulk-delete

Soft-Delete von bis zu 100 Produkten per SKU in einem Request. Nicht gefundene SKUs 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 '{
    "skus": ["WM-2024", "KB-2024", "NICHT-VORHANDEN"]
  }'

Response (200)

{
  "items": [
    { "sku": "WM-2024", "success": true, "status": 200 },
    { "sku": "KB-2024", "success": true, "status": 200 },
    { "sku": "NICHT-VORHANDEN", "success": false, "status": 404, "error": "Produkt nicht gefunden" }
  ],
  "summary": {
    "total": 3,
    "succeeded": 2,
    "failed": 1
  }
}

Limit: Maximal 100 SKUs pro Request.

Produkt-Payload

Das folgende Schema gilt für POST, PUT und PATCH Requests auf Product-Endpoints. Bei PATCH sind alle Felder optional.

Basis-Felder

Feld	Typ	Status	Beschreibung
`name`	string \| null	Optional	Produktname
`ean`	string \| null	Optional	EAN / GTIN Barcode

prices

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

Feld	Typ	Status	Beschreibung
`price_type`	string	Pflicht	Preistyp: "ek" (Einkauf), "vk" (Verkauf), "uvp" (UVP), "min" (Mindestpreis)
`price_net`	number	Pflicht	Nettopreis
`price_gross`	number	Pflicht	Bruttopreis
`currency_iso3`	string	Optional	ISO 4217 Währungscode (Default: "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 für zusätzliche Produktkennungen (z.B. MPN, ISBN). Bei Angabe werden alle bestehenden Identifier ersetzt.

Feld	Typ	Status	Beschreibung
`key`	string	Pflicht	Schlüssel (z.B. "mpn", "isbn", "asin")
`value`	string	Pflicht	Wert

attributes

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

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

exclusions

Steuert, ob ein Produkt vom Import oder Export ausgeschlossen wird.

Feld	Typ	Status	Beschreibung
`import`	boolean	Optional	Produkt vom Import ausschließen
`export`	boolean	Optional	Produkt vom Export ausschließen

Kategorie-Zuordnung

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

Wichtig: category_ids und category_external_ids können nicht gleichzeitig in einem Request verwendet werden. Nutze entweder UUIDs oder externe IDs.

Vollständiges Payload-Beispiel

{
  "name": "Wireless Maus Pro",
  "ean": "4012345678901",
  "prices": [
    {
      "price_type": "vk",
      "price_net": 19.99,
      "price_gross": 23.79,
      "currency_iso3": "EUR"
    },
    {
      "price_type": "ek",
      "price_net": 8.50,
      "price_gross": 10.12
    }
  ],
  "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"]
}

Response-Formate

Standard-Response (Einzelnes Objekt)

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

Listen-Response (mit Pagination)

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

Bulk-Response

Bulk-Endpoints verarbeiten jedes Item einzeln und geben eine Zusammenfassung zurück.

{
  "items": [
    {
      "sku": "WM-2024",
      "success": true,
      "status": 201,
      "data": { "id": "...", "sku": "WM-2024" }
    },
    {
      "sku": "INVALID",
      "success": false,
      "status": 422,
      "error": "Validierungsfehler: ..."
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 1,
    "failed": 1
  }
}

Fehler-Response

{
  "error": "Beschreibung des Fehlers"
}

Delete-Response

{
  "success": true
}

Generische Ressourcen

Neben den spezialisierten Product-Endpoints bietet die API generische CRUD-Operationen für weitere Ressourcen. Alle folgen dem gleichen Muster:

Verfügbare Operationen

GET/v1/{resource}— Liste mit Pagination

GET/v1/{resource}/{id}— Einzelner Eintrag per UUID

POST/v1/{resource}— Neuen Eintrag erstellen

PATCH/v1/{resource}/{id}— Eintrag teilweise aktualisieren

DELETE/v1/{resource}/{id}— Soft-Delete per UUID

Beispiel: Eintrag erstellen

curl -X POST "https://app.priceivy.com/api/v1/platforms" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "marketplace",
    "name": "Amazon DE",
    "provider": "amazon"
  }'

platforms

/v1/platforms

Feld	Typ	Status	Beschreibung
`type`	string	Pflicht	Plattformtyp (z.B. marketplace, shop)
`name`	string	Pflicht	Anzeigename der Plattform
`provider`	string	Pflicht	Provider-Kennung (z.B. amazon, idealo, ebay)

product-prices

/v1/product-prices

Feld	Typ	Status	Beschreibung
`org_product_id`	UUID	Pflicht	Referenz auf das Produkt
`price_type`	string	Pflicht	Preistyp: "ek", "vk", "uvp", "min"
`price_net`	number	Pflicht	Nettopreis
`price_gross`	number	Pflicht	Bruttopreis
`currency_rate_id`	UUID	Optional	Referenz auf Währungskurs (Default: EUR)

product-images

/v1/product-images

Feld	Typ	Status	Beschreibung
`org_product_id`	UUID	Pflicht	Referenz auf das Produkt
`url`	string	Pflicht	URL des Bildes
`sort`	number	Optional	Sortierreihenfolge

product-identifiers

/v1/product-identifiers

Feld	Typ	Status	Beschreibung
`org_product_id`	UUID	Pflicht	Referenz auf das Produkt
`key`	string	Pflicht	Identifier-Schlüssel (z.B. mpn, isbn, asin)
`value`	string	Pflicht	Identifier-Wert

product-attributes

/v1/product-attributes

Feld	Typ	Status	Beschreibung
`org_product_id`	UUID	Pflicht	Referenz auf das Produkt
`key`	string	Pflicht	Attribut-Schlüssel (z.B. farbe, gewicht)
`value`	string	Pflicht	Attribut-Wert

Feld	Typ	Status	Beschreibung
`name`	string	Pflicht	Kategoriename
`external_id`	string	Pflicht	Externe ID (Pflichtfeld, wird für category_external_ids Referenzen verwendet)
`parent_id`	UUID	Optional	UUID der übergeordneten Kategorie (für Hierarchien)

category-identifiers

/v1/category-identifiers

Feld	Typ	Status	Beschreibung
`org_product_category_id`	UUID	Pflicht	Referenz auf die Kategorie
`key`	string	Pflicht	Identifier-Schlüssel
`value`	string	Pflicht	Identifier-Wert

category-mappings

/v1/category-mappings

Feld	Typ	Status	Beschreibung
`org_product_id`	UUID	Pflicht	Referenz auf das Produkt
`org_product_category_id`	UUID	Pflicht	Referenz auf die Kategorie

Kategorien

Kategorien erfordern immer eine external_id — diese wird als eindeutige Referenz innerhalb deiner Organisation verwendet und ermöglicht die Zuordnung via category_external_ids im Product-Payload.

Kategorie erstellen

curl -X POST "https://app.priceivy.com/api/v1/categories" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Elektronik",
    "external_id": "elektronik"
  }'

Unterkategorie erstellen

curl -X POST "https://app.priceivy.com/api/v1/categories" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Peripheriegeräte",
    "external_id": "peripherie",
    "parent_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Zuordnung zu Produkten

Produkte können auf zwei Arten Kategorien zugeordnet werden:

Option 1: Per UUID

{
  "category_ids": [
    "550e8400-e29b-41d4-..."
  ]
}

Option 2: Per External ID

{
  "category_external_ids": [
    "elektronik",
    "peripherie"
  ]
}

Alternativ kann die Zuordnung auch über den category-mappings Ressourcen-Endpoint verwaltet werden.

Fehlercodes

Code	Titel	Beschreibung
`400`	Bad Request	Ungültiges JSON im Request-Body
`401`	Unauthorized	Kein API-Key im Authorization-Header oder Key ist ungültig
`403`	Forbidden	API-Key ist abgelaufen
`404`	Not Found	Ressource nicht gefunden oder nicht unterstützter Ressourcen-Typ
`409`	Conflict	Duplikat — ein Eintrag mit gleicher SKU oder Unique-Constraint existiert bereits
`422`	Unprocessable	Validierungsfehler — fehlende Pflichtfelder, unbekannte Felder, ungültiges UUID-Format oder ungültige Referenzen
`500`	Server Error	Interner Serverfehler — bitte kontaktiere den Support

Fehler-Response Format

Alle Fehler werden als JSON mit einem error Feld zurückgegeben:

// 422 — Validierungsfehler
{
  "error": "Pflichtfelder fehlen: name, external_id"
}

// 409 — Duplikat
{
  "error": "Produkt mit SKU 'WM-2024' existiert bereits"
}

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

API Dokumentation

Vollständige 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: 200, Default: 50
`offset`	integer	Optional	Anzahl zu überspringender Ergebnisse. Min: 0, Default: 0

Die Response enthält immer ein pagination Objekt mit limit, offset und total.

Soft-Delete

Authentifizierung

Die API verwendet Bearer-Token-Authentifizierung. API-Keys können 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 vollständige Key wird nur bei der Erstellung einmalig angezeigt. Bewahre ihn sicher auf.

Auth-Fehlercodes

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

Products

Die Product-Endpoints ermöglichen das vollständige Management deiner Produkte — inklusive Preise, Bilder, Identifier, Attribute und Kategorie-Zuordnungen.

GET/v1/products

Gibt eine paginierte Liste aller Produkte zurück.

Query-Parameter

Feld	Typ	Status	Beschreibung
`limit`	integer	Optional	Ergebnisse pro Seite (1–200, Default: 50)
`offset`	integer	Optional	Anzahl zu überspringender 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",
      "sku": "WM-2024",
      "name": "Wireless Maus Pro",
      "ean": "4012345678901"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 127
  }
}

POST/v1/products?sku={sku}

Erstellt ein neues Produkt mit der angegebenen SKU. Die SKU muss als Query-Parameter übergeben werden und darf noch nicht existieren.

Query-Parameter

Feld	Typ	Status	Beschreibung
`sku`	string	Pflicht	Eindeutige SKU des Produkts

Beispiel

curl -X POST "https://app.priceivy.com/api/v1/products?sku=WM-2024" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wireless Maus Pro",
    "ean": "4012345678901",
    "prices": [
      {
        "price_type": "vk",
        "price_net": 19.99,
        "price_gross": 23.79
      }
    ]
  }'

Response (201)

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

GET/v1/products/{id}

Gibt ein einzelnes Produkt per UUID zurück, inklusive aller verknüpften Preise, Bilder, Identifier und Attribute.

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`id`	UUID	Pflicht	Produkt-UUID

Beispiel

curl -X GET "https://app.priceivy.com/api/v1/products/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer rp_dein_api_key"

Response (200)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "sku": "WM-2024",
    "name": "Wireless Maus Pro",
    "ean": "4012345678901",
    "prices": [...],
    "images": [...],
    "identifiers": [...],
    "attributes": [...]
  }
}

PUT/v1/products/{sku}

Idempotenter Upsert per SKU. Erstellt das Produkt falls es nicht existiert (201) oder aktualisiert es (200). Alle Sub-Ressourcen (Preise, Bilder, etc.) werden bei Angabe vollständig ersetzt.

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`sku`	string	Pflicht	SKU des Produkts

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",
    "prices": [
      {
        "price_type": "vk",
        "price_net": 24.99,
        "price_gross": 29.74
      }
    ],
    "images": [
      {
        "url": "https://example.com/maus-pro-v2.jpg",
        "sort": 0
      }
    ]
  }'

Response (200 oder 201)

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

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

PATCH/v1/products/{id}

Teilupdate eines Produkts per UUID. Nur die übergebenen Felder werden aktualisiert. Sub-Ressourcen (Preise, Bilder, etc.) werden bei Angabe vollständig ersetzt.

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`id`	UUID	Pflicht	Produkt-UUID

Beispiel

curl -X PATCH "https://app.priceivy.com/api/v1/products/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wireless Maus Pro (aktualisiert)"
  }'

Response (200)

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

DELETE/v1/products/{id}

Soft-Delete eines Produkts per UUID. Das Produkt wird nicht physisch gelöscht, sondern mit einem deleted_at Timestamp versehen.

Pfad-Parameter

Feld	Typ	Status	Beschreibung
`id`	UUID	Pflicht	Produkt-UUID

Beispiel

curl -X DELETE "https://app.priceivy.com/api/v1/products/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer rp_dein_api_key"

Response (200)

{
  "success": true
}

POST/v1/products/bulk-upsert

Erstellt oder aktualisiert bis zu 100 Produkte in einem Request per SKU. Jedes Item wird einzeln verarbeitet — Fehler bei einem Item stoppen nicht die anderen.

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": [
      {
        "sku": "WM-2024",
        "name": "Wireless Maus Pro",
        "prices": [
          { "price_type": "vk", "price_net": 19.99, "price_gross": 23.79 }
        ]
      },
      {
        "sku": "KB-2024",
        "name": "Mechanische Tastatur"
      }
    ]
  }'

Response (200)

{
  "items": [
    {
      "sku": "WM-2024",
      "success": true,
      "status": 201,
      "data": { "id": "...", "sku": "WM-2024", "name": "Wireless Maus Pro" }
    },
    {
      "sku": "KB-2024",
      "success": true,
      "status": 200,
      "data": { "id": "...", "sku": "KB-2024", "name": "Mechanische Tastatur" }
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 2,
    "failed": 0
  }
}

Limit: Maximal 100 Items pro Request. Jedes Item benötigt ein sku Feld. Status 201 = neu erstellt, 200 = aktualisiert.

POST/v1/products/bulk-delete

Soft-Delete von bis zu 100 Produkten per SKU in einem Request. Nicht gefundene SKUs 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 '{
    "skus": ["WM-2024", "KB-2024", "NICHT-VORHANDEN"]
  }'

Response (200)

{
  "items": [
    { "sku": "WM-2024", "success": true, "status": 200 },
    { "sku": "KB-2024", "success": true, "status": 200 },
    { "sku": "NICHT-VORHANDEN", "success": false, "status": 404, "error": "Produkt nicht gefunden" }
  ],
  "summary": {
    "total": 3,
    "succeeded": 2,
    "failed": 1
  }
}

Limit: Maximal 100 SKUs pro Request.

Produkt-Payload

Das folgende Schema gilt für POST, PUT und PATCH Requests auf Product-Endpoints. Bei PATCH sind alle Felder optional.

Basis-Felder

Feld	Typ	Status	Beschreibung
`name`	string \| null	Optional	Produktname
`ean`	string \| null	Optional	EAN / GTIN Barcode

prices

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

Feld	Typ	Status	Beschreibung
`price_type`	string	Pflicht	Preistyp: "ek" (Einkauf), "vk" (Verkauf), "uvp" (UVP), "min" (Mindestpreis)
`price_net`	number	Pflicht	Nettopreis
`price_gross`	number	Pflicht	Bruttopreis
`currency_iso3`	string	Optional	ISO 4217 Währungscode (Default: "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 für zusätzliche Produktkennungen (z.B. MPN, ISBN). Bei Angabe werden alle bestehenden Identifier ersetzt.

Feld	Typ	Status	Beschreibung
`key`	string	Pflicht	Schlüssel (z.B. "mpn", "isbn", "asin")
`value`	string	Pflicht	Wert

attributes

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

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

exclusions

Steuert, ob ein Produkt vom Import oder Export ausgeschlossen wird.

Feld	Typ	Status	Beschreibung
`import`	boolean	Optional	Produkt vom Import ausschließen
`export`	boolean	Optional	Produkt vom Export ausschließen

Kategorie-Zuordnung

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

Wichtig: category_ids und category_external_ids können nicht gleichzeitig in einem Request verwendet werden. Nutze entweder UUIDs oder externe IDs.

Vollständiges Payload-Beispiel

{
  "name": "Wireless Maus Pro",
  "ean": "4012345678901",
  "prices": [
    {
      "price_type": "vk",
      "price_net": 19.99,
      "price_gross": 23.79,
      "currency_iso3": "EUR"
    },
    {
      "price_type": "ek",
      "price_net": 8.50,
      "price_gross": 10.12
    }
  ],
  "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"]
}

Response-Formate

Standard-Response (Einzelnes Objekt)

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

Listen-Response (mit Pagination)

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

Bulk-Response

Bulk-Endpoints verarbeiten jedes Item einzeln und geben eine Zusammenfassung zurück.

{
  "items": [
    {
      "sku": "WM-2024",
      "success": true,
      "status": 201,
      "data": { "id": "...", "sku": "WM-2024" }
    },
    {
      "sku": "INVALID",
      "success": false,
      "status": 422,
      "error": "Validierungsfehler: ..."
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 1,
    "failed": 1
  }
}

Fehler-Response

{
  "error": "Beschreibung des Fehlers"
}

Delete-Response

{
  "success": true
}

Generische Ressourcen

Neben den spezialisierten Product-Endpoints bietet die API generische CRUD-Operationen für weitere Ressourcen. Alle folgen dem gleichen Muster:

Verfügbare Operationen

GET/v1/{resource}— Liste mit Pagination

GET/v1/{resource}/{id}— Einzelner Eintrag per UUID

POST/v1/{resource}— Neuen Eintrag erstellen

PATCH/v1/{resource}/{id}— Eintrag teilweise aktualisieren

DELETE/v1/{resource}/{id}— Soft-Delete per UUID

Beispiel: Eintrag erstellen

curl -X POST "https://app.priceivy.com/api/v1/platforms" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "marketplace",
    "name": "Amazon DE",
    "provider": "amazon"
  }'

platforms

/v1/platforms

Feld	Typ	Status	Beschreibung
`type`	string	Pflicht	Plattformtyp (z.B. marketplace, shop)
`name`	string	Pflicht	Anzeigename der Plattform
`provider`	string	Pflicht	Provider-Kennung (z.B. amazon, idealo, ebay)

product-prices

/v1/product-prices

Feld	Typ	Status	Beschreibung
`org_product_id`	UUID	Pflicht	Referenz auf das Produkt
`price_type`	string	Pflicht	Preistyp: "ek", "vk", "uvp", "min"
`price_net`	number	Pflicht	Nettopreis
`price_gross`	number	Pflicht	Bruttopreis
`currency_rate_id`	UUID	Optional	Referenz auf Währungskurs (Default: EUR)

product-images

/v1/product-images

Feld	Typ	Status	Beschreibung
`org_product_id`	UUID	Pflicht	Referenz auf das Produkt
`url`	string	Pflicht	URL des Bildes
`sort`	number	Optional	Sortierreihenfolge

product-identifiers

/v1/product-identifiers

Feld	Typ	Status	Beschreibung
`org_product_id`	UUID	Pflicht	Referenz auf das Produkt
`key`	string	Pflicht	Identifier-Schlüssel (z.B. mpn, isbn, asin)
`value`	string	Pflicht	Identifier-Wert

product-attributes

/v1/product-attributes

Feld	Typ	Status	Beschreibung
`org_product_id`	UUID	Pflicht	Referenz auf das Produkt
`key`	string	Pflicht	Attribut-Schlüssel (z.B. farbe, gewicht)
`value`	string	Pflicht	Attribut-Wert

Feld	Typ	Status	Beschreibung
`name`	string	Pflicht	Kategoriename
`external_id`	string	Pflicht	Externe ID (Pflichtfeld, wird für category_external_ids Referenzen verwendet)
`parent_id`	UUID	Optional	UUID der übergeordneten Kategorie (für Hierarchien)

category-identifiers

/v1/category-identifiers

Feld	Typ	Status	Beschreibung
`org_product_category_id`	UUID	Pflicht	Referenz auf die Kategorie
`key`	string	Pflicht	Identifier-Schlüssel
`value`	string	Pflicht	Identifier-Wert

category-mappings

/v1/category-mappings

Feld	Typ	Status	Beschreibung
`org_product_id`	UUID	Pflicht	Referenz auf das Produkt
`org_product_category_id`	UUID	Pflicht	Referenz auf die Kategorie

Kategorien

Kategorie erstellen

curl -X POST "https://app.priceivy.com/api/v1/categories" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Elektronik",
    "external_id": "elektronik"
  }'

Unterkategorie erstellen

curl -X POST "https://app.priceivy.com/api/v1/categories" \
  -H "Authorization: Bearer rp_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Peripheriegeräte",
    "external_id": "peripherie",
    "parent_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Zuordnung zu Produkten

Produkte können auf zwei Arten Kategorien zugeordnet werden:

Option 1: Per UUID

{
  "category_ids": [
    "550e8400-e29b-41d4-..."
  ]
}

Option 2: Per External ID

{
  "category_external_ids": [
    "elektronik",
    "peripherie"
  ]
}

Alternativ kann die Zuordnung auch über den category-mappings Ressourcen-Endpoint verwaltet werden.

Fehlercodes

Code	Titel	Beschreibung
`400`	Bad Request	Ungültiges JSON im Request-Body
`401`	Unauthorized	Kein API-Key im Authorization-Header oder Key ist ungültig
`403`	Forbidden	API-Key ist abgelaufen
`404`	Not Found	Ressource nicht gefunden oder nicht unterstützter Ressourcen-Typ
`409`	Conflict	Duplikat — ein Eintrag mit gleicher SKU oder Unique-Constraint existiert bereits
`422`	Unprocessable	Validierungsfehler — fehlende Pflichtfelder, unbekannte Felder, ungültiges UUID-Format oder ungültige Referenzen
`500`	Server Error	Interner Serverfehler — bitte kontaktiere den Support

Fehler-Response Format

Alle Fehler werden als JSON mit einem error Feld zurückgegeben:

// 422 — Validierungsfehler
{
  "error": "Pflichtfelder fehlen: name, external_id"
}

// 409 — Duplikat
{
  "error": "Produkt mit SKU 'WM-2024' existiert bereits"
}

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