/
[2-4] INBOUND OUTBOUND CREATE API

PEIQ Knowledge Base

[2-4] INBOUND OUTBOUND CREATE API

Owned by Franziska Franz, created
Last updated: 2025-03-07 by Alexander Steichele
11 min read

Transportverfahren

Übertragung per Restful API (https)

Objekt

Artikel, Bilder, NGEN-ID

Trigger

Request durch Drittsystem

Typische Drittsysteme

Typische Anbindungen sind Drittsysteme zur Content-Erstellung für Online

Beispieldaten

→ siehe swagger-Dokumentation

Mit der hier beschriebenen Schnittstelle können CREATE-Artikel (auch einzelne Ausprägungen) durch Dritte via Restful API inkl. Bilder von extern abgefragt & in Drittsysteme exportiert werden oder vom Drittsystem neue CREATE-Artikel angelegt bzw. geupdatet werden.

Inhaltsverzeichnis

Funktionalitäten & Endpunkte der CREATE API

Der aktuelle Funktionsumfang kann über das Swagger User Interface eingesehen werden:
https://mt-master-create.peiq.cloud/createapi/createapi.html#/

GET: Abfragen von API Infos

get /createapi/v1/info

Von einem Drittsystem aus können per CREATE API zur Fehleranalyse Infos abgefragt werden, mit welchem Benutzer und welcher Version die API aufgerufen wurde.

Beispiel get Aufruf:
{{baseUrl}}/createapi/v1/info
cURL:
curl --location --request GET 'https://mt-master-create-test.peiq.cloud/createapi/v1/info' \ --header 'Authorization: Bearer [TOKEN]'

Response

{ "version": "1.0.8306.16415", "user": "[USERNAME]" }

GET: Abfragen zuletzt geänderter CREATE-Artikel

get /createapi/v1/articles

Von einem Drittsystem aus können per CREATE API alle zuletzt geänderten CREATE-Artikel aus der Datenbank abgefragt werden. Als Ergebnis wird eine Liste mit IDs ausgegeben.

Mögliche Parameter

  • limit: max. Anzahl der Artikel, die gesucht werden sollen (optional)

  • eventName: changed (Pflicht)

  • offset: Gibt an, wie viele Artikel in der Ergebnisliste am Anfang übersprungen werden sollen (optional)

Beispiel get Aufruf:
{{baseUrl}}/createapi/v1/articles/events?eventName=changed&offset=0&limit=50
cURL:
curl --location --request GET 'https://mt-master-create-test.peiq.cloud/createapi/v1/articles/events?eventName=changed&offset=0&limit=50' \ --header 'Authorization: Bearer [TOKEN]'

Response

{ "offset": "45", "data": [ { "id": "202-2117139" }, { "id": "202-2110803" }, { "id": "202-2117170" }, { "id": "202-2117171" }, { "id": "202-2117172" } ] }

 

GET: Abfragen von zuletzt geänderten CREATE-Artikeln mit dem Filter “Kanal” und “Kanal & Status”

get /createapi/v1/articles/events?eventName=changed&channel

Von einem Drittsystem aus können per CREATE API nach zuletzt geänderten CREATE-Artikel nach dem Kanal aus der Datenbank gefiltert und abgefragt werden. Als Ergebnis wird eine Liste mit IDs ausgegeben.

Mögliche Parameter

  • Kanal “Online”

  • Kanal “Print”

Beispiel get Aufruf:
{{baseUrl}}/createapi/v1/articles/events?eventName=changed&channel=Online
Response
{ "offset": "23", "data": [ { "id": "204-4988600" } ] }

 

get /createapi/v1/articles/events?eventName=changed&channel&status

Von einem Drittsystem aus können per CREATE API nach zuletzt geänderten CREATE-Artikel nach dem Kanal und Status aus der Datenbank gefiltert und abgefragt werden. Als Ergebnis wird eine Liste mit IDs ausgegeben.

Mögliche Parameter

  • channel=Online

  • channel=Print

  • status=Erfassung

  • status=Publiziert

  • status=Revision

Beispiel get Aufruf:
{{baseUrl}}/createapi/v1/articles/events?eventName=changed&channel=Online&status=Publiziert
Response
{ "offset": "729", "data": [ { "id": "204-4994283" } ] }

