File transfer

Files can be supplied in two different ways. Back in the step Order we briefly showed how to supply files as URLs when creating an order:

'files' => array(                     
    'cover' => 'https://www.printapi.nl/sample-book-a5-cover.pdf',
    'content' => 'https://www.printapi.nl/sample-book-a5-content.pdf'
)

Print API will then automatically download the files asynchronously. This usually happens within 5 minutes. Should a download fail for any reason, you'll receive an automatic error report per e-mail. If this is a suitable solution for your application, you can skip ahead to the next step.

Are your files not publicly available from a webserver? Then read on: you can also upload your files to the API after you've placed an order.

Alternative Uploading

Alternatively, you can upload your files after creating an order. Print API will generate a unique uploadUrl for each file you need to supply. You can then simply POST each file directly to its upload URL. These URLs will be in the API response of your order.

To enable uploads, you must first omit the files-array from your order data, or set it to null in its entirety: this will tell the API to wait for uploads. Our PHP library has a special function for uploading files:

// $order = $api->post('/orders', ...);
                 
$contentUploadUrl = $order->items[0]->files->content->uploadUrl;
$api->upload($contentUploadUrl, 'files/123/content.pdf', 'application/pdf');

$coverUploadUrl = $order->items[0]->files->cover->uploadUrl;
$api->upload($coverUploadUrl, 'files/123/cover.pdf', 'application/pdf');

The file paths files/123.content.pdf and files/123/cover.pdf are obviously fictional. You can customize this snippet to upload your own file(s). Note: the cover file is only required for books, so if you're ordering something else, you only need to supply a content file.

Be sure to specify the correct MIME-type for the file type you're using, so the API knows how to process your file. The table below shows the value associated with each file type.

File type		MIME-type
PDF	*.pdf	application/pdf
PNG	*.png	image/png
JPEG	*.jpg, *.jpeg	image/jpeg

Ordering multiple items with unique files?

Our example snippet above assumes you always order one item, with the same file(s). Often, this won't be the case, and you'll order multiple items with unique files. To map the right files to the right items, it might help to store some metadata when creating your order:

Supplying metadata:

$item1 = array(
    'productId' => 'poster_a4_sta',
    'quantity' => 100,
    'metadata' => json_encode(array(
        'file' => $file
    ))
);

You can use the metadata-field to store your own data, like a file path or file ID. It's just a text field, so JSON, XML or plain text are all fine. When uploading, you could use this field to map each item back to its file:

Reading metadata:

foreach ($order->items as $item) {
   $metadata = json_decode($item->metadata);
   $uploadUrl = $item->files->content->uploadUrl;
   $api->upload($uploadUrl, $metadata->file, 'application/pdf');
}