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