GET: Einzelne CREATE-Artikel abfragen

Alternativ kann auch eine feste Artikel-ID als Variable in der Postman Environment hinterlegt werden.

Mögliche Parameter

  • limit: max. Anzahl der Artikel, die gesucht werden sollen

  • eventname: changed

  • offset oder offsetindex: Gibt an, wie viele Artikel in der Ergebnisliste am Anfang übersprungen werden sollen

Beispiel get Aufruf:
{{baseUrl}}/createapi/v1/articles/{{cid}}
cURL:
curl --location --request GET 'https://mt-master-create-test.peiq.cloud/createapi/v1/articles/202-2117130' \ --header 'Authorization: Bearer [TOKEN]'

Response

Als Ergebnis wird die CID des erstellten Artikels ausgegeben.

{     "id": "202-2334673" }

POST: CREATE-Artikel anlegen

post /createapi/v1/articles

Von einem Drittsystem aus können per CREATE API alle CREATE-Artikel angelegt werden. Dabei muss der Artikel über die Schnittstelle als gültiges JSON im body als Binärdaten übergeben werden.

Zum Anlegen eines CREATE-Artikels werden mindestens “id”, “type” und “template_name” in “variants” (Artikel-Ausprägung) benötigt.

Mögliche Parameter

Keine Parameter.

Beispiel post Aufruf:
{{baseUrl}}/createapi/v1/articles

JSON:

