← Alle Themen · API

API: Artikel-Endpunkte

Zurück zur API-Übersicht

GET /items

Artikel suchen und abrufen. Gibt Artikel mit optionalen Unterdaten (Texte, Barcodes, Varianten, Bestände etc.) zurück.

URL: GET /public_api/<token>/items

Request-Parameter (Query-String)

Beispiel-Request

curl -X GET "https://meinefirma.scanalot.io/public_api/<token>/items?sku=T-SHIRT&showVariants=1&page=1&limit=10" \
  -H "Authorization: <api-token>"

Erfolgreiche Antwort

{
  "valid": true,
  "data": [
    {
      "id": 123,
      "parentId": 123,
      "sku": "T-SHIRT-001",
      "isMain": 1,
      "manufacturerId": 5,
      "manufacturer": "Markenname",
      "model": "Modell-A",
      "externalId": "EXT-123",
      "purchasePrice": 5.99,
      "weightG": 200,
      "widthMM": 300,
      "lengthMM": 400,
      "heightMM": 20,
      "statusId": 1,
      "isBundle": 0,
      "isBundleComponent": 0,
      "createdAt": 1700000000,
      "updatedAt": 1700100000,
      "stockUpdatedAt": 1700100000,
      "texts": [
        {
          "id": 1,
          "itemId": 123,
          "lang": "de",
          "textKey": "name",
          "textValue": "T-Shirt Blau"
        }
      ],
      "salesPrices": [
        {
          "id": 1,
          "itemId": 123,
          "salesPriceId": 1,
          "price": 19.99,
          "updatedAt": 1700000000
        }
      ],
      "images": [
        {
          "id": 1,
          "itemId": 123,
          "imageName": "bild1.jpg",
          "position": 1
        }
      ],
      "imageLinks": [],
      "properties": [
        {
          "id": 1,
          "itemId": 123,
          "propertieId": 1,
          "propertieValue": "Baumwolle"
        }
      ],
      "barcodes": [
        {
          "id": 1,
          "itemId": 123,
          "barcodeId": 1,
          "code": "4006381333931"
        }
      ],
      "markets": [
        {
          "id": 1,
          "itemId": 123,
          "market": "amazon",
          "active": 1
        }
      ],
      "clients": [
        {
          "id": 1,
          "itemId": 123,
          "clientId": 1,
          "active": 1
        }
      ],
      "bundles": [],
      "stocks": [
        {
          "warehouseId": 1,
          "id": 10,
          "name": "A-01-01",
          "stock": 50,
          "warehouseName": "Hauptlager",
          "itemId": 123,
          "reserved": 5,
          "stockNet": 45
        }
      ],
      "variants": [
        {
          "id": 124,
          "parentId": 123,
          "sku": "T-SHIRT-001-M",
          "isMain": 0,
          "barcodes": [],
          "attributes": [],
          "salesPrices": [],
          "properties": [],
          "markets": [],
          "clients": [],
          "bundles": [],
          "stocks": []
        }
      ]
    }
  ],
  "count": 1,
  "pages": 1,
  "used_page": 1,
  "warehouses": [
    {
      "id": 1,
      "name": "Hauptlager",
      "active": 1
    }
  ]
}

Fehler-Antwort

{
  "valid": false,
  "error": "Keine Artikel gefunden"
}

POST /items

Erstellt einen neuen Artikel oder aktualisiert einen bestehenden Artikel inklusive Varianten, Texten, Barcodes, Verkaufspreisen und weiteren Daten.

URL: POST /public_api/<token>/items

Request-Body (JSON)

Der Request-Body muss ein item-Objekt enthalten:

Texte (optional)

Verkaufspreise (optional)

Barcodes (optional)

Bilder (optional, nur bei bestehenden Artikeln)

Eigenschaften (optional, nur bei bestehenden Artikeln)

Märkte (optional, nur bei bestehenden Artikeln)

Mandanten (optional, nur bei bestehenden Artikeln)

Bundles (optional, nur bei bestehenden Artikeln)

Varianten (optional)

Varianten-Attribute:

Beispiel-Request (neuer Artikel)

curl -X POST "https://meinefirma.scanalot.io/public_api/<token>/items" \
  -H "Authorization: <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "item": {
      "itemId": "new",
      "sku": "HOODIE-001",
      "manufacturerId": 5,
      "weightG": 500,
      "statusId": 1,
      "texts": [
        {
          "lang": "de",
          "name": "Hoodie Schwarz",
          "desc": "Bequemer Hoodie aus Baumwolle"
        }
      ],
      "barcodes": [
        { "id": 1, "value": "4006381333931" }
      ],
      "salesPrices": [
        { "id": 1, "value": 39.99 }
      ],
      "variants": [
        {
          "itemId": "new",
          "sku": "HOODIE-001-M",
          "weightG": 500,
          "attributes": [
            { "id": 1, "value": "M" }
          ]
        },
        {
          "itemId": "new",
          "sku": "HOODIE-001-L",
          "weightG": 520,
          "attributes": [
            { "id": 1, "value": "L" }
          ]
        }
      ]
    }
  }'

