API Documentation

API Base URL https://api.picanova.com/api

Authorization

Information

Type: Basic
User: Store's API user
Password: Store's API key
Header format: Authorization: Basic Encoded + base64 encoded user:password

Documentation

Shipment

When order will be fulfilled and shipped a notification to your email will be sent.
Additional you can specify store webhook URL in your store settings. The post to your webhook will made with following information

{
  "type": "shipment_sent",
  "created": {
    "date": "2018-05-30 08:40:20.050308",
    "timezone_type": 3,
    "timezone": "UTC"
  },
  "data": {
    "shipment": {
      "shipping_method": {
        "code": "UPS MIEXP",
        "name": "UPS MIEXP"
      },
      "tracking_number": "",
      "tracking_url": "",
      "shipped_at": {
        "date": "2018-05-29 15:42:37.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "items": [
        {
          "item_id": 5443,
          "quantity": 1
        }
      ]
    },
    "order": {
      "id": "PPO26149838T",
      "external_id": null,
      "is_test": true,
      "shipping_method": {
        "code": "UPS MIEXP",
        "name": "UPS MIEXP"
      },
      "status": "FULFILLED",
      "status_label": "Fulfilled (TEST)",
      "created_at": {
        "date": "2018-05-29 14:14:52.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "updated_at": {
        "date": "2018-05-29 15:42:37.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "shipments": [
        {
          "shipping_method": {
            "code": "UPS MIEXP",
            "name": "UPS MIEXP"
          },
          "tracking_number": "",
          "tracking_url": "",
          "shipped_at": {
            "date": "2018-05-29 15:42:37.000000",
            "timezone_type": 3,
            "timezone": "UTC"
          },
          "items": [
            {
              "item_id": 5443,
              "quantity": 1
            }
          ]
        }
      ],
      "items": [
        {
          "id": 5443,
          "external_id": null,
          "variant_id": 40,
          "name": "8\" x 8\"",
          "quantity": 1,
          "price": "5.34",
          "price_details": {
            "currency": "USD",
            "formatted": "$ 5.34",
            "in_subunit": 534
          },
          "file": "http:\/\/api.picanova.com\/premiumprint\/example\/orders\/PPO26149838T\/38ba27cda8fb5545f1676ddce67049df.jpg",
          "options": [
            {
              "id": 1,
              "name": "Canvas border",
              "value": {
                "id": 2,
                "name": "Folded"
              }
            },
            {
              "id": 2,
              "name": "Stretcher frame",
              "value": {
                "id": 6,
                "name": "2 cm"
              }
            }
          ],
          "retail_price": null,
          "retail_price_details": null
        }
      ],
      "totals": {
        "subtotal_amount": "5.34",
        "subtotal_amount_details": {
          "currency": "USD",
          "formatted": "$ 5.34",
          "in_subunit": 534
        },
        "shipping_amount": "3.70",
        "shipping_amount_details": {
          "currency": "USD",
          "formatted": "$ 3.70",
          "in_subunit": 370
        },
        "total_amount": "9.04",
        "total_amount_details": {
          "currency": "USD",
          "formatted": "$ 9.04",
          "in_subunit": 904
        },
        "customs_shipping_costs": "1111.00",
        "customs_shipping_costs_details": {
          "currency": "USD",
          "formatted": "$ 1111.00",
          "in_subunit": 111100
        }
      },
      "retail_costs": []
    }
  }
}
                            

Print Files

Providing print files

To provide a print file to the API, specify a path on a webserver in the JSON node "file" within the "items" dictionary. We recommend to use an obfuscated path which also contains an authentication token or session ID to make sure the files cannot be accessed freely on the internet. Also, make sure to set the path where the files are stored on the server to "noindex, nofollow" in your "robots.txt", to make sure search engines do not try to index it.

Example: https://www.example.com/download_print_data/12345/6789?token=XJRHAZQU76AU41KJNIHV1MQJ

The print file is downloaded as soon as the order is read into our system, but since processing is done asynchronously, we recommend to either calculate print files on demand by a server-side controller or, when you prepare them in advance, keep them on the server for a certain time to allow our systems to download and process them before you delete them from your server.

File format

Print files can be provided in JPEG or PNG format. JPEG files are preferred for better compression, except when transparency is required (e.g. for the T-Shirt product). We recommend to provide RGB files, preferably with an sRGB or AdobeRGB color profile attached. Other color profiles and color spaces can be handled, but loss of print quality might result when the files are converted for the print process.

Resolution and aspect ratio

Files need to be provided in sufficient resolution and correct aspect ratio. Some sanity checks are done by our systems to protect against the most common usage errors, but generally, the customer is responsible to provide correct print files for the orders.

Please note that the resolution/dpi value saved in the files is ignored by the system since the files are automatically scaled to fit the product. Instead the size, i.e. the width and height in pixels, needs to be sufficient to fulfill the minimum resolution for the product. Please use the "products" API to retrieve the information about the minimum resolution for each product, as well as the aspect ratio your files should have.

Example: The Puzzle product has a minimum resolution of 72 dpi (dots per inch) and the variant "20x27 cm - 88 Pieces" has a print file size of 270x200 millimeters. The minimum size of the image in pixels is therefore 765x567 (270 / 25.4 * 72, 200 / 25.4 * 72), but you can improve print quality by providing a larger file, but must make sure that the aspect ratio (ratio between width and height) always matches a ratio of 27:20.

A notable exception to this rule is the "Canvas" product when used in conjunction with the FOLDED border effect. The FOLDED border effect allows the customer to specify the portion of the image which is wrapped around the stretcher frame of the Canvas. This means that in this case the print file must include an image border to wrap around the stretcher frame. The border must be 25mm for the 2cm stretcher frame and 45mm for the 4cm stretcher frame. So for example, for a 40x30cm canvas, when using a FOLDED border effect with a 2cm stretcher frame, the effective size of the print file must be 45x35cm, which changes the required aspect ratio from 4:3 to 9:7 (45:35) and also increases the minimum pixel size. But this is only required when using the FOLDED border effect, not when using one of the other border effects like STRETCHED or MIRRORED, since, when using the latter, the border is created by the system automatically.

Depending on the product, files above a certain resolution only increase the storage space and load on the systems, but do not improve print quality. For practically all products, files with a resolution larger than 300dpi do not make sense in practice.