{ "external_id": "", "keywords": [ { "name": "Wirtschaft", "type": "topic", "priority": 5 }, { "name": "Politik", "type": "topic", "priority": 4 }, { "name": "News", "type": "topic", "priority": 3 } ], "seo": { "title": "SEO Titel", "description": "SEO Beschreibung" }, "variants": [ { "id": "HrlLaqcemUywP-UWtM9mcA", "type": "Main", "template_name": "Story_D", "status": "Erfassung", "channels": [ { "name": "Online", "publish": false, "publish_start": "2022-08-11T00:00:00+00:00", "publish_end": "2022-08-31T00:00:00+00:00", "publish_day": "", "status": "Erfassung", "paid_content": false, "categories": [ { "id": "1-15826189", "paths": [ { "path": "anzeigensonder" } ] } ] }, { "name": "Print", "publish": true, "publish_start": "", "publish_end": "", "publish_day": "2022-08-17", "status": "Fertig", "categories": [ { "id": "", "paths": [ { "path": "ma/anz" } ] } ] } ], "contents": [ { "type": "catchline", "value": { "text": "Das ist die Dachzeile." } }, { "type": "title", "value": { "text": "Das ist der Titel." } }, { "type": "subline", "value": { "text": "Das ist der Untertitel." } }, { "type": "teaser", "value": { "text": "Das ist der Teaser mit <strong>fett</strong>, <em>kursiv</em> und einem <a href=\"https://peiq.de\">Link</a>." } }, { "type": "paragraph", "value": { "text": "Das ist ein Textabsatz mit <strong>fett</strong>, <em>kursiv</em> und einem <a href=\"https://peiq.de\">Link</a>." } }, { "type": "subtitle", "value": { "text": "Das ist ein Zwischentitel." } }, { "type": "paywall" }, { "type": "question", "value": { "text": "How are you?" } }, { "type": "answer", "value": { "text": "I am fine." } }, { "type": "author", "value": { "text": "Alex API Tester" } }, { "type": "location", "value": { "text": "Bergkirchen" } }, { "type": "source", "value": { "text": "postman" } }, { "type": "quote", "value": { "text": "Phantasie ist wichtiger als Wissen, denn Wissen ist begrenzt.", "source": "Albert Einstein" } }, { "type": "list", "value": [ { "text": "Das ist ein Listeneintrag mit <strong>fett</strong>, <em>kursiv</em> und einem <a href=\"https://peiq.de\">Link</a>." } ] }, { "type": "teaser_image", "value": { "image": { "id": "202-2119498" } } }, { "type": "image", "value": { "image": { "id": "202-2119472", "floating": true } } }, { "type": "article_link", "value": { "type": "Standard", "id": "1-3456789", "title": "Das ist der Linktitel." }, { "type": "embed", "value": { "id": "202-2118864" } } ] } ] }
cURL:
curl --location --request POST 'https://mt-master-create-test.peiq.cloud/createapi/v1/articles' \ --header 'Authorization: Bearer [TOKEN]' \ --header 'Content-Type: text/plain' \ --data-raw '{ "external_id": "", "keywords": [ { "name": "Wirtschaft", "type": "topic", "priority": 5 }, { "name": "Politik", "type": "topic", "priority": 4 }, { "name": "News", "type": "topic", "priority": 3 } ], "seo": { "title": "SEO Titel", "description": "SEO Beschreibung" }, "variants": [ { "id": "HrlLaqcemUywP-UWtM9mcA", "type": "Main", "template_name": "Story_D", "status": "Erfassung", "channels": [ { "name": "Online", "publish": false, "publish_start": "2022-08-11T00:00:00+00:00", "publish_end": "2022-08-31T00:00:00+00:00", "publish_day": "", "status": "Erfassung", "paid_content": false, "categories": [ { "id": "1-15826189", "paths": [ { "path": "anzeigensonder" } ] } ] }, { "name": "Print", "publish": true, "publish_start": "", "publish_end": "", "publish_day": "2022-08-17", "status": "Fertig", "categories": [ { "id": "", "paths": [ { "path": "ma/anz" } ] } ] } ], "contents": [ { "type": "catchline", "value": { "text": "Das ist die Dachzeile." } }, { "type": "title", "value": { "text": "Das ist der Titel." } }, { "type": "subline", "value": { "text": "Das ist der Untertitel." } }, { "type": "teaser", "value": { "text": "Das ist der Teaser mit <strong>fett</strong>, <em>kursiv</em> und einem <a href=\"https://peiq.de\">Link</a>." } }, { "type": "paragraph", "value": { "text": "Das ist ein Textabsatz mit <strong>fett</strong>, <em>kursiv</em> und einem <a href=\"https://peiq.de\">Link</a>." } }, { "type": "subtitle", "value": { "text": "Das ist ein Zwischentitel." } }, { "type": "question", "value": { "text": "How are you?" } }, { "type": "answer", "value": { "text": "I am fine." } }, { "type": "author", "value": { "text": "Alex API Tester" } }, { "type": "location", "value": { "text": "Bergkirchen" } }, { "type": "source", "value": { "text": "postman" } }, { "type": "quote", "value": { "text": "Phantasie ist wichtiger als Wissen, denn Wissen ist begrenzt.", "source": "Albert Einstein" } }, { "type": "list", "value": [ { "text": "Das ist ein Listeneintrag mit <strong>fett</strong>, <em>kursiv</em> und einem <a href=\"https://peiq.de\">Link</a>." } ] }, { "type": "teaser_image", "value": { "image": { "id": "202-2119498" } } }, { "type": "image", "value": { "image": { "id": "202-2119472" } } }, { "type": "embed", "value": { "id": "202-2118864" } } ] } ] }'

Response

Als Ergebnis wird die CID des erstellten Artikels ausgegeben.

{     "id": "202-2119506" }

PUT: Einzelne Artikel updaten

Über die CREATE API können bereits existierende CREATE-Artikel bzw. Ausprägungen darin aktualisiert werden.

Ausprägungen können nur aktualisiert werden, solange noch kein Kanal einer Ausprägung publiziert wurde.

Ist mind. ein Kanal einer Ausprägung bereits publiziert worden, wird der gesamte PUT-Request abgelehnt und eine entsprechende Meldung als Response ausgegeben:

{     "error": "Article update is not allowed because for variant '[variantid]' the channel '[channelname]' has already been published." }

Zur Aktualisierung einer Ausprägung in der CREATE API muss im PUT-Request die Artikel-CID des CREATE-Artikels angegeben werden.

Zum Updaten eines CREATE-Artikels werden mindestens id, type und ein template_name benötigt.

Im Body müssen alle Daten, die aktualisiert werden sollen, als gültiges JSON übergeben werden.

Eine nicht angegebene Variante wird auch nicht geändert.

Wenn im Text etwas aktualisiert werden soll, muss der gesamte Content-Bereich noch einmal mitgeschickt werden. Das heißt, der Text einer Ausprägung (“variant”) wird beim Update stets überschrieben. Felder, die nicht angegeben werden, werden nicht verändert. Felder, die leer angegeben werden, werden leer gesetzt.

Beim Update kommen keine Daten aus dem Ziel-System zurück.

Beispiel put Aufruf:
{{baseUrl}}/createapi/v1/articles/202-2135672
cURL:
curl --location --request PUT 'https://mt-master-create-test.peiq.cloud/createapi/v1/articles/202-2119506' \ --header 'Authorization: Bearer [TOKEN]' \ --header 'Content-Type: text/plain' \ --data-raw '{ "external_id": "", "variants": [ { "id": "", "type": "", "template_name": "", "status": "", "channels": [ { "name": "Online", "publish": true, "publish_start": "", "publish_end": "", "publish_day": "", "status": "", "paid_content": true, "categories": [ { "id": "", "paths": [ { "path": "" } ] } ] } ], "contents": [ { "type": "catchline", "value": { "text": "Update: Dachzeile." } }, { "type": "title", "value": { "text": "Update: Titel." } }, { "type": "subline", "value": { "text": "Update: Untertitel." } }, { "type": "teaser", "value": { "text": "Update: Teaser mit <strong>fett</strong>, <em>kursiv</em> und einem <a href=\"https://peiq.de\">Link</a>." } }, { "type": "paragraph", "value": { "text": "Update: Textabsatz mit <strong>fett</strong>, <em>kursiv</em> und einem <a href=\"https://peiq.de\">Link</a>." } }, { "type": "subtitle", "value": { "text": "Update: Zwischentitel." } }, { "type": "author", "value": { "text": "" } }, { "type": "location", "value": { "text": "" } }, { "type": "source", "value": { "text": "" } }, { "type": "quote", "value": { "text": "Update Zitat", "source": "Update: Zitatquelle" } }, { "type": "list", "value": [ { "text": "Update: Das ist ein Listeneintrag mit <strong>fett</strong>, <em>kursiv</em> und einem <a href=\"https://peiq.de\">Link</a>." } ] } ] } ] }'

Response

Als Ergebnis wird die ID des aktualisierten Artikels ausgegeben.

{     "id": "202-2135672" }

Sonderfall: Artikel-Ausprägung löschen

Wenn im JSON bei einer Ausprägung der Status “Entfernen” angegeben wird, so wird die Ausprägung des CREATE-Artikels gelöscht.

Beim Status “Entfernen” werden auch alle Subvarianten (z. B. Infoboxen), die von der zu löschenden Ausprägung aus referenziert werden, mit gelöscht.

Validierungen beim POST/PUT von CREATE-Artikeln

Validierung Artikel-Daten

Prüfung Pflichtfelder

  • Es müssen mind. ‘id’ und ‘template_name’ angegeben werden, damit ein Artikel angelegt wird (type kann weggelassen werden und ist automatisch ‘Main’)

  • Bei den ‘contents’-Elementen (z. B. Titel, Unterteil, Paragraph usw.) wird geprüft, ob die notwendigen Daten-Strukturen korrekt angegeben wurden. Bei unbekannten contents-Elementen wird eine entsprechende Fehlermeldung ausgegeben.

  • Wenn CIDs von Clustern übergeben werden, wird geprüft, ob der Cluster (image, lead_image, teaser_image, image_gallery, embed, article_link) auch im System vorhanden ist. Gibt es ein Element/Cluster nicht, wird eine entsprechende Fehlermeldung ausgegeben.

  • Wenn ein ‘subarticle’ (Infobox, Onlinebox) angegeben wird, muss die ‘variant_id’ angegeben sein und in den Requestdaten muss eine dazu passende variante mit angegeben sein ('variant_id' muss eindeutig sein).

Prüfung Kanal-übergreifender Metadaten (Parametrisierbar)

Es können in der CREATE-API bestimmte Metadaten, deren Inhalt durch PEIQ fest vorgegeben ist - z. B. durch Wertelisten oder Autocompleter, inhaltlich geprüft werden. Werden Artikel-Metadaten bei einem POST oder PUT geschickt, die nicht erlaubt sind, wird ein entsprechender Fehler ausgegeben.

Setzt ein Verlag kundenspezifische Metadaten in der CREATE Kanalsteuerung ein, können diese mittels Parametrisierung im Customizing in die Validierung mit aufgenommen werden.

Validierung Kanal-Daten

  • ‘channels’: es muss der korrekte Name des Kanals angegeben sein, so wie er in CREATE verwendet wird. Wird ein ungültiger Name angeliefert, wird ein entsprechender Fehler ausgegeben.

  • categories pro channel:

    • Den ‘categories’ entspricht ein Mappenpfad imRubrikenbaum. Wenn eine ID angegeben ist, muss ein entsprechender DMappeDigital-Cluster in PRINT NGEN vorhanden sein.

    • Wenn ‘id’ leer ist und ein ‘path’ angegeben ist, wird versucht über den Pfad der DMappeDigital-Cluster zu bestimmen.

Prüfung Kanal-spezifischer Metadaten (Parametrisierbar)

Es können in der CREATE-API bestimmte kanalspezifische Metadaten, die in den KanalInfos (z. B. an der Ausprägung gespeichert werden und deren Inhalt durch PEIQ fest vorgegeben ist - z. B. durch Wertelisten oder Autocompleter, inhaltlich geprüft werden. Werden Artikel-Metadaten bei einem POST oder PUT geschickt, die nicht erlaubt sind, wird ein entsprechender Fehler ausgegeben.

Setzt ein Verlag kundenspezifische Metadaten in der CREATE Kanalsteuerung ein, können diese mittels Parametrisierung im Customizing in die Validierung mit aufgenommen werden.

Validierung Ausprägungs-Daten

  • variants: Die id der variants (=Ausprägungen ) muss eindeutig sein. Es können also nicht mehrere Ausprägungen mit identischer id angelegt werden.

Bilderhandling

Für das Handling (Anlegen, Abholen, Updaten) der Bilder in CREATE-Artikeln wird die DAM API benötigt.

Beim Anlegen und Updaten von Artikeln wird in der CREATE API - sofern Bilder im Status “Original” angeliefert bzw. im JSON referenziert sind - immer eine Bildkopie erstellt und diese statt des Originals über die Angabe der Bild-CID im Artikel verlinkt. Bilder im Status “Unverschlagwortet” werden abgewiesen.

Abfragen der Bilder in CREATE-Artikeln inkl. Bild-Metadaten

Bilder, die in CREATE-Artikeln verwendet wurden, können inkl. der an den Bild-Clustern gespeicherten Metadaten über die DAM API abgefragt werden.

Über die im CREATE Artikel-JSON referenzierte ID des Artikelbildes, z. B. "id": "202-2119472", kann dieses über eine get Abfrage in der DAM API unter Angabe der entsprechenden Bild-Auflösung (Empfehlung: HighRes) heruntergeladen werden.

Ausführliche Informationen dazu finden sich unter [0-21] PEIQ DAM API | Suche nach bestimmten Bildern.

Beispiel get Aufruf:
{baseUrl}/images/202-2119472/HighRes

Die Metadaten des Bildes können ohne den Zusatz für die Auflösung abgeholt werden.

Beispiel get Aufruf:
{baseUrl}/images/202-2119472

Response

{ "archive_id": null, "caption": "Abraham vs. KhorenGevor ging nach einem linken Haken in der elften Runde zunächst in die Knie und kippte dann benommen hinten über kippte.Arthur Abraham besteigt als König den Ring in der Berliner Max-Schmeling-Halle. Vor 6000 Zuschauern musste er seinen IBF-Gürtel im Mittelgewicht gegen Khoren Gevor verteidigen. Der 28-Jährige Herausforderer kam in den ersten Runden oft zum Schlag, Abraham verhinderte Schlimmeres mit seiner Doppeldeckung. Nur einmal geriet Abraham ins Straucheln. Das lag allerdings mehr daran, dass Gevor ihm beim Angriff ein wenig umgrätschte. Abraham behielt dennoch einen kühlen Kopf und zog seine Taktik unbeeidruckt durch. Nach fünf Runden ließ die Kraft bei beiden ein wenig nach. Während der 27-Jährige Abraham durch passive Boxweise Kraft sammelte, boxte sich Kohen müde zum Ende des Kampfes drehte Abraham wieder auf und landete harte Schläge am Kopfs seines Herausforderers. Am Ende behielt Abraham dank seiner harten Punches die Oberhand gegen Universum-Schützling Gevor, der nach einem linken Haken in der elften Runde zunächst in die Knie ging und dann benommen hinten über kippte. &lt;?ZE?&gt;Der Ringrichter entschied sofort auf Abbruch und technischen Ko. Khoren wurde später aufgrund einer schweren Gehirnerschütterung behandelt.BERLIN - AUGUST 18: Khoren Gevor of Germany lies on the ground after he was knocked out by Arthur Abraham during the IBF World Championship Middleweight fight between Arthur Abraham and Khoren Gevor at the Max Schmeling Halle August 18, 2007 in Berlin, Germany. (Photo by Martin Rose/Bongarts/Getty Images)", "creation_timestamp": "2022-12-07T13:56:48+01:00", "creation_user": "create_tester_01", "filename": "1-15734248", "honorar_id": null, "object": "ta", "edition": null, "origin": "Create", "original_id": "DBild/202-4284773", "id": "202-2119472", "by_line": "Martin Rose", "category": "ku", "location": null, "credit": "Bongarts/Getty Images", "country": null, "date_time_created": null, "object_name": null, "service_identifier": null, "source": null, "special_instructions": null, "title": "Arthur Abraham v Khoren Gevor - IBF Middleweight World Championship", "urgency": null, "status": "Kopie", "underline": "Normales Bold", "image_source": "Bongarts/Getty Images", "image_region": null, "keywords": [ { "name": "berlin", "type": "location", "priority": 4 }, { "name": "germany", "type": "location", "priority": 3 }, { "name": "BOX", "type": "organisation", "priority": 1 }, { "name": "Boxen", "type": "topic", "priority": 5 } ], "modification_timestamp": "2022-12-07T13:57:02+01:00", "modification_user": "create_tester_01", "usage_instructions": null, "width": 696, "height": 464, "sha1": "ihhuu2hdDg7lM389o35Hme5jKh9" }

Auch das Originalbild der im CREATE-Artikel verwendeten Produktionskopie kann über die DAM API abgefragt werden. Die CID des Originalbildes findet sich in den Metadaten im Attribut "original_id": "DBild/205-4284773" wieder.

Bild-File sowie die zugehörigen Metadaten können analog zu den oben genannten get Aufrufen abgefragt bzw. heruntergeladen werden.

Handling von Infoboxen/Onlineboxen

  • get: Infoboxen und Onlineboxen sind über “type”: “OnlineBox” bzw. “type”: “InfoBox” identifizierbar und können so eindeutig zugeordnet werden. Es können mehrere Onlineboxen in einem CREATE-Artikel enthalten sein und abgeholt werden.

  • post: Es können im Moment mehrere Infoboxen angelegt werden. Standardmäßig ist in den CREATE-Templates jedoch in der Regel nur eine Infobox. Weitere Infoboxen/Onlineboxen werden folglich herausgefiltert, da aktuell alle Elemente, die im Template nicht erlaubt sind, gemäß Artikel-Templates und Freiheitsgrade, entfernt werden.

Komponenten der Schnittstelle

Masken

  • DamAPI.dll

  • CreateUtils.dll

  • ApiUtils.dll

  • NGenWebServices.dll

  • CreateAPI.dll

  • CommonUtils.dll

Tokens zur Autorisierung und Authentifizierung in der CREATE API

siehe dazu:

https://peiq.atlassian.net/wiki/spaces/CORE/pages/1024851977

Maßgebliche DB-Tabellen

DBild, DText, DEmbed

Mitwirkungspflichten

Schnittstelleneinrichtung des Drittanbieters.

 

Verwandte Seiten

 

Nur für PEIQ-Mitarbeiter:

https://peiq.atlassian.net/wiki/spaces/CORE/pages/209060009

Impressum