Paginations API - Gebrauchsanweisung

Eine kurze Einführung in die Pagination API anhand einer Demo-Vorlage

Pagination API

Die API von Pagination ermöglicht es Ihnen ganz einfach Dokumente zu erstellen. Aus einer strukturierten Datendatei und einem bestimmten Layout liefert die API von Pagination einen Link zum Herunterladen des Dokuments im PDF- und InDesign Format.

Endpunkt-Spezifikationen werden mit dem OpenAPI 3.0 Format dokumentiert.

Inhaltsverzeichnis


Erste Schritte

Die API von Pagination ermöglicht den Nutzern, den Service von Pagination eigenständig zu nutzen, bearbeiten und kontrollieren.

Die wichtigsten Bestandteile des Service von Pagination sind:

  • Projekt
    Projekte enthält alle Wünsche des Kundens im Sinne von:
    ⋅   Grundlayout (aus unseren Vorlagen oder von uns für Sie maßgeschneidert erstellt)
    ⋅   Personalisierung (Alle Funktionen die zusätzlich zum Basislayout hinzugefügt werden)
    ⋅   Einstellungen (z. B. Benachrichtigungseinstellungen)
    Das Projekt ist durch eine einzigartige tt>projekt_id gekennzeichnet.
    Das Grundlayout wird durch eine einzigartige projekt_klasse gekennzeichnet.
  • Nutzer
    Der Administrator des Projekts ist autorisiert, den API-Vorgang auszuführen.
    Dieser wird durch eine einzigartige user_id gekennzeichnet.
  • Der Paginierungs-Vorgang
    Anfragen werden durch eine einzigartige reqId gekennzeichnet. Wenn Sie den Endpunkt aufrufen, müssen Sie folgendes bereitstellen:
    ⋅   eine gut strukturierte Datendatei
    ⋅   Auftragsspezifische Einstellungen z. B. Farbe, Exporttyp, Benachrichtigungen
    Der Service von Pagination verarbeitet Anfragen asynchron auf der Grundlage von den gespeicherten Regeln und Einstellungen in dem Projekt.
    Am Ende wird alles in einer einzigen ZIP Datei exportiert, welche alle Ausgabedateien in dem gewünschten Format enthält.
    Neben dem Vorgang, wird der Status aller Anfragen in dem Projektverlauf gespeichert, der immer vom Nutzer eingesehen werden kann.
    Nach Abschluss des Vorgangs erhalten die Nutzer eine Benachrichtiung via Email, Webhook etc. außerdem erhalten Sie einen Link, um die exportierten Dokumente herunterzuladen.

Die API von Pagination bietet verschiedene Endpunkte, um alle Funktionen des Service von Pagination kontrollieren zu können.


Workflow

Um den Worklow unseres Service besser zu verstehen, sowie die Steuerung über die API’s, erklären wir Ihnen die Abläufe anhand eines Tutorials mit einer unserer Demo-Vorlagen!

Schritt 0 – Anmeldedaten

Jeder Aufruf einer API muss Authentifiziert werden.
Normalerweise benötigt jeder Endpunkt einen API-Schlüssel und eine User_id als Kopfparameter.
Bitte schauen Sie sich die weiteren Spezifikationen der Authentifizierungs Details hier an.

Fragen Sie uns nach einigen kostenlosen Demo-Zugangsdaten, die bereits für den Start eines Projekts eingerichtet sind, oder laden Sie direkt einen API-Schlüssel herunter, um ein neues Demo-Projekt von Grund auf neu einzurichten.

Schritt 1 – Projekt erstellen

Bevor Sie mit dem Paginierungsvorgang beginnen können, müssen Sie zuerst ein neues Projekt erstellen, indem Sie den "Projekt erstellen" Endpunkt aufrufen.
Wenn Sie das erste Mal ein Projekt erstellen, erscheint ein neuer Nutzer in Ihrer Datenbank.
Für den Endpunkt müssen Sie Folgendes angeben:

  • Projekt_klasse
    Die Projekt Klasse ist die einzigartige ID für das Dokumentenlayout, Sie können eins unserer vielen verschiedenen Templates aus der Bibliothek auswählen.
    Für unsere Demo können Sie die Projektklasse mit dem Namen Demo auswählen.
    Um besser zu verstehen, wie das Dokumentenlayout auf der Seite organisiert ist, können Sie sich dieses in dem Layout Bereich ansehen.
  • Email
    Geben Sie Ihre Email Adresse an, also die Email Adresse des Projekt-Eigentümers.
    Diese Email Adresse wird verwendet, wenn Sie sich bei uns über unsere Datenbank registrieren.
    Alle Projekte die mit der gleichen Email erstellt werden, werden dem gleichen Benutzer zugeordnet.
  • Webhook Einstellungen (Optional)
    Wenn Sie bevorzugen POST Nachrichten über den aktuellen Prozessstatus an Ihre URL zu erhalten, füllen Sie einfach dieses Feld aus.
  • Optionale Einstellungen
    Jede Klasse hat seine eigenen Einstellungen, die Sie während dem Erstellen des Projekt festlegen können.
    Die Demo-Vorlage benötigt keine weiteren Einstellungen.
    Viele weitere Projekt Klassen hinzuzufügen steht ganz oben auf unseren Prioritäten!

