Print Jobs

New Print Job

This authenticated request will submit a new print job. This is the only required request; all others are optional. This request specifies the product, options and the location of the PDF files. The XML is sent via the HTTP POST method with the request parameter 'printjob'.

The XML is validated after the print job request is successfully received. Errors are reported by an XML with a short description of the error. When all actions are successful, a status XML is returned.

Upon success, the specified PDFs are downloaded by our server. The PDFs are processed and the print job is executed if no error occurs in the process. On status changes, the callback URL is called to provide information. The same information can be polled with the 'print job status' interface.

With the attribute 'dry_run' set to 'true', a test print job can be sent. In this case the print job will be accepted and the PDF will be downloaded, but no book will be printed.

Request

• Method: POST
• URL: https://www.epubli.de/api/partner/printjob/create
• Parts:
  • partner: partner name
• POST parameters:
  • printjob: 'epubli_print_job' XML
  • authentication parameters
• Reply: 'epubli_print_job_status' in XML (see example) or 'epubli_api_error'

Example

• URL: https://www.epubli.de/api/demo/printjob/create
• POST parameter printjob:

<?xml version="1.0"?>
<epubli_printjob xmlns="http://www.epubli.de/spec" version="1.0">

  <partner>partner</partner>
  <unique_id>1234</unique_id>
  <external_ref>4321</external_ref>

  <!-- set to true for simulation mode -->
  <dry_run><true /></dry_run>

  <item>

    <author>Autor</author>
    <title>Title</title>
    <product>3</product>
    <copies>17</copies>

    <options>
      <cover_surface>2</cover_surface>
      <content_color>1</content_color>
      <simplex_mode><true /></simplex_mode>
    </options>

    <sources>
      <u1>
        <!-- cover side -->
        <pdf>http://www.example.com/pod.pdf</pdf>
        <page>1</page>
      </u1>
      <spine>
        <pdf>http://www.example.com/pod.pdf</pdf>
        <page>2</page>
      </spine>
      <u4>
        <!-- cover backside -->
        <pdf>http://www.example.com/pod.pdf</pdf>
        <page>3</page>
      </u4>
      <content>
        <pdf>http://www.example.com/pod.pdf</pdf>
        <page_start>1</page_start>
        <page_end>89</page_end>
      </content>
    </sources>

    <delivery_address>
      <salutation>Anrede</salutation>
      <name_line1>Name Zeile 1</name_line1>
      <name_line2>Name Zeile 2</name_line2>
      <name_line3>Name Zeile 3</name_line3>
      <street_name>Strasse</street_name>
      <street_nr>23</street_nr>
      <zip>12345</zip>
      <city>Berlin</city>
      <country>DE</country>
      <email>john.doe@example.com</email>    <!-- optional -->
      <phone>+49 42 42 42 42 42</phone>    <!-- optional -->
    </delivery_address>

    <status_callback>http://example.com/s.php?id=1</status_callback>

  </item>
</epubli_printjob>

This will order 17 copies of product ID 3 (DinA4, 90 grams white matt paper, softcover) – with the following options: simplex (one sided print); 'cover_surface' 2 (cover is glossy); 'content_color' 1 (black and white content).

The 'unique_id' is an arbitrary string, set by the partner. The only requirement is that it must be different for every order. This is to detect unwanted duplicate orders.

The 'external_ref' is an external reference number (e.g. your order ID). It is returned on status updates.

The 'author' and the 'title' are used for job identification (e.g. invoices) and do not appear in print. The 'delivery_address' element is the address the order is shipped to.

The 'sources' are the PDF files: 'U1' is the front cover; 'U4' the back cover; 'spine' the spine. For the cover, there are two options: Provide U1 and U4 plus spine for the formats that need it (hardcover, softcover), or supply a single PDF with the tag 'cover'.

For content, there can be one or several files, each giving a page range. This way, the content can be combined from several files, or from different parts of a single one.

If given, all status changes are posted via HTTP POST (parameter 'status') to the 'status_callback' interface.

Delivery address

The following elements of the delivery address are required: 'name_line1', 'street_name', 'street_nr', 'zip', 'city', 'country'.

The 'country' element is the two letter country code as defined in ISO 3166 ALPHA-2. The following countries are supported:

• Austria
• Canada
• Belgium
• Britain
• Denmark
• Finland
• France
• Germany
• Greece
• Ireland
• Italy
• Luxembourg
• Netherlands
• Norway
• Portugal
• Sweden
• Switzerland
• Slovenia
• Spain
• USA

If one of the required elements is missing or the country-code is invalid no print job is created and the response to the request is "address incomplete".

Print job status

If a callback interface is given, all status changes are pushed to this interface. It is also always possible to ask the interface (with an authenticated request) for the current status. Each status has a 'type' which is either 'success' or 'error'. On type 'error' the print job failed -- no further status updates will be sent.

Request

• Method: GET
• URL: https://www.epubli.de/api/partner/printjob/status/printjobId
• Parts:
  • partner: partner name
  • printjobId: ID of the print job
• POST parameters: authentication parameters
• Reply: 'epubli_print_job_status' in XML (see example) or 'epubli_api_error'

Example

• URL: https://www.epubli.de/api/demo/printjob/status/103
• Reply:

<?xml version="1.0" encoding="UTF-8"?>
<epubli_print_job_status xmlns="http://www.epubli.de/spec" version="1.0">
  <date>2010-02-09T14:10:06+01:00</date>
  <partner>
    <partner_name>partner</partner_name>
  </partner>
  <printjob_id>103</printjob_id>
  <external_ref>4321</external_ref>
  <status>
    <code>300</code>
    <type>success</type>
    <message>PDF files successfully downloaded</message>
    <url>http://www.epubli.de/api/comics/printjob/status/103</url>
  </status>
</epubli_print_job_status>

« Back to the API menu