Erfolgreiche Antwort

{
  "valid": true,
  "id": 456
}

Fehler-Antworten

{
  "valid": false,
  "error": "Hauptartikel - SKU bereits vorhanden"
}

{
  "valid": false,
  "error": "Hauptartikel - SKU darf nicht leer sein"
}

{
  "valid": false,
  "error": "Variante - SKU HOODIE-001-M bereits vorhanden"
}

PUT /items/item_status

Ändert den Status eines Artikels.

URL: PUT /public_api/<token>/items/item_status

Request-Body (JSON)

Beispiel-Request

curl -X PUT "https://meinefirma.scanalot.io/public_api/<token>/items/item_status" \
  -H "Authorization: <api-token>" \
  -H "Content-Type: application/json" \
  -d '{ "itemId": 123, "statusId": 2 }'

Erfolgreiche Antwort

{
  "valid": true
}

Fehler-Antwort

{
  "valid": false
}

GET /items/stock

Ruft die Bestandsdaten eines Artikels pro Lagerort ab.

URL: GET /public_api/<token>/items/stock

Request-Parameter (Query-String)

Beispiel-Request

curl -X GET "https://meinefirma.scanalot.io/public_api/<token>/items/stock?itemId=123" \
  -H "Authorization: <api-token>"

Erfolgreiche Antwort

{
  "valid": true,
  "data": [
    {
      "warehouseId": 1,
      "id": 10,
      "name": "A-01-01",
      "stock": 50,
      "warehouseName": "Hauptlager",
      "itemId": 123,
      "qrCode": "a1b2c3d4e5f6g7h"
    }
  ]
}

Fehler-Antwort

{
  "valid": false,
  "error": "Kein Bestand gefunden"
}

POST /items/stock_incoming

Bucht einen Wareneingang. Die angegebene Menge wird zum bestehenden Bestand am Lagerort addiert.

URL: POST /public_api/<token>/items/stock_incoming

Request-Body (JSON)

*Pflicht, wenn barcode nicht angegeben ist. Wenn barcode angegeben wird, werden locationId und warehouseId automatisch ermittelt.

Beispiel-Request

curl -X POST "https://meinefirma.scanalot.io/public_api/<token>/items/stock_incoming" \
  -H "Authorization: <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "itemId": 123,
    "locationId": 10,
    "warehouseId": 1,
    "stock": 25
  }'

Alternativ mit Barcode:

curl -X POST "https://meinefirma.scanalot.io/public_api/<token>/items/stock_incoming" \
  -H "Authorization: <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "itemId": 123,
    "barcode": "a1b2c3d4e5f6g7h",
    "stock": 25
  }'

Erfolgreiche Antwort

{
  "valid": true
}

Fehler-Antworten

{
  "valid": false,
  "error": "Artikel nicht gefunden"
}

{
  "valid": false,
  "error": "Lagerort nicht gefunden"
}

{
  "valid": false,
  "error": "Menge darf nicht 0 sein"
}

POST /items/stock_correction

Führt eine Bestandskorrektur für einen oder mehrere Artikel an bestimmten Lagerorten durch. Der Bestand wird auf den angegebenen Wert gesetzt (nicht addiert).

URL: POST /public_api/<token>/items/stock_correction

Request-Body (JSON)

Beispiel-Request

curl -X POST "https://meinefirma.scanalot.io/public_api/<token>/items/stock_correction" \
  -H "Authorization: <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "corrections": [
      { "itemId": 123, "locationId": 10, "warehouseId": 1, "stock": 50 },
      { "itemId": 124, "locationId": 10, "warehouseId": 1, "stock": 30 }
    ]
  }'

Erfolgreiche Antwort

{
  "valid": true,
  "errors": [],
  "count": 0,
  "success": 2
}

Antwort mit Teilfehlern

{
  "valid": true,
  "errors": ["ItemId 999 correction failed"],
  "count": 1,
  "success": 1
}

Fehler-Antwort

{
  "valid": false,
  "error": "param corrections missing"
}

PUT /items/stock_rebook

