Dokumenten-API

Mit der Dokumenten-API laden Sie Dokumente in einen Kanal hoch, rufen die verarbeiteten Daten ab und melden Workist, ob der Import in Ihr System geklappt hat. Alle Dokumenttypen bieten dieselben Operationen.

Die vollständigen Schemas aller Anfragen und Antworten stehen in der Swagger-Oberfläche. Diese Seite beschreibt, wie Sie die API einsetzen.

Grundlagen

• Basis-URL: https://api.workist.com/v1 (gleichwertig: https://api.workist.com/api/v1).
• Kein Schrägstrich am Ende. GET /orders funktioniert, GET /orders/ liefert 404.
• Authentifizierung: Jeder Aufruf enthält den Header Authorization: Bearer <API-Schlüssel>. Wie Sie einen Schlüssel erstellen, steht im Quickstart.
• Kanäle: Ein API-Schlüssel sieht nur die Kanäle, die für ihn freigegeben sind. Dokumente anderer Kanäle liefert die API nicht aus.
• Format: Antworten sind JSON. Uploads senden Sie als multipart/form-data, alle anderen Anfragen als JSON.
• Übertragungsart des Kanals: Wenn Ihr System die Ergebnisse per API abholt, stellen Sie im Kanal unter Upload die Übertragungsart API ein. Sonst überträgt Workist die Ergebnisse zusätzlich per SFTP, und erfolgreich übertragene Dokumente erscheinen nicht mehr unter imported=false.

Ressourcen

Dokumenttyp	Ressource
Bestellungen	/orders
Rechnungen	/invoices
Auftragsbestätigungen	/order-confirmations
Angebotsanfragen	/rfq
Lieferscheine	/delivery-notes
Leistungsverzeichnisse	/list-of-services

Operationen

Jede Ressource bietet dieselben sieben Operationen. Ersetzen Sie {ressource} durch den Pfad aus der Tabelle oben, z. B. /orders.

Methode	Pfad	Zweck
GET	/{ressource}	Dokumente auflisten (seitenweise, filterbar)
GET	/{ressource}/{id}	Ein Dokument abrufen
POST	/{ressource}	Datei in einen Kanal hochladen
DELETE	/{ressource}/{id}	Dokument löschen
PATCH	/{ressource}/{id}/meta	Absender und Betreff setzen
PUT	/{ressource}/{id}/mark_imported	Ergebnis des Imports in Ihr System zurückmelden
PUT	/{ressource}/{id}/assign_user	Dokument einem Benutzer zuweisen
POST	/list-of-services/{id}/generate-x94	GAEB-X94-Angebotsdatei aus einem X83-Leistungsverzeichnis erzeugen

Typischer Ablauf

1. Dokumente kommen per E-Mail, über die Workbench oder per POST /{ressource} in den Kanal.
2. Ihr System fragt regelmäßig alle abgeschlossenen, noch nicht übergebenen Dokumente ab, z. B. GET /orders?finished=true&imported=false, und liest alle Seiten (siehe Seiten).
3. Für jedes Dokument importiert Ihr System die Daten und meldet das Ergebnis mit PUT /orders/{id}/mark_imported: SUCCEEDED mit Ihrer Belegnummer oder FAILED mit der Fehlermeldung.
4. Gemeldete Dokumente erscheinen in der Abfrage aus Schritt 2 nicht mehr. Mit FAILED gemeldete Dokumente kommen zurück, sobald ein Benutzer sie in der Workbench korrigiert und abgeschlossen hat (siehe Import zurückmelden).

Statt regelmäßig abzufragen, können Sie sich per Webhook benachrichtigen lassen, sobald ein Dokument abgeschlossen ist, und es dann abrufen.

Dokumente abrufen

Filter

GET /{ressource} akzeptiert folgende Query-Parameter:

