Appearance
Insert order
Insert a new order into the system. If the information is correct the order will be inserted as a cart and the files will be downloaded from the given urls. As soon as the download process is complete the cart will be converted into an order and the orderId will be assigned.
Endpoint
| Key | Value |
|---|---|
| URL | https://api.profotonet.nl/v1/order |
| Method | POST |
Request object for print(s) order
Key / Value overview
| Field | Type | Required | Default | Description | Note |
|---|---|---|---|---|---|
| test | Boolean | false | false | If test is true, the request is only tested on correctness. | |
| testNotificationUrl | String | false | false | If test is true and testNotificationUrl is set, the test insert will also fire a status callback with test data. The status callback is explained in a different section of this documentation. | |
| notificationUrl | String | false | false | If set, this url will be used for status callbacks for the order instead of the default notificationUrl filled in under your account. | |
| referenceId | String | true | Your unique id. This id is used to push and get the status and to reprint an order. | ||
| reference | String | false | Your internal reference. This reference can be used if you need to contact customer support, if (for example) the referenceId is an UUID. | ||
| companyName | String | false | Companyname of the customer. | ||
| firstName | String | true | Firstname of the customer. | ||
| lastName | String | true | Lastname of the customer. | ||
| emailAddress | String | false | Email of the customer which will be used for send & track-notifications | ||
| phoneNumber | String | false | Phonenumber of the customer which will be used for send & track-notifications | ||
| street | String | true | Street of the customer. | ||
| houseNumber | String | true | Housenumber (+ addition) of the customer. | ||
| zipCode | String | true | Zipcode of the customer. | ||
| city | String | true | City of the customer. | ||
| state | String | false | State of the customer. | ||
| country | String | true | ISO-3166 2 char country code | ||
| shippingMethod | String | true | Possible values: pickup, send, postnlpickuppoint, sendaspackage (overwrites shippingmethod to package if it is going to be send as a letter). | ||
| pickupLocationCode | String | false | Required if shippingMethod is "postnlpickuppoint" and should contain the locationCode retrieved from the PostNL API. This value will be validated using the follow route: https://api.postnl.nl/shipment/v2_1/locations/lookup?LocationCode={pickupLocationCode} | ||
| sorting | Boolean | false | false | This can be used to send in multiple orders in 1 batch after which the whole batch is sorted based on the sortingReference and thereafter will be shipped to 1 location. Additional charges will be applied. Sorting will only be applied to photoprints (lustre and glossy) to a maximum of 30x45 and photoproducts like keychains and mugs. Products like (for example) canvas, walldecoration and larger photo sizes are not prohibited within the order, but will not be individually sorted. | |
| entries | Array | true | Array of all the entries. | ||
| entries[].referenceId | Integer | true (false if productId starts with 12000) | Your unique entry id. This id is used to reprint order. | ||
| entries[].productId | Integer | true | ProductId supplied by us | ||
| entries[].quantity | Integer | true | Quantity of the entry. | ||
| entries[].backprint | String | false | Custom backprint for the image (max 60 characters). | ||
| entries[].sortingReference | String | false | SortingReference (max. 60 characters) is required in combination with the sorting parameter. The sortingReference is used by us to know which parts of the orders need to be combined and the sortingReference will be visible behind the transparant window of the envelope. It is important to note that the sortingReferences need to be in consecutive order within entries (entries are basicly grouped together this way). Also Make sure that sortingReference is unique per order. An example of a sortingReference would be: "1A – Voornaam Achternaam - 100012". | ||
| entries[].file | Object | true (false if productId starts with 12000) | Fileobject of the entry. | ||
| entries[].file.name | String | true | Original filename including the extension (jpg, png, tiff or pdf if productId starts with 11000). | ||
| entries[].file.url | String | true | Url to download the file from. | ||
| entries[].file.md5 | String | false | Optional MD5 of the file for extra checks after the download. | ||
| entries[].options | Array | false | Options used for certain products. | ||
| entries[].options.code | String | true | Code supplied by us to point to the option. | ||
| entries[].options.value | String | true | Attribute values supplied by us for the option. | ||
| entries[].note | String | false | Only needed for products without a file (for example if a certain type of flyer needs to be added to the order). Note for the product (max 60 characters). | ||
| packingSlip | Object | false | Custom packingslip used to send with the order (pdf). | ||
| packingSlip.url | String | true | Url to download the packingslip from. | ||
| packingSlip.md5 | String | false | Optional MD5 of the file for extra checks after the download. |
Example of an order object
json
{
test: true,
testNotificationUrl: "https://testurl.ofyourwebsite.com/statuscallback",
notificationUrl: "https://url.ofyourwebsite.com/statuscallback",
referenceId: "10000000",
reference: "10000000",
companyName: "Company",
firstName: "John",
lastName: "Doe",
emailAddress: "[email protected]",
phoneNumber: "0031102912302",
street: "Street",
houseNumber: "1A",
zipCode: "1234AA",
city: "Rotterdam",
state: "",
country: "NL",
shippingMethod: "send",
entries: [
{
referenceId: 10000,
productId: 1002201300190001,
quantity: 1,
backprint: "",
file: {
name: "testimage1.jpg",
url: "https://images.testwebsite.nl/DH98sa7daKJhdKShdSD987/KJDShg9a8sd9878HDSAC.jpg",
md5: "e2c0c4781074792afbaf73c6af5eae87"
},
options: [
{
code: "whiteborder",
value: "checked"
}
]
},
{
referenceId: 10001,
productId: 1003705000500003,
quantity: 1,
backprint: "",
file: {
name: "testimage2.png",
url: "https://images.testwebsite.nl/DH98sa7daKJhdKShdSD987/KJDShg9a8sd9878HDSAD.png",
md5: "7815696ecbf1c96e6894b779456d330e"
},
options: [
{
code: "canvasedge",
value: "mirror"
}
]
}
],
packingSlip: {
url: "https://www.testwebsite.nl/DH98sa7daKJhdKShdSD987/KJDShg9a8sd9878HDSsada.pdf",
md5: "6af0d8b2c5c3fff02066b31e8e83c192"
}
}Request object for photobook(s) order
Key / Value overview
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| test | Boolean | false | false | If test is true, the request is only tested on correctness. |
| testNotificationUrl | String | false | false | If test is true and testNotificationUrl is set, the test insert will also fire a status callback with test data. The status callback is explained in a different section of this documentation. |
| notificationUrl | String | false | false | If set, this url will be used for status callbacks for the order instead of the default notificationUrl filled in under your account. |
| referenceId | String | true | Your unique id. This id is used to push and get the status and to reprint an order. | |
| reference | String | false | Your internal reference. This reference can be used if you need to contact customer support, if (for example) the referenceId is an UUID. | |
| companyName | String | false | Companyname of the customer. | |
| firstName | String | true | Firstname of the customer. | |
| lastName | String | true | Lastname of the customer. | |
| emailAddress | String | false | Email of the customer which will be used for send & track-notifications | |
| phoneNumber | String | false | Phonenumber of the customer which will be used for send & track-notifications | |
| street | String | true | Street of the customer. | |
| houseNumber | String | true | Housenumber (+ addition) of the customer. | |
| zipCode | String | true | Zipcode of the customer. | |
| city | String | true | City of the customer. | |
| state | String | false | State of the customer. | |
| country | String | true | ISO-3166 2 char country code | |
| shippingMethod | String | true | Possible values: pickup, send, sendaspackage (overwrites shippingmethod to package if it is going to be send as a letter). | |
| entries | Array | true | Array of all the entries. | |
| entries[].referenceId | Integer | true (false if productId starts with 12000) | Your unique entry id. This id is used to reprint order. | |
| entries[].productId | Integer | true | ProductId supplied by us | |
| entries[].quantity | Integer | true | Quantity of the entry. | |
| entries[].files | Object | true (false if productId starts with 12000) | Filesobject of the entry. | |
| entries[].files.coverEmbossing | Object | true (if product contains embossing) | If the photobook contains embossing this object is required. The coverFile is not needed in this case | |
| entries[].files.coverEmbossing.line1 | String | true | First line of embossing | |
| entries[].files.coverEmbossing.line2 | String | true (Depending on the PLU) | Second line of embossing | |
| entries[].files.coverEmbossing.line3 | String | true (Depending on the PLU) | Third line of embossing | |
| entries[].files.coverFile | Object | true (if product contains a photocover) | If the photobook contains a photocover this object is required. The coverEmbossing is not needed in this case | |
| entries[].files.coverFile.name | String | true | Original filename including the extension (jpg, png, tiff or pdf if productId starts with 11000). | |
| entries[].files.coverFile.url | String | true | Url to download the file from. | |
| entries[].files.coverFile.md5 | String | false | Optional MD5 of the file for extra checks after the download. | |
| entries[].files.spreadFiles[] | Array | true | Array of all the spreadfiles for the photobook | |
| entries[].files.spreadFiles[].name | String | true | Original filename including the extension (jpg, png, tiff or pdf if productId starts with 11000). | |
| entries[].files.spreadFiles[].url | String | true | Url to download the spread from. | |
| entries[].files.spreadFiles[].md5 | String | false | Optional MD5 of the file for extra checks after the download. |
Example of an order object
json
{
test: true,
testNotificationUrl: "https://testurl.ofyourwebsite.com/statuscallback",
notificationUrl: "https://url.ofyourwebsite.com/statuscallback",
referenceId: "10000000",
reference: "10000000",
companyName: "Company",
firstName: "John",
lastName: "Doe",
emailAddress: "[email protected]",
phoneNumber: "031102912302",
street: "Street",
houseNumber: "1A",
zipCode: "1234AA",
city: "Rotterdam",
state: "",
country: "NL",
shippingMethod: "pickup",
entries: [
{
referenceId: "10000001",
productId: "hardcoverbook_15x15_th-unthickened_pa-velvetalbum_co-embossingcover_cm-naturecork_em-1linelarge_ec-white",
quantity: 1,
files: {
// If product contains a photocover
coverFile: {
name: "cover.jpg",
url: "https://images.testwebsite.nl/7254230/cover.jpg",
md5: "4680c4781074792afbaf73c6af5eakkj"
},
// If product contains embossing
coverEmbossing: {
line1: "Wedding in Italy",
line2: "John & Gina",
line3: "20-05-2026"
},
spreadFiles: [
{
name: "spread_001.jpg",
url: "https://images.testwebsite.nl/7254230/spread_001.jpg",
md5: "2e70c4781074792afbaf73c6af5eanb6"
},
{
name: "spread_002.jpg",
url: "https://images.testwebsite.nl/7254230/spread_002.jpg",
md5: "ag40c4781074792afbaf73c6af5ea2df"
},
{
name: "spread_003.jpg",
url: "https://images.testwebsite.nl/7254230/spread_003.jpg",
md5: "c2e0c4781074792afbaf73c6af5eakj3"
},
{
name: "spread_004.jpg",
url: "https://images.testwebsite.nl/7254230/spread_004.jpg",
md5: "avg0c4781074792afbaf73c6af5ean99"
},
{
name: "spread_005.jpg",
url: "https://images.testwebsite.nl/7254230/spread_005.jpg",
md5: "98r0c4781074792afbaf73c6af5ea6yy"
},
{
name: "spread_006.jpg",
url: "https://images.testwebsite.nl/7254230/spread_006.jpg",
md5: "4tg0c4781074792afbaf73c6af5eallf"
},
{
name: "spread_007.jpg",
url: "https://images.testwebsite.nl/7254230/spread_007.jpg",
md5: "lk30c4781074792afbaf73c6af5eai90"
},
{
name: "spread_008.jpg",
url: "https://images.testwebsite.nl/7254230/spread_008.jpg",
md5: "2210c4781074792afbaf73c6af5ea7u8"
},
{
name: "spread_009.jpg",
url: "https://images.testwebsite.nl/7254230/spread_009.jpg",
md5: "5yh0c4781074792afbaf73c6af5ea33e"
},
{
name: "spread_010.jpg",
url: "https://images.testwebsite.nl/7254230/spread_010.jpg",
md5: "asd0c4781074792afbaf73c6af5eab21"
},
{
name: "spread_011.jpg",
url: "https://images.testwebsite.nl/7254230/spread_011.jpg",
md5: "lj60c4781074792afbaf73c6af5eae11"
},
{
name: "spread_012.jpg",
url: "https://images.testwebsite.nl/7254230/spread_012.jpg",
md5: "po90c4781074792afbaf73c6af5eae87"
}
]
}
}
]
}Response object(s)
Structure of the response messages.
Resultcodes
| Code | Description |
|---|---|
| 200 | Success |
| 400 | Bad request. Invalid parameters. |
| 401 | Unauthorized. Check if APIid and APIkey are set correctly. |
| 403 | Forbidden. Illegal action. |
| 404 | Not found. |
| 409 | Conflict. Already exists. |
| 422 | Unprocessable entity. Incorrect parameters. |
| 500 | Internal server error. |
Response success
| Key | Value |
|---|---|
| HTTP status code(s) | 200 |
| Type | JSON |
Examples will be added to the calls.
Success object
| Field | Type | Description |
|---|---|---|
| id | ObjectId | The objectid assigned to the order. |
| status | String | The status assigned to the order. |
| total | Integer | The total of the order in cents (tax included). Returns 0 in test. |
| taxTotal | Integer | The total of the tax of the order in cents. Returns 0 in test. |
| subTotal | Integer | The subtotal of the order in cents (tax included). Returns 0 in test. |
| shippingTotal | Integer | The shippingtotal of the order in cents (tax included). Returns 0 in test. |
| shippingTaxTotal | Integer | The total of the tax of the shipping in cents. Returns 0 in test. |
| startingCostsTotal | Integer | The startingcoststotal of the order in cents (tax included). Returns 0 in test. |
| startingCostsTaxTotal | Integer | The total of the tax of the startingscosts in cents. Returns 0 in test. |
| entryTotals[].productId | Integer | ProductId supplied by us. |
| entryTotals[].quantity | Integer | Total quantity of the cartentries ordered under the productId. |
| entryTotals[].total | Integer | Total price of the cartentries ordered under the productId (tax included). Returns 0 in test. |
| entryTotals[].taxTotal | Integer | Total tax of the cartentries ordered under the productId. Returns 0 in test. |
json
{
id: "507f1f77bcf86cd799439011",
status: "accepted"
total: 8996,
taxTotal: 1561,
subTotal: 8322,
shippingTotal: 575,
shippingTaxTotal: 100,
startingCostsTotal: 99,
startingCostsTaxTotal: 17,
entryTotals: [
{
productId: 1002201300190001,
quantity: 1,
total: 127,
taxTotal: 22
},
{
productId: 1003705000500003,
quantity: 1,
total: 8195,
taxTotal: 1422
}
]
}Response error
| Key | Value |
|---|---|
| HTTP status code(s) | 400, 401, 403, 404, 409, 422, 500 |
| Type | JSON |
Error object
| Field | Type | Description |
|---|---|---|
| errors | Array | An array of the errors. |
| errors[].field | String | The field the error occurred on. |
| errors[].message | String | A description of the error. |
json
{
errors: [
{
field: "orderId",
message: "Invalid parameter"
}
]
}