Benutzung der Stammdaten-API

Workist benötigt die Stammdaten aus dem ERP-System. Stammdaten können übermittelt werden:

• Als Datei
• Als Link zu einer öffentlich zugänglichen Datei
• Als Liste von Objekten im JSON-Format (in Chunks/Teilstücken)

Bis zu sieben Gruppen von Stammdaten-Objekten werden unterstützt:

Gruppe	Pflicht
Kunden (Auftraggeber / Debitor)
Lieferadressen (Warenempfänger)	optional
Rechnungsadressen (Rechnungsempfänger)	optional
Ansprechpartner (der Warenempfänger)	optional
Artikel
Kundenspezifische Artikel	optional
Rahmenverträge	optional

Jede Gruppe wird durch eine lookup_definition_id identifiziert.

API Dokumentation (Swagger): https://api.workist.com/v1/swagger/

Hinweise zu Massen-Importen

Workist empfängt stets vollständige Stammdaten-Importe (keine Delta-Updates). Große Datenmengen können paginiert werden (Chunks von je 1000 Elementen).

Vorgehen:

1. Erstellen Sie einen Batch-Import mit "batched": true in POST /master-data/imports → gibt import_id zurück
2. Fügen Sie Daten-Batches hinzu per POST /master-data/imports/:import_id/data
3. Lösen Sie die Verarbeitung manuell aus per POST /master-data/imports/:import_id/start

import requests
import json

def chunk(it, size):
    from itertools import islice
    it = iter(it)
    return iter(lambda: tuple(islice(it, size)), ())

base_url = "https://api.workist.com/api/v1/master-data"
lookup_definition_id = "<Article Lookup Definition ID>"
token = "<Your Auth Token>"
headers = {"Authorization": f"Bearer {token}"}

articles = [
    {"article_id1": "123", "description": "abc", "order_units": ["PCS", "KG"]},
    {"article_id1": "456", "description": "def", "order_units": ["KG"]},
    {"article_id1": "789", "description": "def", "order_units": ["M"]}
]
articles_chunked = list(chunk(articles, 1))

url = f"{base_url}/articles/imports"
response = requests.request("POST", url, headers=headers, data={
    "lookup_definition_id": lookup_definition_id,
    "batched": True,
})
import_id = response.json().get("import_id")

for articles_batch in articles_chunked:
    url = f"{base_url}/imports/{import_id}/data"
    response = requests.request("POST", url, headers=headers, data={"data": json.dumps(articles_batch)})

url = f"{base_url}/articles/start"
response = requests.request("POST", url, headers=headers)

Kunden

clients = [
    {"client_id1": "C-001", "company_name": "Test SE", "address1": "Test street 1", ...},
    {"client_id1": "C-002", "company_name": "Muster GmbH&Co. KG", ...}
]
url = f"{base_url}/clients/imports?replace=True"
payload = {"lookup_definition_id": "<your lookup definition>", "data": json.dumps(clients)}
response = requests.request("POST", url, headers=headers, data=payload)

Lieferadressen

Verknüpfung mit Kunden über partition_id. Das Feld für die Lieferadresse sollte ausschließlich Firmennamen enthalten.

delivery_addresses = [
    {"partition_id": "C-001", "address_id1": "L-001", "name": "Tester 2 GmbH", "address1": "Test street 2", ...}
]
url = f"{base_url}/addresses/imports?replace=True"
payload = {"lookup_definition_id": "<your lookup definition>", "data": json.dumps(delivery_addresses)}
response = requests.request("POST", url, headers=headers, data=payload)

Artikel

order_unit muss als Array übermittelt werden (z.B. ["KG", "STK"]).

articles = [
    {"article_id1": "ART-001", "description": "Sensor Module", "order_units": ["PCE", "KG"]},
]
url = f"{base_url}/articles/imports?replace=True"
payload = {"lookup_definition_id": "<your lookup definition>", "data": json.dumps(articles)}
response = requests.request("POST", url, headers=headers, data=payload)

Kundenspezifische Artikel

Jeder Eintrag braucht partition_id (Kundenverweis) und article_id1 (interner Artikel). article_id2 enthält die Kundenartikelnummer.

client_articles = [
    {"partition_id": "C-001", "article_id1": "ART-001", "article_id2": "CUST-ART-555"},
]
url = f"{base_url}/articles/imports?replace=True"
payload = {"lookup_definition_id": "<your client-specific lookup definition>", "data": json.dumps(client_articles)}
response = requests.request("POST", url, headers=headers, data=payload)

Import Status

url = f"https://api.workist.com/api/v1/master-data/imports/{import_id}"
response = requests.request("GET", url, headers=headers)
# Gibt zurück: {"id": "...", "status": "SUCCESS", "lookup_type": "ARTICLE_LOOKUP", ...}

Postman Collection

Eine Postman Collection für die Stammdaten-API ist auf Anfrage verfügbar. Wenden Sie sich an Ihren Workist-Ansprechpartner oder an support@workist.com.

Lookup Definition IDs

Die Lookup-IDs können pro Channel in Workist eingestellt werden:

1. Kanal auswählen
2. Menü oben rechts öffnen → „Kanal verwalten"
3. „Stammdaten" auswählen
4. IDs kopieren

Weitere Details: Lookup-IDs abrufen