Bucht Bestand von einem Lagerort auf einen anderen um. Wenn die gewünschte Menge den verfügbaren Bestand am alten Lagerort übersteigt, wird der gesamte verfügbare Bestand umgebucht.

URL: PUT /public_api/<token>/items/stock_rebook

Request-Body (JSON)

*Pflicht, wenn barcode nicht angegeben ist. Wenn barcode angegeben wird, werden newLocation und newWarehouse automatisch ermittelt.

Beispiel-Request

curl -X PUT "https://meinefirma.scanalot.io/public_api/<token>/items/stock_rebook" \
  -H "Authorization: <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "itemId": 123,
    "oldLocation": 10,
    "oldWarehouse": 1,
    "newLocation": 20,
    "newWarehouse": 1,
    "stock": 15
  }'

Erfolgreiche Antwort

{
  "valid": true
}

Fehler-Antworten

{
  "valid": false,
  "error": "Artikel nicht gefunden"
}

{
  "valid": false,
  "error": "Alter Lagerort nicht gefunden"
}

{
  "valid": false,
  "error": "Neuer Lagerort nicht gefunden"
}

{
  "valid": false,
  "error": "Menge darf nicht 0 sein"
}

DELETE /items/{id}

Löscht einen Artikel inklusive Varianten, Bildern, Texten, Barcodes, Preisen, Beständen und Bundle-Verknüpfungen. Bei einem Hauptartikel werden auch sämtliche Varianten mit entfernt.

URL: DELETE /public_api/<token>/items/{id}

URL-Parameter

Beispiel-Request

curl -X DELETE "https://meinefirma.scanalot.io/public_api/<token>/items/123" \
  -H "Authorization: <api-token>"

Erfolgreiche Antwort

{ "valid": true }

Fehler-Antwort

{ "valid": false, "error": "cant find item" }

GET /items/stock_movements

Gibt Warenbewegungen (Zu-/Abgänge, Umbuchungen, Korrekturen) aus dem Lagerbuch zurück. Es handelt sich um die historisch gebuchten Lagerort-Bewegungen aus scanalot_warehouse_locations_movements.

URL: GET /public_api/<token>/items/stock_movements

Request-Parameter (Query-String)

Beispiel-Request

curl -X GET "https://meinefirma.scanalot.io/public_api/<token>/items/stock_movements?itemId=123&createdFrom=2026-01-01&createdTo=2026-01-31" \
  -H "Authorization: <api-token>"

Erfolgreiche Antwort

{
  "valid": true,
  "data": [
    {
      "id": 999,
      "user": "Max Mustermann",
      "warehouse": "Hauptlager",
      "location": "A-01-01",
      "sku": "T-SHIRT-001",
      "reasonKey": "incoming",
      "reasonValue": "Wareneingang Lieferschein 4711",
      "change": 10,
      "oldStock": 40,
      "newStock": 50,
      "bookedAt": 1700000000,
      "bookedAtFormat": "15.11.2023 12:00"
    }
  ]
}

Fehler-Antwort

{ "valid": false, "error": "Keine Warenbewegungen gefunden" }

GET /items/barcode_lookup

Sucht einen Artikel anhand eines Barcodes. Es wird zuerst in den Artikel-Barcodes gesucht, dann als Fallback auf die SKU gematcht. Liefert zusätzlich alle Lagerorte mit Bestand > 0 zurück.

URL: GET /public_api/<token>/items/barcode_lookup

Request-Parameter (Query-String)

Beispiel-Request

curl -X GET "https://meinefirma.scanalot.io/public_api/<token>/items/barcode_lookup?barcode=4006381333931" \
  -H "Authorization: <api-token>"

Erfolgreiche Antwort

{
  "valid": true,
  "data": [
    {
      "id": 124,
      "sku": "T-SHIRT-001-M",
      "parentId": 123,
      "name": "T-Shirt Blau",
      "stocks": [
        {
          "warehouseId": 1,
          "id": 10,
          "name": "A-01-01",
          "stock": 25,
          "warehouseName": "Hauptlager",
          "itemId": 124
        }
      ]
    }
  ]
}

Fehler-Antworten

{ "valid": false, "error": "Barcode fehlt" }

{ "valid": false, "error": "Artikel nicht gefunden" }

GET /items/stats

Liefert eine Verkaufs- und Retouren-Statistik pro Artikel über einen definierten Zeitraum. Berücksichtigt werden ausschließlich Positionen vom Typ item auf nicht gelöschten Aufträgen.

URL: GET /public_api/<token>/items/stats

Request-Parameter (Query-String)

Beispiel-Request

