Zum Hauptinhalt springen

Die offene REST-API von Keyline

Berechtigungen erstellen und verwalten mit Beispielen sowie neue Endpunkte

Patric avatar
Verfasst von Patric
Diese Woche aktualisiert

Die offiziellen Dokus von unseren beiden API findest Du hier:

Die Inbox-API eignet sich dazu von z.B. einem Web2Print-Shop einen Auftrag mit definierten Produktvorlagen in Keyline anzulegen.
Hier wird der virtuelle Einkaufswagen gepackt und mit einem Checkout erstellt Keyline Dir dann direkt eine Order mit Deinen definierten Daten und Produkten.


Mit der Advanced-API kannst Du dann weitere Einstellungen vornehmen.

Im Adminbereich unter Accounts/API-Berechtigungen kannst Du neue API-Keys erstellen und verwalten.

Die Keys werden benötigt, um Drittanwendungen wie z.B. Pipedrive, make.com, CRM-Systeme etc. einzubinden.

Wenn Du über den Button “API-Zugangsberechtigung anlegen” einen neuen API-Key erstellt hast, kannst Du diesen an den Dienstleister weitergeben und jederzeit auch wieder sperren.

Vorsicht: API-Keys, die Du auf diese Weise erstellt hast, haben Zugriff auf sämtliche Ressourcen Deines Keyline-Accounts. Du kannst daher API-Keys auch nur für bestimmte Organisationen freigeben, die dann nur unter diesem Namen agieren können. Dazu legst Du den API-Key bitte direkt bei der Organisation an (Vertrieb > Organisation).

Nicht mehr benötigte Keys sollten sofort gesperrt werden.
Jeder API-Key zählt auch zur Gesamtzahl der User dazu.

Bitte beachte, dass ein einmalig gesperrter Key nicht entsperrt werden kann.


Hier findest Du auch noch einige Beispiele in chronologischer Reihenfolge, die noch nicht in der offiziellen API dokumentiert sind:

Du kannst über die Browsersuche mit Strg+F bzw CMD+F einfach nach Schlagwörtern suchen. 🔎

Dann landest Du direkt bei Deinem gewünschten Endpunkt bzw. Funktion.


📦 Auflagen – Druckmengen pro Variante definieren

In diesem API-Abschnitt kannst Du tatsächliche Auflagen (Druckmengen) pro Produktvariante festlegen – ähnlich wie in der Oberfläche (UI) verfügbar.

Method

Endpoint

Description

GET

/production/products/:product_id/circulations

List all circulations for a product

GET

/production/products/:product_id/circulations/:id

Retrieve a single circulation

PATCH

/production/products/:product_id/circulations/:id

Update the actual_amount of a circulation

📤 Beispiel Payload:

{
"circulation":{
"actual_amount": 32
}
}

📄 Auftragstaschen, Lieferscheine & Etiketten

Über die API kannst Du verschiedene Produktions- und Logistikdokumente generieren.

Je nach angeforderten Inhaltstyp gibt die API entweder JSON-Metadaten oder direkt die PDF-Datei zurück.

Method

Endpoint

Beschreibung

GET

/production/products/:product_id/job_bag.pdf

Job bag (PDF as JSON link)

GET

/logistics/shipments/:shipment_id/delivery_note.pdf

Delivery note (PDF as JSON)

GET

/logistics/shipments/:shipment_id/proforma_invoice.pdf

Pro forma invoice

GET

/logistics/parcels/:parcel_id/label.pdf

Parcel label (PDF link)

PDF-Dateien:

Verwende dieselben Endpunkte mit folgendem Header:

Accept: application/pdf

Method

Endpoint

Beschreibung

GET

/production/products/:product_id/job_bag

Direct job bag PDF

GET

/logistics/shipments/:shipment_id/delivery_note

Direct delivery note PDF

GET

/logistics/shipments/:shipment_id/proforma_invoice

Pro forma invoice PDF

GET

/logistics/parcels/:parcel_id/label

Parcel label PDF

GET

/logistics/outsourcings/:outsourcing_id

Outsourcing Slip PDF


📘 Material Voreinstellungen:

Materialvorgaben können auf verschiedenen Ebenen hinterlegt werden:

Method

Endpoint

