API

Under construction …

Einfache API für eine problemlose Entwicklung

Doxey ist von Entwicklern für Entwickler konzipiert worden. Wir haben unser Bestes versucht, eine API zu erstellen, die sehr einfach zu benutzen ist.

Rufen Sie einfach die /merge API Methode auf und übergeben Sie das Template (entweder als sharable link oder als base64 kodierte Binärdatei) und Ihre Daten zusammen mit einigen optionalen Parametern und Sie erhalten im Anschluss das generierte Dokument.

/merge

Der Endpunkt /merge unterstützt sowohl GET- als auch POST-Anforderungen. Alle optionalen Parameter können entweder im Request-Header oder als URL-Parameter übergeben werden.

Parameter

Parameter

Format

Description

template

required

URL

or

base64 encoded document

Übergeben Sie einen Sharable-Link an Ihre Vorlage aus Google Drive, OneDrive oder Dropbox oder einer öffentlichen URL.

model

required

JSON

or

multipart/form-encoded

or

URL-encoded parameters

Die in das Dokument einzufügenden Daten können als JSON- oder mehrteilige/formkodierte Parameter im Anforderungstext bei Verwendung von POST oder URL-kodiert bei Verwendung von GET-Anforderungen übergeben werden (siehe Beispiele unten). Wenn der mitgelieferte JSON ein Array von Objekten ist, können mehrere Dokumente auf einmal erzeugt und eine Zip-Datei mit den Dokumenten erzeugt werden.

apiKey

String

Mit der Übergabe des api-Schlüssels wird das Wasserzeichen aus den generierten Dokumenten entfernt und auch die Generierung von Word- und LibreOffice-Dokumenten wird möglich.

format

pdf
txt

docx

odt
htm

same

Gibt das Format des erzeugten Dokuments an.

Das Standardformat ist pdf.

same liefert nach Möglichkeit das gleiche Format wie das Vorlagendokument zurück.

locale

String

Legt das Gebietsschema fest, das bei der Formatierung von Daten, Zahlen oder Währungen verwendet wird.

Locales müssen mit Java Language Tags angegeben werden (z.B. en-US für US-Englisch, de-DE für Deutsch/Deutschland)

Wenn nicht gesetzt, ist das Gebietsschema en-US.

currency

String

Die Standardwährung, die beim Rendern von Währungen verwendet wird.

Wenn nicht gesetzt, ist die Standardwährung  USD.

timezone

String

Die Zeitzone, die bei der Formatierung von Daten ohne Zeitzone verwendet werden soll.

Wenn keine Zeitzone angegeben wird, ist die Standardzeitzone GMT.

cache

Number

Stellt die Zeit in Sekunden ein, bevor die Vorlage neu geladen wird. Verwenden Sie diesen Parameter, um die Dokumentenerzeugung zu beschleunigen.

debug

true

false

Wenn debug auf true gesetzt ist, fügt Doxey Fehleranmerkungen direkt in das generierte Dokument ein und fügt auch eine Stapelverfolgung zur Fehlerantwort hinzu, wenn der Server Ihre Anfrage nicht erfüllen kann.

content-disposition

download

preview

Beim Aufruf der Zusammenführung im Browser können Sie angeben, ob Sie das generierte Dokument herunterladen oder in der Vorschau ansehen möchten.

filename

String

Gibt den Dateinamen beim Herunterladen des Dokuments im Browser an.

Response

Status code

Format

Beschreibung

200

Blob

Die Methode /merge gibt den Dateiinhalt des erzeugten Dokuments zurück.

400

{

  "error" : "error",

  "details" : "xxx",

  "stack" : ""

}

Wenn das Dokument aufgrund einer unzulässigen Kombination von Parametern nicht aus Ihrer Vorlage erzeugt werden kann.

500

{

  "error" : "error",

  "details" : "xxx",

  "stack" : ""

}

Wenn der Dienst auf einen internen Fehler stößt.

GET

Der einfachste Weg, eine Zusammenführung durchzuführen, ist das Anhängen der kodierten Parameter an die URL. Während dieser Ansatz aufgrund der maximalen Länge einer URL begrenzt ist, kann es praktisch sein, Dokumente "on the fly" aus einem einfachen Link zu generieren, der per E-Mail oder Chat versendet werden kann.

Ihr Datenmodell kann entweder als URL-Parameter im JSON-Format wie folgt übergeben werden...

