User Manual Quickstart General Concepts Buyer Side Snippets Engraving Styles and Form Fields Flex Designs Sub Documents Scripting Workflows Editing Workflow Production Workflow Tutorial Videos Frame Features Resources Account Portal Style Reference Change Log Known Bugs & Limitations Glossary Acknowledgements Api Reference Authorization Tokens Embedding The Editor Custom Integration Backend Api Backend API

Backend API

Once a customer’s order is paid for and ready for production, you can order print-ready files with the help of the Printess Backend API.

token dialog

The preferred method would be that the shop backend or shop floor software calls our backend API (using the service token for authentication) and provides a callback URL for the Printess backend.

The call function is /production/produce.

The Printess backend will return a JobID. Generally, all documents marked as production documents are produced. If no document is marked for production then the first document in the list will be rendered.

Once the Printess backend has finished rendering the high res file(s) for this document, it will call the shop backend with the URL(s) to the output file(s) or display an error message in case there was a problem while rendering.

Note: If your endpoint is down for any reason the Printess backend will retry delivering the callback up to 10 times with increasing waiting times. The first 5 retries will be sent after 5 minutes, the 6th after 15 minutes, the 7th after 1 hour, the 8th after 2 hours, the 9th after 4 hours, and the (final) 10th callback retry sent after 24 hours.

Additionally you can retrieve the status of a product order by calling the function /production/status/get. This function provides the JobID of the job you want to get the status for. This is the best practice for all backend systems which are restarted and have jobs without final status in their databases, as in-between callbacks might have been lost or delayed (see note above).

Please avoid loops in fast succession calling the status of a job for each started job, as this API method is throttled and might stall your system in the case of many parallel jobs. Please use the callback method instead.

To make testing and integration of our order processing backend convenient we’ve created an OpenAPI for you which can be used in Postman (and many other tools).

Each backend function will need the service-token for authorization as Bearer in the request header.

It is possible to test the API endpoint directly on our Swagger page - for backend testing please use your service token from the login menu in the editor (see Authorization chapter).

Follow this Link to our Swagger API page

Here is a JavaScript example for a complete roundtrip calling our produce function and then polling for the production status with the returned JobID. This example will take a SaveToken from a buyer edited document and produce all contained production documents as a PDF.

Call this example with producePdf(YOUR_TOKEN, templateNameOrSaveToken).

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function postJson(url, token, model) {
  return await fetch(url, {
    method: "POST",
    mode: "cors",
    cache: "no-cache",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer " + token
    },
    redirect: "follow",
    referrerPolicy: "no-referrer",
    body: JSON.stringify(model)
  });
}

async function sendToProduction(token, templateNameOrSaveToken) {
  const model = {
    "templateName": templateNameOrSaveToken,
    "origin": "YOUR PRODUCTION SYSTEM NAME",
    "outputSettings": {
      "dpi": 300
    }
  };
  const response = await postJson("https://api.printess.com/production/produce", token, model);

  return response;
}

async function getStatus(token, jobId) {
  const model = { "jobId": jobId };
  const response = await postJson("https://api.printess.com/production/status/get", token, model);

  if (!response.ok) {
    throw new Error(`Cannot retrieve status: ${response.statusText} (statusCode=${response.status})`);
  }

  const apiStatus = await response.json();

  return apiStatus;
}

async function producePdf(token, templateNameOrSaveToken) {
  const produceResponse = await sendToProduction(token, templateNameOrSaveToken);

  if (!produceResponse.ok) {
    const errorMessage = await produceResponse.text();
    throw new Error("Cannot produce pdf error=" + errorMessage + ", statusCode=" + produceResponse.status);
  }

  const produceJson = await produceResponse.json();
  const jobId = produceJson.jobId;
  const statusModel = { "jobId": jobId };

  let isFinished = false;
  let status;

  do {
    status = await getStatus(token, jobId);
    isFinished = status.isFinalStatus;

    if (!isFinished) {
      await sleep(1000);
    }
  } while (!isFinished);

  if (status.isSuccess) {
    const pdfs = Object.keys(status.result.r).map(key => ({ document: key, url: status.result.r[key] }));

    for (const document of pdfs) {
      window.open(document.url, "_blank");
    }

    // this handles picture output (png, jpg, tif) if you set output type
    if (status.result.p) {
      for (let i = 0; i < status.result.p.length; i++) {
        const distributionFile = status.result.p[i];
        window.open(distributionFile.u, "_blank");
      }
    }

  } else {
    alert("Cannot render pdf: " + status.errorDetails);
  }
}

It is also possible to test the API endpoint directly on our Swagger page. For backend testing just use your service token from the login menu in the Editor (see Authorization chapter).

Follow this link to our Swagger API page.