curl -X GET "https://meinefirma.scanalot.io/public_api/<token>/items/stats?itemIds[]=123&itemIds[]=124&days=90" \
  -H "Authorization: <api-token>"

Erfolgreiche Antwort

{
  "valid": true,
  "data": [
    {
      "itemId": 123,
      "sales": 42,
      "salesGross": 839.58,
      "returns": 2,
      "returnsGross": 39.98,
      "currency": "EUR"
    }
  ]
}

Felder:

GET /items/logs

Gibt die Metadaten der Marktplatz-Change-Logs eines Artikels zurück (ohne Payload). Payload je Eintrag kann über GET /items/log nachgeladen werden.

URL: GET /public_api/<token>/items/logs

Request-Parameter (Query-String)

Beispiel-Request

curl -X GET "https://meinefirma.scanalot.io/public_api/<token>/items/logs?itemId=123" \
  -H "Authorization: <api-token>"

Erfolgreiche Antwort

{
  "valid": true,
  "data": [
    {
      "taskId": "a1b2c3",
      "market": "amazon",
      "account": "DE Marketplace",
      "inserted": 1700000000,
      "createdAtFormat": "15.11.2023 12:00",
      "state": "unknown"
    }
  ]
}

Fehler-Antwort

{ "valid": false, "error": "Keine Logs gefunden" }

GET /items/log

Gibt den vollständigen Log-Eintrag inklusive Request- und Response-Daten zurück.

URL: GET /public_api/<token>/items/log

Request-Parameter (Query-String)

Beispiel-Request

curl -X GET "https://meinefirma.scanalot.io/public_api/<token>/items/log?itemId=123&taskId=a1b2c3" \
  -H "Authorization: <api-token>"

Erfolgreiche Antwort

{
  "valid": true,
  "data": {
    "itemId": 123,
    "taskId": "a1b2c3",
    "market": "amazon",
    "account": "DE Marketplace",
    "sendData": "{...}",
    "responseData": "{...}",
    "inserted": 1700000000
  }
}

Fehler-Antwort

{ "valid": false, "error": "Eintrag nicht gefunden" }

POST /items/image_upload

Lädt ein Bild (JPG/PNG) hoch und ordnet es dem Artikel zu. Der Request muss multipart/form-data sein.

URL: POST /public_api/<token>/items/image_upload

Request-Felder (multipart/form-data)

Beispiel-Request

curl -X POST "https://meinefirma.scanalot.io/public_api/<token>/items/image_upload" \
  -H "Authorization: <api-token>" \
  -F "itemId=123" \
  -F "file=@/pfad/zum/bild.jpg"

Erfolgreiche Antwort

{
  "valid": true,
  "path": "/documents/files/<hash>/<hash>_bild.jpg"
}

Fehler-Antworten

{ "valid": false, "error": "Filetype not allowed" }

{ "valid": false, "error": "cant upload file" }

DELETE /items/image

Entfernt ein hochgeladenes Artikel-Bild. Die zugehörige Datei im Dateisystem wird mit gelöscht.

URL: DELETE /public_api/<token>/items/image

Request-Body (JSON)

Beispiel-Request

curl -X DELETE "https://meinefirma.scanalot.io/public_api/<token>/items/image" \
  -H "Authorization: <api-token>" \
  -H "Content-Type: application/json" \
  -d '{ "itemId": 123, "imageName": "abc_bild.jpg" }'

Erfolgreiche Antwort

{ "valid": true }

Fehler-Antwort

{ "valid": false, "error": "Image not found" }

POST /items/bundle

Legt eine Bundle-Komponente an oder aktualisiert deren Menge. Der Zielartikel wird dadurch zum Bundle, die Komponente wird als Bundle-Bestandteil markiert.

URL: POST /public_api/<token>/items/bundle

Request-Body (JSON)

*Entweder bundleItemId oder sku muss angegeben werden.

Beispiel-Request

curl -X POST "https://meinefirma.scanalot.io/public_api/<token>/items/bundle" \
  -H "Authorization: <api-token>" \
  -H "Content-Type: application/json" \
  -d '{ "itemId": 500, "sku": "T-SHIRT-001-M", "quantity": 2 }'

Erfolgreiche Antwort

{ "valid": true }

Fehler-Antworten

{ "valid": false, "error": "Menge darf nicht kleiner als 1 sein" }

{ "valid": false, "error": "Kein Artikel gefunden" }

DELETE /items/bundle

Entfernt eine Bundle-Komponente. Hat das Bundle nach dem Entfernen keine Komponenten mehr, wird isBundle zurückgesetzt. Analog bei der Komponente mit isBundleComponent, falls sie Teil keines anderen Bundles mehr ist.

