← Alle Themen · API

API: Anbindungen

Zurück zur API-Übersicht

Dieser Abschnitt deckt die API-Endpunkte für Marktplatz-Anbindungen ab. Aktuell steht das Feld-Mapping zur Verfügung, die Zuordnung zwischen Scanalot-Artikelfeldern und Marktplatz-Zielfeldern pro Konto. Die zugehörige Backend-Seite: Anbindungen → Feld-Mapping. Konzeptionelle Hintergründe und UI-Workflow stehen in Anbindungen, Feld-Mapping.

GET /markets/mapping_meta

Liefert die vollständigen Metadaten für die Feld-Mapping-UI: alle unterstützten Marktplätze inkl. Konten, deren festen Zielfeldern mit lokalisierten Labels und dem Dynamik-Prefix, sowie die drei Quellfeld-Listen (Artikel, Aufträge, Warenbewegungen).

URL: GET /public_api/<token>/markets/mapping_meta

Request

Keine Parameter.

Beispiel-Request

curl -X GET "https://meinefirma.scanalot.io/public_api/<token>/markets/mapping_meta" \
  -H "Authorization: <api-token>"

Erfolgreiche Antwort

{
  "valid": true,
  "markets": [
    {
      "key": "shopify",
      "name": "Shopify",
      "targetFields": ["title", "vendor", "productType", "tags", "desc", "price", "priceAdd", "priceRound", "barcode"],
      "targetFieldLabels": {
        "title": "Titel",
        "vendor": "Hersteller/Vendor",
        "productType": "Produkttyp",
        "tags": "Tags",
        "desc": "Beschreibung",
        "price": "Preis",
        "priceAdd": "Preisaufschlag",
        "priceRound": "Preisrundung",
        "barcode": "Barcode"
      },
      "dynamicPrefix": "{meta}",
      "accounts": [
        { "id": 1, "name": "Mein Shopify-Shop" }
      ]
    }
  ],
  "sourceFields": [
    { "key": "sku", "title": "SKU", "optionName": null, "optionKey": null, "optionSelectName": null, "options": [] },
    { "key": "name", "title": "Name", "optionName": null, "optionKey": null, "optionSelectName": null, "options": [] },
    { "key": "barcodes", "title": "Barcodes", "optionName": "name", "optionKey": "id", "optionSelectName": "BarcodeID", "options": [ { "id": 1, "name": "EAN" } ] },
    { "key": "sales_price", "title": "Verkaufspreis", "optionName": "name", "optionKey": "id", "optionSelectName": "SalesPriceID", "options": [ { "id": 1, "name": "UVP" } ] },
    { "key": "stock_phy", "title": "Bestand (Physisch)", "optionName": "name", "optionKey": "id", "optionSelectName": "Lager", "options": [ { "id": "all", "name": "Alle Läger" }, { "id": 1, "name": "Hauptlager" } ] },
    { "key": "image", "title": "Bild-URL", "optionName": null, "optionKey": null, "optionSelectName": "Position", "options": [], "freeText": true, "hint": "Position eintragen: 1 = erstes Bild, 2 = zweites, ..." }
  ],
  "orderSourceFields": [ /* Auftrags-Quellfelder */ ],
  "movementSourceFields": [ /* Warenbewegungs-Quellfelder */ ]
}

Markets

Alle unterstützten Marktplätze mit ihrem internen key:

Marktplätze ohne dynamicPrefix (null) unterstützen keine dynamischen Attribute über das Feld-Mapping.

Quellfelder (sourceFields)

Die Liste der verfügbaren Scanalot-Felder pro Mapping-Zeile. Jedes Quellfeld hat folgende Struktur:

Enthaltene Quellfelder:

Dynamische Zielfelder

Marktplätze mit dynamicPrefix != null erlauben beliebige weitere Zielfelder nach dem Muster {prefix}Name. Beispiele:

• {attr}Farbe, eBay/Kaufland/OTTO/About You/Temu Attribut „Farbe"
• {meta}custom_field, Shopify Metafeld „custom_field"

GET /markets/mapping_settings

Liefert die aktuell gespeicherten Mapping-Zeilen eines Markt-Konto-Paars.

URL: GET /public_api/<token>/markets/mapping_settings

Request-Parameter (Query-String)

Beispiel-Request

curl -X GET "https://meinefirma.scanalot.io/public_api/<token>/markets/mapping_settings?market=shopify&accountId=1" \
  -H "Authorization: <api-token>"

Erfolgreiche Antwort

{
  "valid": true,
  "data": [
    { "id": 10, "accountId": 1, "settingKey": "title", "settingRef": "name", "settingRefId": "" },
    { "id": 11, "accountId": 1, "settingKey": "barcode", "settingRef": "barcodes", "settingRefId": "1" },
    { "id": 12, "accountId": 1, "settingKey": "price", "settingRef": "sales_price", "settingRefId": "2" },
    { "id": 13, "accountId": 1, "settingKey": "vendor", "settingRef": "own", "settingRefId": "Mein Markenname" },
    { "id": 14, "accountId": 1, "settingKey": "{meta}material", "settingRef": "properties", "settingRefId": "7" }
  ]
}

Felder pro Zeile:

Fehler-Antworten

{ "valid": false, "error": "Market ungültig" }

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

POST /markets/mapping_settings

Speichert die Feld-Mappings eines Konto-Paars. Der Request ersetzt alle bestehenden Mappings dieses Konto-Paars komplett, eine selektive Pflege einzelner Zeilen ist nicht vorgesehen. Zeilen ohne key oder ref werden stillschweigend übersprungen.

URL: POST /public_api/<token>/markets/mapping_settings

Request-Body (JSON)

Beispiel-Request

curl -X POST "https://meinefirma.scanalot.io/public_api/<token>/markets/mapping_settings" \
  -H "Authorization: <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "market": "shopify",
    "accountId": 1,
    "settings": [
      { "key": "title",         "ref": "name" },
      { "key": "desc",          "ref": "desc" },
      { "key": "price",         "ref": "sales_price", "refId": "2" },
      { "key": "barcode",       "ref": "barcodes",    "refId": "1" },
      { "key": "vendor",        "ref": "own",         "refId": "Mein Markenname" },
      { "key": "{meta}material","ref": "properties",  "refId": "7" }
    ]
  }'

Erfolgreiche Antwort

{ "valid": true }

Fehler-Antworten

{ "valid": false, "error": "Market ungültig" }

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

Hinweise

• Jedes Konto hat sein eigenes Mapping. Zwei eBay-Konten können völlig unterschiedliche Zuordnungen haben.
• Welche Mapping-Zeilen beim Produkt-Export tatsächlich greifen, hängt vom Marktplatz-Client ab, jeder Marktplatz hat eigene API-Anforderungen und baut die Daten unterschiedlich zusammen. Details in den Anbindungs-Dokumenten der einzelnen Marktplätze unter Anbindungen.
• Bestand bei About You wird nicht über das Feld-Mapping gesteuert, sondern automatisch aus dem Scanalot-Lagerbestand übernommen.
• Marktplatz-spezifische Attribut-Mappings jenseits des Feld-Mappings (About You Property-Werte, Temu Property-Werte) werden hier noch nicht abgebildet.