Parameter	Bedeutung
channel	Kanal-ID. Nur Dokumente dieses Kanals.
assistance_needed	true: nur Dokumente, die auf Bearbeitung in der Workbench warten. false: alle anderen.
finished	true: abgeschlossene, nicht verworfene Dokumente. false: noch nicht abgeschlossene Dokumente.
imported	true: erfolgreich übergeben (Rückmeldung SUCCEEDED oder erfolgreiche Übertragung per SFTP, AS2 oder ERP-Integration). false: noch nicht erfolgreich übergeben. Ohne import_failed gilt dabei import_failed=false.
import_failed	true: Übergabe fehlgeschlagen (z. B. Rückmeldung FAILED). false: alle anderen.
created_by	E-Mail-Adresse oder ID des Benutzers, der das Dokument hochgeladen hat.
assisted_by	E-Mail-Adresse oder ID des Benutzers, der das Dokument bearbeitet hat.
date_from	Erstellt ab diesem Zeitpunkt, ISO 8601 (YYYY-MM-DDTHH:MM:SSZ).
date_to	Erstellt bis zu diesem Zeitpunkt, ISO 8601.
show_unfinished_data	true: data auch für Dokumente befüllen, die noch in Verarbeitung sind. Standard: false.
page	Seitennummer, beginnend bei 1.
page_size	Einträge pro Seite, höchstens 10.

GET /{ressource}/{id} akzeptiert ebenfalls show_unfinished_data.

Seiten

Die Liste liefert höchstens 10 Dokumente pro Seite, älteste zuerst. Die Antwort hat diese Form:

{
  "total_count": 37,
  "next": "https://api.workist.com/v1/orders?finished=true&imported=false&page=2",
  "previous": null,
  "items": [ ... ]
}

• Rufen Sie next auf, bis der Wert null ist. Wer nur die erste Seite liest, verpasst Dokumente.
• Wenn Sie Dokumente während des Blätterns zurückmelden, fallen sie aus dem Filter imported=false heraus und die folgenden Seiten verschieben sich. Rufen Sie in diesem Fall immer wieder die erste Seite ab, bis items leer ist.

Datensatz

Jedes Dokument in items und jede Einzelabfrage hat diese Felder:

Feld	Inhalt
id	ID des Dokuments (UUID).
channel	ID des Kanals.
status	Verarbeitungsstatus, siehe Status.
sender	Absender, z. B. Absender der E-Mail.
subject	Betreff der E-Mail oder Dateiname.
created_at	Zeitpunkt des Eingangs.
updated_at	Zeitpunkt der letzten Änderung.
created_by	Benutzer, der das Dokument hochgeladen hat (first_name, last_name, email).
assigned_to	Zugewiesener Benutzer.
assisted_by	Benutzer, der das Dokument bearbeitet hat.
assisted_at	Zeitpunkt der Bearbeitung.
delivered_at	Zeitpunkt der erfolgreichen Übertragung per SFTP, AS2 oder ERP-Integration.
finished_at	Zeitpunkt des Abschlusses.
imported_at	Zeitpunkt, zu dem Ihr System den Import mit SUCCEEDED bestätigt hat.
email_file_url	Link zur Original-E-Mail, falls das Dokument per E-Mail kam.
input_file_url	Link zur verarbeiteten Datei.
input_file_name	Ursprünglicher Dateiname.
classified_files	Weitere Anhänge derselben E-Mail mit file_name, classification und url.
additional_file_urls	Links zu zusätzlichen Dateien, falls vorhanden.
workbench_url	Link zum Dokument in der Workbench.
external_reference	Referenz aus der letzten Rückmeldung, z. B. Ihre Belegnummer.
external_status	Status aus der letzten Rückmeldung.
external_message	Nachricht aus der letzten Rückmeldung, z. B. eine Fehlermeldung.
data	Die extrahierten Dokumentdaten, siehe Dokumentdaten.

Die Links zu Dateien sind höchstens 30 Minuten gültig. Laden Sie die Dateien direkt nach dem Abruf herunter oder rufen Sie das Dokument erneut ab, um neue Links zu erhalten.