URL with encoded model in JSON format

... oder Sie können jeden Wert einfach als URL-Parameter übergeben:

URL with parameters

Sie können Arrays durch mehrfaches Anhängen von vorangestellten Parametern (beginnend mit <prefix>.) übergeben. Das Präfix wird zum Namen des Arrays, der Substring nach dem Präfix wird zu einer Eigenschaft jedes Objektes im Array.

URL with array parameter

Die folgenden Code-Schnipsel zeigen, wie man den /merge Endpunkt mittels einer GET-Abfrage aufruft.

# Replace the url with your own sharable link and add an api key
curl https://api.doxey.io/merge?url=https%3A%2F%2Fdocs.google.com%2Fdocument%2Fd%2F1q5ghXsjPS8OqjmRH0lDvlUauZ2F5yO_lk1pPAC72zVc%2Fedit&name=World%21 >merged.pdf

<!-- Replace the url with your own sharable link and add an api key -->
<a href="https://api.doxey.io/merge?url=https%3A%2F%2Fdocs.google.com%2Fdocument%2Fd%2F1q5ghXsjPS8OqjmRH0lDvlUauZ2F5yO_lk1pPAC72zVc%2Fedit&name=World!" target="_blank">Create and Download</a>

var response = UrlFetchApp.fetch('https://api.doxey.io/merge?url=https%3A%2F%2Fdocs.google.com%2Fdocument%2Fd%2F1q5ghXsjPS8OqjmRH0lDvlUauZ2F5yO_lk1pPAC72zVc%2Fedit&name=World!');
var blob = response.getBlob();
var code = response.getResponseCode();
Logger.log(code === 200 ? "Success" : "Error Code: " + code);
// sending out email just for demo purposes
GmailApp.sendEmail("[your email goes here to send this to yourself]", "Your generated document", "See attachment",
  { attachments: [{
      fileName: blob.getName(),
      mimeType: "application/pdf",
      content: blob.getBytes()
    }]
  });

// Replace the url with your own sharable link and add an api key
URL url = new URL("https://api.doxey.io/merge?url=https%3A%2F%2Fdocs.google.com%2Fdocument%2Fd%2F1q5ghXsjPS8OqjmRH0lDvlUauZ2F5yO_lk1pPAC72zVc%2Fedit&name=World!");
InputStream inputStream = url.openStream();
FileOutputStream outputStream = new FileOutputStream(new File("processed.pdf"));
transfer(inputStream, outputStream);

Vollständige Beispiele finde Sie auf GitHub.

POST

Das Datenmodell kann auch im Body der Anforderung im JSON-Format oder bei Verwendung einer POST-Anfrage formularverschlüsselt gesendet werden.

Schauen Sie sich das HTML-Beispiel an, um zu sehen, wie Sie die Vorteile von formularverschlüsselten Daten nutzen können, alle anderen Beispiele verwenden das JSON-Format.

# Execute in your shell and the processed Ultradoc will be saved to a file called processed.pdf
curl  http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU
-X POST
-H "Content-Type: application/json"
-d '{"position": "Sales Representative", "dateOfInterview": "2014-01-31", "refused": "false"}'
> processed.pdf

<form action="http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU" target="_blank">
    <input type="text" name="position" required placeholder="Position">
    <input type="text" name="dateOfInterview" required placeholder="Date of Interview, format YYYY-MM-DD">
    <input type="text" name="refused" required placeholder="Refused: true / false">
    <input type="submit" value="Create and Download">
</form>

function postParameters() {
  var payload = {
    position: "Sales Representative",
    dateOfInterview: "2014-01-31",
    refused: true
  };

   var options = {
     contentType: "application/json",
     method : "post",
     payload : Utilities.jsonStringify(payload)
  };

  var response =
    UrlFetchApp.fetch('http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU',
                      options)
  var blob = response.getBlob();
  var code = response.getResponseCode();
  Logger.log(code === 200 ? "Success" : "Error Code: " + code);

  // sending out email just for demo purposes
  // in real applications send out personalized emails using Ultradox instead
  GmailApp.sendEmail("[your email goes here to send this to yourself]", "Your generated document",
    "See attachment",
     { attachments: [
                        { fileName: blob.getName(),
                          mimeType: "application/pdf",
                          content: blob.getBytes()
                        }
                    ]
     }
  );
}