Beschreibung

GET/POST

/conception/products/:product_id/components/:component_id/material_presets

Material presets for a specific component

GET/POST

/conception/products/:product_id/components/:component_id/finishings/:finishing_id/material_presets

Material presets for a finishing within a component

GET/POST

/conception/products/:product_id/material_presets

Material presets at product level

GET/POST

/conception/products/:product_id/finishings/:finishing_id/material_presets

Material presets at product → finishing level

GET/POST

/conception/products/:product_id/packagings/:packaging_id/material_presets

Material preset for packaging

📤 Beispiel Payload:

{
"material_preset": {
"material_id": 1
}
}

📦 Verpackungs-Workflow (Schritt für Schritt)

Um den Verpackungsprozess zu automatisieren, folge diesem Ablauf:

1. Verpackungseintrag erstellen

POST /conception/products/{product_id}/packagings

2. Verpackungsdetails definieren (z. B. Labeltyp, Zielort etc.)

PATCH /conception/products/{product_id}/packagings/{packaging_id}

3. Pick-Anweisungen erstellen (welche Elemente verpackt werden sollen)

POST /conception/products/{product_id}/packagings/{packaging_id}/picks

👉 Wenn mehrere Sorten oder Verpackungseinheiten vorhanden sind, müssen alle Definitionen gemeinsam in einem einzigen JSON-Payload übergeben werden.

🚚 Hinweis zum Versand:

Wenn ein Produkt direkt versendet werden soll, muss folgende Eigenschaft gesetzt werden:

"deposition": "shipment"

Dadurch wird der Pick-Schritt übersprungen und direkt eine versandfertige Verpackung erstellt.

📦 Packagings während der Produktion abrufen

Wenn Du die Verpackungseinheiten eines Produkts während der Produktion einsehen möchtest, stehen Dir folgende Endpunkte zur Verfügung:

GET /production/products/:id/packagings/
GET /production/products/:id/packagings/:id

🛠️ Produktionsmittel ändern & Kalkulation neu berechnen

Diese Endpunkte ermöglichen es Dir, voreingestellte Produktionsmittel zu überschreiben und eine neue Kalkulation (Neuberechnung des Produktionspfads) auszulösen.


🔧 Produktionsmittel ändern (z. B. Maschine)

Um das Produktionsmittel für eine bestimmte Komponente zu ändern:

POST /conception/products/{product_id}/production_paths/{production_path_id}/production_flow_modifications

📤 Beispiel Payload:

{
"production_flow_modification": {
"modification": "preset",
"workable_type": "component",
"workable_id": 1361413,
"stock_task_id": 6579,
"means_of_production_id": 10319
}
}
  • workable_id: entspricht der Komponenten-ID

  • means_of_production_id: die neue Maschine bzw. das Produktionsmittel

  • stock_task_id: die spezifische Task-ID innerhalb des Produktionsflusses


♻️ Produktionspfad neu berechnen (Konzeption)

Nachdem Du Änderungen vorgenommen hast, kannst Du eine neue Kalkulation anstoßen:

POST /conception/products/{product_id}/production_paths/{production_path_id}/conceptualize

Das ist nicht zwingend erforderlich, wird aber empfohlen, um Zeiten und Kosten zu aktualisieren.


✂️ Schneiden aktivieren

Um den Schneideschritt bei einem bestimmten Ausschießschema zu aktivieren:

PATCH /conception/products/{product_id}/components/{component_id}/imposings/{imposing_id}

📤 Beispiel Payload:

{
"imposing": {
"cutting": true
}
}

📐 Falzschema anpassen

Um das Falzmuster eines Ausschießschemas zu ändern:

PATCH /conception/products/{product_id}/components/{component_id}/imposings/{imposing_id}

📤 Beispiel Payload:

{
"imposing": {
"default_stock_folding_pattern_id": 983
}
}

Verfügbare Falzmuster kannst Du hier abrufen:

GET /configuration/stock_folding_patterns

🔄 Optionen für die Seitenanordnung:

Wert

Beschreibung

standalone

Einzelblatt

crossover

Seitenanordnung zusammenhängend

parallel

Paralleler Falz (z. B. Z-Falz)


🔍 Filter & Suchabfragen