Status

status	Bedeutung
PENDING	In Verarbeitung.
ON_HOLD	In der Workbench zurückgestellt.
ASSISTANCE_NEEDED	Wartet auf Bearbeitung in der Workbench.
ASSISTED	Bearbeitet, die Verarbeitung läuft weiter.
FINISHED	Abgeschlossen.
DELIVERED	Per SFTP, AS2 oder ERP-Integration übertragen.
IMPORTED	Ihr System hat den Import mit SUCCEEDED bestätigt.
FAILED	Verarbeitung oder Übergabe fehlgeschlagen, auch nach einer Rückmeldung FAILED.
REJECTED	Die Datei konnte nicht gelesen werden.
DISCARDED	Verworfen.
DELETED	Gelöscht. Gelöschte Dokumente liefert die API nicht aus.

Dokumentdaten

data enthält die Kopffelder des Dokuments und die Positionen unter line_items (bei Leistungsverzeichnissen unter positions). Die Feldnamen je Dokumenttyp zeigt die Swagger-Oberfläche.

• Es erscheinen nur Werte der Felder, die im Kanal aktiviert sind. Alle anderen Felder sind null.
• Solange ein Dokument weder bearbeitet noch abgeschlossen ist, ist data leer ({}). Mit show_unfinished_data=true erhalten Sie den aktuellen Zwischenstand.
• Mengen, Preise und Datumsangaben sind Texte, so wie sie in der Workbench stehen.

Dokument hochladen

POST /{ressource} mit multipart/form-data:

Feld	Pflicht	Inhalt
channel	Ja	ID des Kanals, in dem das Dokument verarbeitet wird.
file	Ja	Die Datei.
user	Nein	E-Mail-Adresse oder ID eines Benutzers, der als Ersteller eingetragen wird.

• Kanal-ID: Sie steht in der Adresszeile der Workbench, wenn der Kanal geöffnet ist (…/channels/<Kanal-ID>), und im Feld channel jedes Dokuments dieses Kanals. Der Kanal muss zum Dokumenttyp der Ressource passen.
• Dateitypen: BMP, CSV, DOC, DOCX, EML, HTML, JPEG, ODS, PDF, PNG, RTF, TIFF, TXT, XLS, XLSM, XLSX und XML. ZIP-Archive, Outlook-Nachrichten (MSG) und winmail.dat packt Workist aus und verarbeitet den Inhalt.
• Antwort: 201 mit dem neuen Dokument. Wenn eine Datei mehrere Dokumente ergibt (z. B. eine E-Mail mit mehreren Anhängen oder ein ZIP-Archiv), enthält die Antwort nur das erste. Die übrigen finden Sie über GET /{ressource}.

Import zurückmelden

Mit PUT /{ressource}/{id}/mark_imported melden Sie, ob Ihr System das Dokument übernommen hat. Alle Felder sind optional; ohne Inhalt gilt SUCCEEDED.

Feld	Inhalt
status	SUCCEEDED (Standard): Import erfolgreich, endgültig. FAILED: Import abgelehnt, das Dokument geht zurück in die Workbench. PENDING: Übergabe noch offen.
external_reference	Referenz des Dokuments in Ihrem System, z. B. die Auftragsnummer.
external_status	Status des Dokuments in Ihrem System.
external_message	Freitext, z. B. die Fehlermeldung Ihres Systems.

{
  "status": "FAILED",
  "external_reference": "",
  "external_status": "rejected",
  "external_message": "Artikel 4711 ist gesperrt"
}

Regeln:

• Nur abgeschlossene Dokumente können zurückgemeldet werden. Sonst antwortet die API mit 400 und Record not finished yet.
• SUCCEEDED ist endgültig. Eine weitere Rückmeldung zum selben Dokument lehnt die API mit 400 und Record already successfully delivered ab.
• PENDING lässt das Dokument in der Abfrage imported=false, z. B. wenn Ihr System es angenommen, aber noch nicht gebucht hat.
• Jede Rückmeldung überschreibt external_reference, external_status und external_message der vorherigen.