// this example requires GSON: http://code.google.com/p/google-gson/
URL url = new URL("http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU");
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("POST");
connection.setRequestProperty("Content-Type", "application/json");
connection.setDoInput(true);
connection.setDoOutput(true);

Gson gson = new Gson();
// have a look at GitHub gist below to see full code for Payload class
Payload payload = new Payload("Sales Representative", "2014-01-31", true);
String json = gson.toJson(payload);
byte[] bytes = json.getBytes();
connection.setRequestProperty("Content-Length", Integer.toString(bytes.length));
OutputStream os = connection.getOutputStream();
os.write(bytes);
os.close();
InputStream inputStream = connection.getInputStream();
FileOutputStream outputStream = new FileOutputStream(new File("processed.pdf"));
transfer(inputStream, outputStream);

// this example requires GSON: http://code.google.com/p/google-gson/
URL url = new URL("http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU");
URLFetchService urlFetchService = URLFetchServiceFactory.getURLFetchService();
HTTPRequest request = new HTTPRequest(url, HTTPMethod.POST, withDefaults().setDeadline(30.0));
request.setHeader(new HTTPHeader("Content-Type", "application/json"));

Gson gson = new Gson();
// have a look at GitHub gist below to see full code for Payload class
Payload payload = new Payload("Sales Representative", "2014-01-31", true);
String json = gson.toJson(payload);
request.setPayload(json.getBytes());
request.setHeader(new HTTPHeader("Content-Type", "application/json"));

HTTPResponse response = urlFetchService.fetch(request);
byte[] content = response.getContent();

The pure HTML solution deserves special attention. Ultradox has a feature that allows you to pass complex objects and even lists of objects using GET requests. This is especially nice when using links in HTML .

To pass properties of objects you simply use the dot notation for the name of a parameter like in object.property.

If you want a list of objects you pass along as many parameters of the same name as you want. If you pass both object.property=Prop1 and object.property=Prop2 as parameters to a GET request, Ultradox will receive a list of objects one having Prop1 as a property, the other Prop2. Have a look at the HTML tab for a complete example.

Die reine HTML-Lösung verdient besondere Aufmerksamkeit. Ultradox verfügt über eine Funktion, die es erlaubt, komplexe Objekte und sogar Listen von Objekten mittels GET-Anfragen zu übergeben. Dies ist besonders nützlich bei der Verwendung von Links in HTML .

Um Eigenschaften von Objekten zu übergeben, verwendet man einfach die Punktnotation für den Namen eines Parameters wie in object.property.

Wenn Sie eine Liste von Objekten erstellen wollen, übergeben Sie so viele Parameter gleichen Namens, wie nötig. Wenn Sie sowohl object.property=Prop1 als auch object.property=Prop2 als Parameter an einen GET-Anfragen übergeben, erhält Ultradox eine Liste von Objekten, von denen eines Prop1 als Eigenschaft hat, das andere Prop2. Ein vollständiges Beispiel finden Sie auf der Registerkarte HTML .

# Execute in your shell and the processed Ultradoc will be saved to a file called processed.pdf
curl http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?locale=DE
-X POST
-H "Content-Type: application/json"
-d '{
    "name": "Olli",
    "events": [
        {
            "title": "Strategy Meeting",
            "startTime": "2014-02-01T10:00:00+01",
            "endTime": "2014-02-01T11:30:00+01",
            "description": "Discussion of the floreysoft strategy",
            "location": "Telemannstraße 22, 20255 Hamburg"
        }, {
            "title": "Dinner",
            "startTime": "2014-02-01T20:00:00+01",
            "endTime": "2014-02-01T22:30:00+01",
            "description": "Dinner with Le Chef",
            "location": "Gaußstraße 3, 22765 Hamburg"
        }
    ]
}'
>processed.pdf

<!-- Manual URL enconding at http://www.albionresearch.com/misc/urlencode.php -->
<a href="http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?name=Olli&
events.title=Strategy%20Meeting&
events.startTime=2014-02-01T10%3A00%3A00%2B01&
events.endTime=2014-02-01T11%3A30%3A00%2B01&
events.description=Discussion%20of%20the%20floreysoft%20strategy&
events.location=Telemannstra%C3%9Fe%2022%2C%2020255%20Hamburg&
events.title=Dinner&
events.startTime=2014-02-01T20%3A00%3A00%2B01&
events.endTime=2014-02-01T22%3A30%3A00%2B01&
events.description=Dinner%20with%20Le%20Chef&
events.location=Gau%C3%9Fstra%C3%9Fe%203%2C%2022765%20Hamburg
" target="_blank">Create and Download</a>