Viele Endpunkte unterstützen leistungsstarke Filter- und Suchfunktionen über Query-Parameter.

Damit kannst Du gezielt Teilmengen von Daten abrufen – z. B. anhand von Datumsbereichen, Statuswerten oder Schlüsselwörtern.

🧾 Rechnungen

GET /accounting/invoices?billed_from=2024-08-28&billed_to=2025-08-22

  • billed_from, billed_to – Filter nach Rechnungsdatum

  • created_from, created_to – Filter nach Erstellungsdatum

📦 Aufträge

GET /sales/orders?state=draft

GET /sales/orders?created_from=2024-08-12&created_to=2024-09-12

GET /sales/orders?updated_from=2024-08-12&updated_to=2024-09-12

  • state – z. B. draft, confirmed, cancelled

  • created_from, updated_from – Filter nach Erstellungs- oder Änderungsdatum

⚙️ Produktions-Tasks

GET /production/tasks?search_term=offset

GET /production/tasks?state=running

GET /production/tasks?created_from=2020-06-27&created_to=2020-06-27

GET /production/tasks?updated_from=2020-11-13&updated_to=2020-11-13

GET /production/tasks?search_term=offsetdruck&state=ready

  • search_term – Schlagwortsuche (z. B. Maschine, Prozess, Produkt)

  • state – running, ready, completed

  • created_from, updated_from – Filter über Lebenszyklus der Tasks


✉️ Produktnotizen & Interne Kommentare

Du kannst Nachrichten an Produkte anhängen, um interne Hinweise oder Anweisungen zu dokumentieren.

GET /production/products/{product_id}/messages

POST /production/products/{product_id}/messages

PATCH /production/products/{product_id}/messages/{message_id}

DELETE /production/products/{product_id}/messages/{message_id}

📤 Beispiel Payload:

{
"text": "Dies ist eine Produktnotiz über die API."
}

📧 Angebots-E-Mail individuell anpassen

Du kannst den Betreff und den Inhalt der Angebots-E-Mail per API ändern – solange sich der Auftrag noch im Entwurfsstatus befindet.

POST /sales/orders/{order_id}/offer_mail_messages

📤 Beispiel Payload:

{
"mail_message": {
"subject": "Individueller E-Mail-Betreff über die API",
"content": "E-Mail-Inhalt über die API erstellt."
}
}

⚠️ Das Angebot wird nach dem Absenden direkt mit dem geänderten E-Mail-Text verschickt. Der Auftrag muss sich dafür noch im Entwurfsstatus (draft) befinden.


👥 Berater oder Teammitglied einem Auftrag zuweisen

Du kannst einem Auftrag einen Benutzer zuweisen und dabei seine Rolle festlegen (z. B. Kundenberater, Mediengestalter, Produktionsmitarbeiter etc.).

POST /sales/orders/{order_id}/assignments

📤 Beispiel Payload:

{
"assignment": {
"user_id": 4033,
"role": "customer_consultant"
}
}

🎭 Verfügbare Rollen:

  • customer_consultant

  • sales_representative

  • media_designer

  • prepress_employee

  • production_employee

  • accounting_employee

Die user_id kannst Du im Adminbereich unter Benutzerverwaltung einsehen.


📎 Document Callbacks (eigene Auftragstasche usw.)

Mit Document Callbacks kannst Du Standarddokumente von Keyline (z. B. die Auftragstasche) durch eigene Dokumente ersetzen, indem Du eine externe Dokumenten-URL hinterlegst.

POST /conception/products/{product_id}/document_callbacks

📤 Beispiel Payload:

{
"document_callback": {
"kind": "job_bag",
"url": "http://deine_dokumenten_url"
}
}

🔄 Callback ändern oder löschen

Du kannst Document Callbacks auch während der Produktionsphase verwalten:

PATCH /production/products/{id}/document_callbacks

DELETE /production/products/{id}/document_callbacks/{callback_id}

Oder während der Konzeptionsphase:

PATCH /conception/products/{id}/document_callbacks

DELETE /conception/products/{id}/document_callbacks/{callback_id}


Auftrag bestätigen (an Produktion übergeben)

Nutze folgenden Endpunkt, um einen Entwurfsauftrag freizugeben:

