← Alle Themen · API

In diesem Artikel 4 Kapitel
  1. GET /orders
  2. POST /orders
  3. PUT /orders
  4. PUT /orders/status

API: Auftrags-Endpunkte

Zurück zur API-Übersicht

GET /orders

Aufträge suchen und abrufen. Gibt Aufträge mit Positionen, Adressen, Sendungen, Dokumenten, Historie und Notizen zurück.

URL: GET /public_api/<token>/orders

Request-Parameter (Query-String)

ParameterTypPflichtBeschreibung
idIntegerNeinSuche nach Auftrags-ID
externalIdStringNeinSuche nach externer Auftrags-ID
skuStringNeinSuche nach Artikel-SKU in den Positionen (Prefix-Suche)
marketStringNeinFilter nach Marktplatz (z.B. "amazon", "ebay", "shopify", "manuell")
typeStringNeinFilter nach Auftragstyp: "order", "return", "credit"
clientIdIntegerNeinFilter nach Mandanten-ID
statusIdIntegerNeinFilter nach Status-ID
trackingNrStringNeinSuche nach Tracking-Nummer
returnTrackingNrStringNeinSuche nach Retouren-Tracking-Nummer
documentNrStringNeinSuche nach Dokumentennummer (Rechnung, Lieferschein etc.)
customerdataStringNeinSuche in Kundendaten (Name, Adresse etc.)
createdAtFromStringNeinErstellt ab Datum (Format: YYYY-MM-DD). Muss zusammen mit createdAtTo verwendet werden
createdAtToStringNeinErstellt bis Datum (Format: YYYY-MM-DD). Muss zusammen mit createdAtFrom verwendet werden
updatedAfterIntegerNeinNur Aufträge die nach diesem Unix-Timestamp aktualisiert wurden
ignoreDeletedAnyNeinWenn gesetzt, werden auch gelöschte Aufträge (Status -1) angezeigt
withoutDetailsAnyNeinWenn gesetzt, werden Historie, Notizen, Properties und Lagerort-Zuordnungen nicht geladen (schnellere Antwort)
onlyItemsAnyNeinWenn gesetzt, werden nur Positionen und deren Lagerort-Zuordnungen geladen (schnellste Antwort)
sortingStringNeinSortierung: "id_desc" (nach ID absteigend) oder "lastname_desc" (nach Nachname absteigend)
pageIntegerNeinSeite für Paginierung
limitIntegerNeinErgebnisse pro Seite

Beispiel-Request

curl -X GET "https://meinefirma.scanalot.io/public_api/<token>/orders?market=amazon&statusId=2&page=1&limit=25" \
  -H "Authorization: <api-token>"

Erfolgreiche Antwort