function postComplex() {
  // to show that stringifying real dates does work as well
  var date = new Date();
  var events = {
    name: "Olli",
    events: [
      {
        title: "Strategy Meeting",
        startTime: "Fri Feb 01 10:00:00 CET 2014",
        endTime: "Fri Feb 01 11:30:00 CET 2014",
        description: "Discussion of the floreysoft strategy",
        location: "Telemannstraße 22, 20255 Hamburg"
      }, {
        title: "Dinner",
        startTime: "Fri Feb 01 20:00:00 CET 2014",
        endTime: date,
        description: "Dinner with Le Chef",
        location: "Gaußstraße 3, 22765 Hamburg"
      }
    ]
  };

   var options = {
     contentType: "application/json",
     method : "post",
     payload : Utilities.jsonStringify(events)
  };

  var response =
    UrlFetchApp.fetch('http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?locale=DE',
                      options)
  var blob = response.getBlob();
  var code = response.getResponseCode();
  Logger.log(code === 200 ? "Success" : "Error Code: " + code);

  // sending out email just for demo purposes
  // in real applications send out personalized emails using Ultradox instead
  GmailApp.sendEmail("[your email goes here to send this to yourself]", "Your generated document",
    "See attachment",
     { attachments: [
                        { fileName: blob.getName(),
                          mimeType: "application/pdf",
                          content: blob.getBytes()
                        }
                    ]
     }
  );
}

// this example requires GSON: http://code.google.com/p/google-gson/
URL url = new URL(
  "http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?locale=DE");
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("POST");
connection.setRequestProperty("Content-Type", "application/json");
connection.setDoInput(true);
connection.setDoOutput(true);

Events events = new Events("Olli");
events.addEvent(new Event("Strategy Meeting", new Date(113, 01, 01,
        10, 00), new Date(113, 01, 01, 11, 30),
        "Discussion of the floreysoft strategy",
        "Telemannstraße 22, 20255 Hamburg"));
events.addEvent(new Event("Dinner", new Date(113, 01, 01,
        20, 00), new Date(113, 01, 01, 22, 30),
        "Dinner with Le Chef",
        "Gaußstraße 3, 22765 Hamburg"));

// use ISO8601 date format for best compatibility
Gson gson = new GsonBuilder().setDateFormat("yyyy-MM-dd'T'HH:mm:ssX").create();
String json = gson.toJson(events);
byte[] bytes = json.getBytes("UTF-8"); // encoding is important when you are outside of ASCII
connection.setRequestProperty("Content-Length", Integer.toString(bytes.length));
OutputStream os = connection.getOutputStream();
os.write(bytes);
os.close();

InputStream inputStream = connection.getInputStream();
FileOutputStream outputStream = new FileOutputStream(new File("processed.pdf"));
transfer(inputStream, outputStream);

// this example requires GSON: http://code.google.com/p/google-gson/
URL url = new URL(
  "http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?locale=DE");
URLFetchService urlFetchService = URLFetchServiceFactory.getURLFetchService();
HTTPRequest request = new HTTPRequest(url, HTTPMethod.POST, withDefaults().setDeadline(30.0));
request.setHeader(new HTTPHeader("Content-Type", "application/json"));

Events events = new Events("Olli");
events.addEvent(new Event("Strategy Meeting", new Date(113, 01, 01,
        10, 00), new Date(113, 01, 01, 11, 30),
        "Discussion of the floreysoft strategy",
        "Telemannstraße 22, 20255 Hamburg"));
events.addEvent(new Event("Dinner", new Date(113, 01, 01,
        20, 00), new Date(113, 01, 01, 22, 30),
        "Dinner with Le Chef",
        "Gaußstraße 3, 22765 Hamburg"));

// use ISO8601 date format for best compatibility
Gson gson = new GsonBuilder().setDateFormat("yyyy-MM-dd'T'HH:mm:ssX").create();
String json = gson.toJson(events);
request.setPayload(json.getBytes("UTF-8"));
request.setHeader(new HTTPHeader("Content-Type", "application/json"));

HTTPResponse response = urlFetchService.fetch(request);
byte[] content = response.getContent();