Der Endpunkt gibt einige Schlüsseleigenschaften zurück, die zur Autorisierung und zum Aufruf jedes anderen Endpunkts verwendet werden:

  • Projekt_id
    Die einzigartige ID des neu erstellten Projekts.
  • Nutzer_id
    Die einzigartige ID des Projekt Inhabers. Verwenden Sie dies als erforderlichen Header-Parameter in untergeordneten Api-Aufrufen.

Schritt 2 – Launch-Prozess

Nachdem erstellen des Projekts, können Sie es mit Hilfe des "Launch-Prozess" Endpunkt freigeben.

Für den Endpunkt müssen Sie folgedene Dinge bereitstellen:

  • Project_id (zurückgegeben von dem Projekt erstellen Endpunkt)
  • Nutzer_id (zurückgegeben von dem Projekt erstellen Endpunkt)
  • Datendatei
  • Optionale Einstellungen, die spezifisisch auf die Anforderungen des aktuellen Paginierungsprozesses (z.B die Farbe der Beschriftungen und der Titel) und abängig von der Projektklasse sind.
    Für die Demo Klasse müssen Sie keine Angaben für die Optionalen Einstellungen angeben.

Damit Sie den Paginierungsprozess erfolgreich starten können, müssen Sie die passende Datendateien vorliegen haben.Datendateien (-CSV, -XLSX Format)vorliegen haben, diese müssen so angeordnet sein wie es von der ausgewählten Projekt_klasse erfordert wird.
Um besser zu verstehen, wie sie eine Demo-Klasse am besten strukturieren, können Sie im Bereich „Datendatei“ nachsehen.

Die Datei wird als Teil des Anfagen Körper hochgeladen. Achten Sie bitte darauf das die Art des Körpers einer Multipart/Formular-Datei entspricht.

Hinweis zur Multipart-/Formular-Datei

Abhängig von dem Framework das Sie nutzen um den API Abruf zu vollziehen (z. B. nodeJ, Postman usw.) müssen Sie eine bestimmte Syntax übernehmen um so zu kennzeichnen das eins der Felder im Körper sich auf eine bestimmte Datei bezieht die hochgeladen werden muss. Mit Curl zum Beispiel:

curl -X POST -F fieldNameHere=@myfile.html http://myapi.com/

Der Endpunkt sendet die einzigartige Anfragen-ID des Prozesses zurück (reqId), dieser ermöglicht es Ihnen den Prozessstatus und die Ergebnisse abzurufen.

Benachrichtigungen

Wenn der Prozess beginnt, erhält der Nutzer, dessen Email Adresse angegeben wurde, eine Benachrichtigung über den Beginn des Paginierungsprozesses und einen Webhook URL, wenn Sie diesen während der Erstellung angegeben haben.
Da der Prozess asynchron abläuft, erhalten Sie eine Email und Webhook Benachrichtigung, wenn Sie diese angegeben haben, sobald der Vorgang abgeschlossen ist.
In der Benachrichtigung über den abgeschlossenen Paginierungsvorgang erhalten Sie eine URL zum Exportieren der fertigen Dokumente. Bitte denken Sie daran, dass der Link nach 7 Tagen verfällt. Eine Erneuerung des Links ist durch den "Status erfahren" Endpunkt möglich.

Schritt 3 – Anfragestatus abrufen

Nachdem Sie ein Projektvorgang gestartet haben, sind Sie so gut wie fertig und müssen nur noch auf die Benachrichtigung waren, dass Ihr Paginierungsvorgang abgeschlossen ist.
Sie können die Statusanfrage abrufen, indem Sie den Prozessstatus erfahren Endpunkt abrufen. Außerdem ist es möglich, alle Prozessstatus einzusehen oder nur eine Spezifische, indem Sie die reqId angeben.
In den Benachrichtigungen finden Sie den Download Link: Denken Sie bitte daran, dass der Download Link nach 7 Tagen verfällt. Sie können diesen automatisch erneuern, indem Sie den Prozessstatus abfragen Endpunkt mit der reqId abrufen.


Layout vs Datendatei

Layout

Jede Projekt_Klasse hat sein eigenen Layout und Einstellungen.
Die Struktur der Datendatei wird im Layout wiedergegeben, wenn das Layout also z. B. Tabellen mit zwei Bildern für jedes Bild enthält, dann müssen Sie 2 extra Felder in Ihrer Datendatei ausfüllen.

Die Demo-Vorlage besteht aus zwei Hauptteilen:

  • Die Seite mit dem Inhaltsverzeichnis, welches eine Zusammenfassung der Produkte im Dokument ist
  • Der Hauptteil des Dokuments mit den einzelnen Produkten, die in den Tabellen angeordnet sind.