URL: DELETE /public_api/<token>/items/bundle

Request-Body (JSON)

Beispiel-Request

curl -X DELETE "https://meinefirma.scanalot.io/public_api/<token>/items/bundle" \
  -H "Authorization: <api-token>" \
  -H "Content-Type: application/json" \
  -d '{ "itemId": 500, "bundleItemId": 124 }'

Erfolgreiche Antwort

{ "valid": true }

Artikel-Stammdaten

Alle Stammdaten-Endpunkte folgen dem gleichen Schema:

• GET listet alle Einträge oder einen einzelnen Eintrag per id
• POST legt einen neuen Eintrag an (id = "new") oder aktualisiert einen bestehenden
• DELETE löscht den Eintrag per URL-Parameter

Alle Antworten enthalten valid sowie bei GET das Feld data als Array.

Status

Verwaltet die Artikel-Status (Freigabestatus für Marktplatz-Export, z.B. „Aktiv", „Entwurf", „Archiviert"). Zugehörige Seite im Backend: Artikel → Status.

GET /items/status

{
  "valid": true,
  "data": [
    { "statusId": 1, "name": "Aktiv", "statusColor": "#28a745", "textColor": "#ffffff" }
  ]
}

POST /items/status

Beispiel-Request:

curl -X POST "https://meinefirma.scanalot.io/public_api/<token>/items/status" \
  -H "Authorization: <api-token>" \
  -H "Content-Type: application/json" \
  -d '{ "statusId": 10, "name": "Entwurf", "statusColor": "#6c757d", "textColor": "#ffffff" }'

DELETE /items/status/{id}

curl -X DELETE "https://meinefirma.scanalot.io/public_api/<token>/items/status/10" \
  -H "Authorization: <api-token>"

Attribute

Varianten-Attribute (z.B. „Größe", „Farbe"). Werden an Varianten über POST /items als item.variants[].attributes[] zugeordnet. Backend-Seite: Artikel → Attribute.

GET /items/attributes

{
  "valid": true,
  "data": [
    { "id": 1, "name": "Größe" },
    { "id": 2, "name": "Farbe" }
  ]
}

POST /items/attributes

DELETE /items/attributes/{id}

Löscht das Attribut und entfernt es gleichzeitig aus allen Varianten (scanalot_items_attributes wird mit attributeId = id bereinigt).

Eigenschaften

Freie Artikel-Eigenschaften (z.B. „Material", „Gewicht laut Hersteller"). Werden an Artikel über POST /items als item.properties[] zugeordnet. Backend-Seite: Artikel → Eigenschaften.

GET /items/properties

{
  "valid": true,
  "data": [
    { "id": 1, "name": "Material" }
  ]
}

POST /items/properties

DELETE /items/properties/{id}

Löscht die Eigenschaft und alle zugeordneten Werte (scanalot_item_properties_values wird mit propertieId = id bereinigt).

Hersteller

Hersteller-Stammdaten. Zuordnung an Artikeln über item.manufacturerId in POST /items. Backend-Seite: Artikel → Hersteller.

GET /items/manufacturer

{
  "valid": true,
  "data": [
    { "id": 1, "name": "Markenname" }
  ]
}

POST /items/manufacturer

DELETE /items/manufacturer/{id}

Löscht den Hersteller und setzt bei allen Artikeln mit diesem Hersteller manufacturerId = 0 zurück.

Barcodes (Barcode-Typen)

Barcode-Typen (z.B. „EAN", „ASIN", „Hersteller-SKU"). Werden an Artikel über POST /items als item.barcodes[] zugeordnet. Backend-Seite: Artikel → Barcodes.

GET /items/barcodes

{
  "valid": true,
  "data": [
    { "id": 1, "name": "EAN" },
    { "id": 2, "name": "ASIN" }
  ]
}

POST /items/barcodes

DELETE /items/barcodes/{id}

Löscht den Barcode-Typ. Zugeordnete Artikel-Barcodes mit diesem Typ werden mit entfernt.

Verkaufspreise (Preis-Typen)

Preis-Typen (z.B. „UVP", „Amazon DE", „eBay"). Werden an Artikel über POST /items als item.salesPrices[] zugeordnet. Backend-Seite: Artikel → Verkaufspreise.

GET /items/sales_prices

{
  "valid": true,
  "data": [
    { "id": 1, "name": "UVP" },
    { "id": 2, "name": "Amazon DE" }
  ]
}

POST /items/sales_prices

DELETE /items/sales_prices/{id}

Löscht den Preis-Typ. Zugeordnete Artikel-Preise mit diesem Typ werden mit entfernt.