{
  "valid": true,
  "data": [
    {
      "id": 1001,
      "type": "order",
      "parentId": 0,
      "externalId": "305-1234567-8901234",
      "statusId": 2,
      "market": "amazon",
      "clientId": 1,
      "accountId": 1,
      "isSelfFulfillment": 0,
      "payedAt": 1700000000,
      "payedAtFormat": "15.11.2023 10:00",
      "payedAtFormatEN": "2023-11-15 10:00",
      "shippedAt": 0,
      "shippedAtFormat": "",
      "shippedAtFormatEN": "",
      "createdAt": 1700000000,
      "createdAtFormat": "15.11.2023 10:00",
      "createdAtFormatEN": "2023-11-15 10:00",
      "updatedAt": 1700100000,
      "isLocked": false,
      "address": [
        {
          "id": 1,
          "orderId": 1001,
          "type": "shipping",
          "company": null,
          "firstname": "Max",
          "lastname": "Mustermann",
          "additionalInfo": null,
          "street": "Musterstraße",
          "houseNr": "1",
          "zip": "12345",
          "city": "Berlin",
          "province": null,
          "email": "max@example.com",
          "telephone": null,
          "isoCode2": "DE"
        },
        {
          "id": 2,
          "orderId": 1001,
          "type": "invoice",
          "company": null,
          "firstname": "Max",
          "lastname": "Mustermann",
          "additionalInfo": null,
          "street": "Musterstraße",
          "houseNr": "1",
          "zip": "12345",
          "city": "Berlin",
          "province": null,
          "email": "max@example.com",
          "telephone": null,
          "isoCode2": "DE"
        }
      ],
      "shipments": [
        {
          "id": 1,
          "orderId": 1001,
          "trackingNr": "00340434161094015902",
          "returnTrackingNr": "",
          "carrier": "dhl",
          "createdAt": 1700100000,
          "createdAtFormat": "16.11.2023 13:46"
        }
      ],
      "items": [
        {
          "id": 5001,
          "orderId": 1001,
          "type": "item",
          "parentId": 0,
          "itemId": 123,
          "itemSku": "T-SHIRT-001-M",
          "itemName": "T-Shirt Blau Größe M",
          "itemQty": 2,
          "priceNet": 33.60,
          "priceGross": 39.98,
          "currency": "EUR",
          "vatPercentage": 19,
          "vatAmount": 6.38,
          "locations": [
            {
              "warehouseId": 1,
              "id": 10,
              "name": "A-01-01",
              "stock": 2,
              "warehouseName": "Hauptlager",
              "itemId": 123,
              "locationStock": 48
            }
          ]
        },
        {
          "id": 5002,
          "orderId": 1001,
          "type": "shippingcost",
          "parentId": 0,
          "itemId": 0,
          "itemSku": "",
          "itemName": "Standardversand",
          "itemQty": 1,
          "priceNet": 4.20,
          "priceGross": 4.99,
          "currency": "EUR",
          "vatPercentage": 19,
          "vatAmount": 0.79
        }
      ],
      "documents": [
        {
          "id": 1,
          "type": "invoice",
          "number": "RE-2023-001",
          "canceled": 0,
          "relatedTo": 0,
          "createdAt": 1700100000,
          "createdAtFormat": "16.11.2023 13:46",
          "orderId": 1001,
          "relatedType": "",
          "relatedNumber": ""
        }
      ],
      "historie": [
        {
          "id": 1,
          "orderId": 1001,
          "historieUserId": 1,
          "text": "order created",
          "createdAt": 1700000000,
          "createdAtFormat": "15.11.2023 10:00",
          "name": "Admin",
          "userName": "Admin"
        }
      ],
      "notes": [],
      "properties": [
        {
          "id": 1,
          "orderId": 1001,
          "propertieKey": "payment_method",
          "propertieValue": "paypal"
        }
      ]
    }
  ],
  "amounts": {
    "EUR": {
      "net": 37.80,
      "gross": 44.97,
      "vat": 7.17
    }
  },
  "count": 1,
  "pages": 1,
  "used_page": 1
}

Fehler-Antwort

{
  "valid": false,
  "error": "Keine Aufträge gefunden"
}

POST /orders

Erstellt einen neuen Auftrag mit Positionen, Adressen und Properties.

URL: POST /public_api/<token>/orders

Request-Body (JSON)

Hauptfelder

ParameterTypPflichtBeschreibung
typeStringJaAuftragstyp: "order", "return" oder "credit"
parentIdIntegerJaID des übergeordneten Auftrags (0 für eigenständige Aufträge)
statusIdIntegerJaStatus-ID
marketStringJaMarktplatz (z.B. "amazon", "ebay", "shopify", "manuell")
clientIdIntegerJaMandanten-ID
accountIdIntegerJaAccount-ID
isSelfFulfillmentIntegerJa0 = normaler Versand, 1 = Eigenversand
shippedAtInteger/StringJaVersandzeitpunkt als Unix-Timestamp oder Datumsstring (0 = noch nicht versendet)
externalIdStringNeinExterne Auftrags-ID (bei type=order wird auf Dublette geprüft)
createdAtInteger/StringNeinErstellungszeitpunkt als Unix-Timestamp oder Datumsstring (Standard: aktuelle Zeit)
payedAtInteger/StringNeinZahlungszeitpunkt als Unix-Timestamp oder Datumsstring (Standard: 0)