POST /sales/orders/{order_id}/confirm

Damit wird der Auftrag von „draft“ auf aktiv gesetzt und die Produktion gestartet.

📄 Auftragsbestätigung als PDF herunterladen

Nach der Bestätigung kannst Du die PDF wie folgt abrufen:

GET /sales/orders/{order_id}/confirmation.pdf


📝 Produktbeschreibung bearbeiten

Um die Produktbeschreibung manuell anzupassen:

PATCH /conception/products/{product_id}

📤 Beispiel Payload:

{
"custom_description": "Neue Produktbeschreibung über die API!"
}

⚖️ Produktgewicht manuell festlegen

Du kannst das automatisch berechnete Produktgewicht manuell überschreiben – über folgenden Endpunkt:

PATCH /conception/products/{product_id}/production_paths/{production_path_id}

📤 Beispiel Payload:

{
"weight_calculation_mode": "manual",
"product_weight": 123456
}

Der Wert für product_weight wird in Milligramm pro Stück angegeben (z. B. 123456 = 123,456 g).


Produkt abschließen

Um ein Produkt als vollständig produziert zu markieren:

PATCH /production/products/{product_id}/complete

Damit wird das Produkt abgeschlossen und der Status entsprechend aktualisiert.


📦 Fremdbeschaffung abrufen

Liste aller Fremdbeschaffungs-Vorgänge:

GET /logistics/outsourcings

Dies umfasst alle extern vergebenen Produktionsschritte, die über die Logistik verwaltet werden.


📫 Adressen ankündigen

Um Kundenadressen vorab anzukündigen (damit sie bereits über die Suche gefunden werden können):

POST /customer_relations/organizations/{organization_id}/address_announcements

Nach der Ankündigung ist die Adresse durch die Schnellsuche auffindbar und erscheint bei erstmaliger Verwendung automatisch in der zugehörigen Organisation.


🗂️ Tatsächliche Auflagen aus dem Archiv abrufen

Um die tatsächlich produzierte Auflage eines Produkts im Nachhinein zu prüfen:

GET /archive/products/{product_id}/circulations

GET /archive/products/{product_id}/circulations/{circulation_id}

Das ist besonders nützlich zur Kontrolle der realen Produktionsmengen und wenn Du über z.B. make.com Dir ein Szenario gebaut hast, welches den Kunden proaktiv informiert, wenn die Produktion abgeschlossen ist.


📦 Verpackungsprozess per API

Um den vollständigen Verpackungsablauf über die API zu automatisieren, folge diesem Ablauf:

1. Verpackungseinheit erstellen

POST /conception/products/{product_id}/packagings

2. Verpackungsdetails definieren

PATCH /conception/products/{product_id}/packagings/{packaging_id}

Hier kannst Du Eigenschaften wie Zielort (deposition), Etikettierung usw. festlegen.

3. Pick-Anweisungen erstellen

POST /conception/products/{product_id}/packagings/{packaging_id}/picks

Hiermit wird definiert, was in welche Verpackungseinheit gepackt wird.

Wenn Du mehrere Sorten oder Verpackungsarten hast, müssen diese in einem einzigen JSON kombiniert werden.

👉 Hinweis:

Wenn das Produkt direkt versendet wird, muss die Verpackung folgende Eigenschaft enthalten:

"deposition": "shipment"

In diesem Fall ist kein Pick erforderlich – die Verpackung wird direkt als versandbereit angelegt.


💸 Nachkalkulation und Abrechnen per API

Um eine Nachkalkulation für ein Produkt abzuschließen:

PATCH /billing/products/{product_id}

🧾 Rechnung aus abgeschlossenem Auftrag erstellen

Sobald ein Auftrag nachkalkuliert wurde, kannst Du daraus eine Rechnung erzeugen:

POST /accounting/customer_invoices/create_from_order?order_id={id}

🙅‍♂️ Ansprechpartner aus Rechnung oder Gutschrift entfernen

Wenn die Rechnung oder Gutschrift nur an die Rechnungsadresse (ohne benannten Ansprechpartner) gehen soll:

DEL /accounting/customer_invoices/:id/contact
DEL /accounting/credit_notes/:id/contact

Hat dies Ihre Frage beantwortet?