Data types

Bei der Weitergabe von Daten muss man wissen, wie man sie formatiert, damit Doxey sie sinnvoll nutzen kann.

Boolean

Booleans können entweder mit oder ohne Anführungszeichen übergeben werden.

Wenn der übergebene Wert der leere String oder false ist, wird er als false betrachtet. In allen anderen Fällen gilt er als true.

Number

Zahlen werden immer als Festkommawerte angegeben. Ob der Dezimalpunkt tatsächlich . oder eher , ist, hängt vom angegebenen Gebietsschema ab.

String

Werder als UTF-8 kodiert angegeben.

Date

Termine sind die kompliziertesten Werte, die man bewältigen muss.

Das in JSON zu verwendende Format ist in ISO 8601 festgelegt.

Wenn Sie dieses Format verwenden, sind Sie auf der sicheren Seite.

Zum Beispiel könnte ein nach ISO 8601 formatiertes Datum so aussehen: 2008-02-01T09:00:22+05:00.

Leider können Sie in manchen Situationen die Formatierung der Daten nicht frei wählen.

Diese Situationen beinhalten die Verwendung von Google Apps Script oder JSON-Bibliotheken, die die Formatierung von Daten für Sie übernehmen.

Um Ihnen dabei zu helfen, versucht Doxey, alle Standard-Eingabeformate zu akzeptieren und zu parsen.

Lassen Sie uns wissen, ob es ein Format gibt, das nicht geparst werden kann, aber auf jeden Fall als Standard angesehen werden kann.

/license

Rufen Sie Informationen über Ihre Lizenz, die Anzahl der erzeugten Dokumente im aktuellen Monat und die Anzahl der verbleibenden Merges ab.

Parameters

Parameter

Format

Beschreibung

apiKey

String

Geben sie Ihren API-Schlüssel an.

/print

Führen Sie eine Zusammenführung durch und drucken Sie das erzeugte Dokument auf dem angegebenen Drucker in der angegebenen Ablage aus.

Parameters

Parameter

Format

Beschreibung

template

required

URL

or

base64 encoded document

Übergeben Sie einen Sharable-Link an Ihre Vorlagendatei aus Google Drive, OneDrive oder Dropbox oder einer öffentlichen URL.

model

required

JSON

or

multipart/form-encoded

or

URL-encoded parameters

Die in das Dokument einzufügenden Daten können als JSON- oder mehrteilige/formkodierte Parameter im Anforderungstext bei Verwendung von POST oder URL-kodiert bei Verwendung von GET-Anforderungen übergeben werden (siehe Beispiele unten).

printer

String

Name des Druckers.

Der Namen des Druckers muss mit der Angabe übereinstimmen, wie er unter /printers aufgelistet ist.

tray

String

Name des zu verwendenden Papierfachs.

Muss genau mit dem Namen des Fachs, wie unter /printers aufgeführt, übereinstimmen.

apiKey

String

Geben sie Ihren API-Schlüssel an.

locale

String

Legt das Gebietsschema fest, das bei der Formatierung von Daten, Zahlen oder Währungen verwendet wird.

Gebietsschema müssen mit Java Language Tags angegeben werden (z.B. en-US für US-Englisch, de-DE für Deutsch/Deutschland).

Wenn nicht gesetzt, ist die Gebietsschema en-US.

currency

String

Die Standardwährung, die beim Rendern von Währungen verwendet wird.

Wenn nicht gesetzt, ist die Standardwährung USD.

timezone

String

Die Zeitzone, die bei der Formatierung von Daten ohne Zeitzone verwendet werden soll.

Wenn keine Zeitzone angegeben wird, ist als Standard GMT angegeben.

cache

Number

Stellt die Zeit in Sekunden ein, bevor die Vorlage neu geladen wird. Verwenden Sie diesen Parameter, um die Dokumentenerzeugung zu beschleunigen.

/printers

Der Endpunkt /printers gibt die verfügbaren Drucker und Papierschächte zurück.

Parameter

Format

Beschreibung

apiKey

String

Geben sie Ihren API-Schlüssel an.

Questions and Feedback

If you have any comments on this page, feel free to add suggestions right to the Google document that we are using to create this site.

If you are not yet member of the Doxey community, please join now to get updates from our end or to provide feedback, bug reports and discuss with other users.

Last Updated: 06.01.20