Adressen (optional)

ParameterTypPflichtBeschreibung
addressArrayNeinArray von Adress-Objekten
address[].typeStringJa"shipping" oder "invoice"
address[].isoCode2StringJaLändercode ISO 3166-1 alpha-2 (z.B. "DE", "AT", "CH")
address[].companyStringNeinFirma
address[].firstnameStringNeinVorname
address[].lastnameStringNeinNachname
address[].additionalInfoStringNeinAdresszusatz
address[].streetStringNeinStraße
address[].houseNrStringNeinHausnummer
address[].zipStringNeinPostleitzahl
address[].cityStringNeinStadt
address[].provinceStringNeinBundesland / Provinz
address[].emailStringNeinE-Mail-Adresse
address[].telephoneStringNeinTelefonnummer

Positionen (optional)

ParameterTypPflichtBeschreibung
itemsArrayNeinArray von Positions-Objekten
items[].typeStringJa"item" oder "shippingcost"
items[].itemSkuStringJaSKU der Position (wird automatisch mit Artikelstamm abgeglichen)
items[].itemQtyIntegerJaMenge (muss > 0 sein)
items[].itemIdIntegerNeinArtikel-ID (wenn nicht angegeben, wird automatisch per SKU/Barcode gesucht)
items[].itemNameStringNeinArtikelname
items[].priceGrossFloatNeinBruttobetrag (Gesamtpreis, nicht Einzelpreis)
items[].priceNetFloatNeinNettobetrag
items[].vatPercentageFloatNeinSteuersatz in Prozent
items[].vatAmountFloatNeinSteuerbetrag
items[].currencyStringNeinWährungscode (Standard: "EUR")
items[].propertiesArrayNeinPositions-Properties (s.u.)

Hinweis zur Steuerberechnung: Wenn weder vatPercentage, priceNet noch vatAmount angegeben werden und ein Steuersatz für das Lieferland (Versandadresse) konfiguriert ist, wird der Standardsteuersatz automatisch angewendet und Netto/MwSt aus dem Bruttobetrag berechnet.

Positions-Properties:

ParameterTypPflichtBeschreibung
items[].properties[].propertieKeyStringJaSchlüssel (darf nicht leer sein)
items[].properties[].propertieValueStringJaWert

Auftrags-Properties (optional)

ParameterTypPflichtBeschreibung
propertiesArrayNeinArray von Property-Objekten
properties[].propertieKeyStringJaSchlüssel (darf nicht leer sein)
properties[].propertieValueStringJaWert

Beispiel-Request

curl -X POST "https://meinefirma.scanalot.io/public_api/<token>/orders" \
  -H "Authorization: <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order",
    "parentId": 0,
    "statusId": 1,
    "market": "manuell",
    "clientId": 1,
    "accountId": 1,
    "isSelfFulfillment": 0,
    "shippedAt": 0,
    "externalId": "EXT-2024-001",
    "createdAt": "2024-01-15 10:00:00",
    "payedAt": "2024-01-15 09:55:00",
    "address": [
      {
        "type": "shipping",
        "isoCode2": "DE",
        "firstname": "Max",
        "lastname": "Mustermann",
        "street": "Musterstraße",
        "houseNr": "1",
        "zip": "12345",
        "city": "Berlin",
        "email": "max@example.com"
      },
      {
        "type": "invoice",
        "isoCode2": "DE",
        "firstname": "Max",
        "lastname": "Mustermann",
        "street": "Musterstraße",
        "houseNr": "1",
        "zip": "12345",
        "city": "Berlin",
        "email": "max@example.com"
      }
    ],
    "items": [
      {
        "type": "item",
        "itemSku": "T-SHIRT-001-M",
        "itemQty": 2,
        "itemName": "T-Shirt Blau Größe M",
        "priceGross": 39.98,
        "currency": "EUR"
      },
      {
        "type": "shippingcost",
        "itemSku": "VERSAND",
        "itemQty": 1,
        "itemName": "Standardversand",
        "priceGross": 4.99,
        "vatPercentage": 19,
        "currency": "EUR"
      }
    ],
    "properties": [
      {
        "propertieKey": "payment_method",
        "propertieValue": "paypal"
      }
    ]
  }'