Was nach FAILED passiert

1. Das Dokument erhält den Status FAILED und gilt nicht mehr als abgeschlossen. Es erscheint wieder in der Liste offener Dokumente in der Workbench.
2. Beim Öffnen sehen Benutzer den Hinweis „Ihr System hat das Dokument mit der folgenden Antwort abgelehnt:" mit Referenz, Status und Nachricht aus Ihrer Rückmeldung.
3. Ein Benutzer klickt auf Erneut assistieren, korrigiert die Daten und schließt das Dokument ab, oder er verwirft es mit Verwerfen.
4. Nach dem erneuten Abschluss erscheint das Dokument wieder in GET /{ressource}?finished=true&imported=false, und Ihr System kann es erneut importieren.

Schreiben Sie deshalb eine verständliche Ursache in external_message. Sie ist das, was Ihre Kolleginnen und Kollegen in der Workbench lesen.

Weitere Operationen

Absender und Betreff setzen

PATCH /{ressource}/{id}/meta setzt Absender und Betreff, z. B. wenn Sie Dateien aus einem eigenen Postfach hochladen. Nur mitgesendete Felder werden geändert.

Feld	Inhalt
sender	Absender, z. B. Absender der Original-E-Mail.
subject	Betreff, z. B. Betreff der Original-E-Mail.

Benutzer zuweisen

PUT /{ressource}/{id}/assign_user mit {"user": "<E-Mail-Adresse oder ID>"} weist das Dokument einem Benutzer Ihrer Organisation zu. Unbekannte Benutzer lehnt die API mit 400 und {"user": ["User does not exist."]} ab.

Dokument löschen

DELETE /{ressource}/{id} löscht das Dokument und antwortet mit 204. Die API liefert das Dokument danach nicht mehr aus.

GAEB X94 erzeugen

Für Leistungsverzeichnisse, die als GAEB-X83-Datei eingegangen sind, erzeugt POST /list-of-services/{id}/generate-x94 eine X94-Angebotsdatei. Sie senden Ihre Preise je Position und Ihre Lieferantendaten, Workist liefert die XML-Datei zurück.

• items (Pflicht): eine Liste mit einem Eintrag je Position. source_id ist die GAEB-ID der Position und muss zu einer Position des Leistungsverzeichnisses passen. Optional: article_number, article_characteristics (normal, alternate oder provis), quantity, unit, vat, net_price, price_basis, offer_price, price_basis_unit, ean, article_description.
• supplier_info (Pflicht): id_no, tax_no, reg_no und address mit name1, street, p_code, city, country. Alle Unterfelder sind optional.
• Antwort: 200 mit der X94-Datei (application/xml) als Download.
• Fehler: 400 mit {"error": "...", "message": "..."}, z. B. wenn das Dokument keine gültige X83-Datei ist oder eine source_id nicht passt.

Fehler

HTTP-Status	Ursache	Antwort
400	Ungültige Anfrage	{"detail": "<Meldung>"} oder je Feld {"<feld>": ["<Meldung>"]}, z. B. {"channel": ["Channel does not exist"]} oder {"file": ["Unsupported file type"]}
401	API-Schlüssel fehlt, ist unbekannt oder abgelaufen	{"detail": "Authentication credentials were not provided."}, {"detail": "Invalid token"} oder {"detail": "Integration has expired"}
404	Dokument nicht gefunden, Kanal nicht für den Schlüssel freigegeben, Seite außerhalb des Bereichs oder Pfad mit / am Ende	{"detail": "<Meldung>"}

Ein abgelaufener Schlüssel funktioniert erst wieder, wenn Sie in der Workbench das Ablaufdatum ändern oder entfernen.