Beispiel PDF-Dokument hier ansehen.
Abonnements profitieren von weiteren Vorlagen oder können Ihr eigenes Layout hochladen.
Für mehr Informationen kontaktieren Sie uns bitte.


Datendatei

Format der Dateien: -CSV oder -XLSX
Datendatei Beispiel hier runterladen.
Hierarchie Felder und beschreibende Felder müssen ausgefüllt werden, Merkmal Felder können frei bleiben. Zellen können frei bleiben, die Überschrift einer Spalte muss aber ausgefüllt werden.

Hierarchie Felder

Mit diesen Feldern werden Produkte gruppiert: Produkte, die die gleichen Kategorien haben, werden zusammen gruppiert.
Der Inhalt dieser Felder wird im Inhaltsverzeichnis gedruckt.

Kategorie 1

Hauptkategorie, die die Produkte einordnet.
Platzierung: Seitenränder
Category1 in the document

Kategorie 2

Die zweite Ebene der Klassifizierung der Produkte, die Unterkategorie.
Platzierung: Seitenränder
Category1 in the document
Category1 in the document

Beschreibende Felder

Diese Felder beziehen sich auf die Produkte.

Produkt Name

Produkttitel.
Dieses Feld wird verwendet, um Varianten oder verschiedene Produktcodes zusammenzufassen.
Pltzierung: Oben im Layout
ProductName in the document
ProductName in the document

Beschreibung

Produkt Beschreibung.
Einfache HTML-Codierung kann verwendet werden, um den Text zu personalisieren.
Erlaubte Tags:
<b>bold</b>
<ul> <li> bullet list </li> </ul>
<i>italic</i>
sup for superscript
sub for subscript
Platzierung: Unter dem Produktnamen
Description in the document

Bild 1

Öffentliche URL des Hauptproduktbildes.
Das Bild bezieht sich auf den Produktnamen, nicht auf den Produktcode. Wenn jeder Artikel/SKU ein anderes Bild hat, wird das erste der Gruppe (Produktname) gedruckt
Muss die Erweiterung enthalten. z. B. „pagination.jpg“
Akzeptiertes Format: .jpg .eps .pdf .png .tiff .ai .psd

Platzierung: Rechte Seite des Layouts
Image1 in the document

Bild 2

Öffentliche URL von Produktbildern könnte technische Zeichnung, Detail, verschiedene Ansichten sein.
Das Bild bezieht sich auf den Produktnamen, nicht auf den Produktcode. Wenn jeder Artikel/SKU ein anderes Bild hat, wird das erste der Gruppe (Produktname) gedruckt
Muss die Erweiterung enthalten. z. B. „pagination.jpg“
Akzeptiertes Format: .jpg .eps .pdf .png .tiff .ai .psd

Platzierung: Unter der Beschreibung
Image2 in the document

Bild 3

Die öffentliche URL des Produktbildes könnte eine technische Zeichnung, ein Detail, eine andere Ansicht sein.
Das Bild bezieht sich auf den Produktnamen, nicht auf den Produktcode. Wenn jeder Artikel/SKU ein anderes Bild hat, wird das erste der Gruppe (Produktname) gedruckt
Muss die Erweiterung enthalten. z. B. „pagination.jpg“
Akzeptiertes Format: .jpg .eps .pdf .png .tiff .ai .psd

Platzierung: Unter der Beschreibung
Image3 in the document

Public URL of the manufacturer/brand logo of the product.
Muss die Erweiterung enthalten. z. B. „pagination.jpg“
Akzeptiertes Format: .jpg .eps .pdf .png .tiff .ai .psd

Platzierung: Über Bild 1
BrandLogo in the document

Eigenschaften

Diese Felder können spezifisch für die Produkte und Varianten sein.
Es können so viele Spalten in der Datendatei sein, wie benötigt werden.
In das Demo-Layout passen maximal 11 Eigenschaftsspalten, die pro Produktname gefüllt sind.
Die Reihenfolge, in der die Spalten in der Datendatei erscheinen (von links nach rechts), ist die im Layout verwendete Reihenfolge.
Kopfzeilen haben keine obligatorischen Namen.

Produktcode/SKU ist als Attribut zu betrachten.
Weitere Beispiele für Attribute können sein: Abmessungen, Farben, Kurzbeschreibung, Preise/Währungen.
Stellen Sie sicher, dass die Zellen als Text formatiert sind und der Inhalt dem entspricht, was im Layout zu sehen ist. Stellen Sie besonders in den Preisspalten sicher, dass: Präfix für Währungen, Anzahl der Dezimalstellen
Ziffern, Tausendertrennzeichen, Dezimaltrennzeichen korrekt eingegeben werden
.
Platzierung: Tabelle
Attributes in the document
Attributes in the data file


Bilder

Alle Bilder werden automatisch von der öffentlichen URL geladen, die in der Datendatei enthalten ist.

Erstellen Sie Ihr automatisches Dokument

Nutzen Sie unsere kostenlose InDesign-Vorlagen oder laden Sie Ihr eigenes Layout hoch.
Erstellen Sie unbegrenzt viele Dokumente!