Erfolgreiche Antwort

{
  "valid": true,
  "errorsCount": 0,
  "errors": [],
  "orderId": 1002
}

Antwort mit Teilfehlern

Auch bei Teilfehlern (z.B. ein Property-Schlüssel war leer) wird der Auftrag erstellt. Die Fehler werden im errors-Array aufgelistet.

{
  "valid": true,
  "errorsCount": 1,
  "errors": ["properties.0.propertieKey is not filled"],
  "orderId": 1003
}

Fehler-Antworten

{
  "valid": false,
  "error": "param type missing"
}
{
  "valid": false,
  "error": "Kombination aus Marktplatz und ExterneID existiert bereits"
}

PUT /orders

Aktualisiert einen bestehenden Auftrag. Sie können Adressen, Status, Zeitstempel und externe ID ändern.

URL: PUT /public_api/<token>/orders

Request-Body (JSON)

ParameterTypPflichtBeschreibung
orderIdIntegerJaAuftrags-ID
statusIdIntegerNeinNeue Status-ID
externalIdStringNeinNeue externe ID
createdAtStringNeinNeues Erstellungsdatum (Datumsstring, wird mit strtotime geparst)
payedAtStringNeinNeues Zahlungsdatum (Datumsstring, wird mit strtotime geparst)
addressArrayNeinArray von Adress-Objekten (überschreibt bestehende Adressen des jeweiligen Typs)

Adressen

ParameterTypPflichtBeschreibung
address[].typeStringJa"shipping" oder "invoice"
address[].isoCode2StringJaLändercode ISO 3166-1 alpha-2 (darf nicht leer sein)
address[].companyStringNeinFirma
address[].firstnameStringNeinVorname
address[].lastnameStringNeinNachname
address[].additionalInfoStringNeinAdresszusatz
address[].streetStringNeinStraße
address[].houseNrStringNeinHausnummer
address[].zipStringNeinPostleitzahl
address[].cityStringNeinStadt
address[].provinceStringNeinBundesland / Provinz
address[].emailStringNeinE-Mail-Adresse
address[].telephoneStringNeinTelefonnummer

Beispiel-Request

curl -X PUT "https://meinefirma.scanalot.io/public_api/<token>/orders" \
  -H "Authorization: <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": 1001,
    "statusId": 3,
    "externalId": "EXT-2024-001-UPDATED",
    "address": [
      {
        "type": "shipping",
        "isoCode2": "DE",
        "firstname": "Max",
        "lastname": "Mustermann",
        "street": "Neue Straße",
        "houseNr": "5",
        "zip": "54321",
        "city": "München"
      }
    ]
  }'

Erfolgreiche Antwort

{
  "valid": true,
  "errors": [],
  "errorsCount": 0
}

Antwort mit Teilfehlern

{
  "valid": true,
  "errors": ["address.0.isoCode2 shipping is not filled"],
  "errorsCount": 1
}

Fehler-Antwort

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

PUT /orders/status

Ändert den Status mehrerer Aufträge gleichzeitig.

URL: PUT /public_api/<token>/orders/status

Request-Body (JSON)

ParameterTypPflichtBeschreibung
orderIdsArrayJaArray von Auftrags-IDs (Integer)
statusIdIntegerJaNeue Status-ID für alle angegebenen Aufträge

Beispiel-Request

curl -X PUT "https://meinefirma.scanalot.io/public_api/<token>/orders/status" \
  -H "Authorization: <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "orderIds": [1001, 1002, 1003],
    "statusId": 5
  }'

Erfolgreiche Antwort

{
  "valid": true
}

Fehler-Antwort

{
  "valid": false,
  "errors": ["Status nicht geupdated"]
}