Profotonet API implementation v1

Key

Add the given key to the request header under the tag: key.

Content-type

Add the Content-type: "application/json" to the request header under the tag: content-type.

Structure of the response messages.

Response success

HTTP status code(s)	200
Type	JSON

Examples will be added to the calls.

Response error

HTTP status code(s)	400, 401, 403, 404, 409, 422, 500
Type	JSON

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.

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.


          {
  errors: [
    {
      field: "orderId",
      message: "Invalid parameter"
    }
  ]
}

A list of the order statuses returned by multiple requests

accepted	Order was accepted by the API.
downloading	Order is downloading the necessary files.
prepare	Order is getting prepared for production.
hold	Order is getting evaluated by our customer support.
production	Order is in production.
shipped	Order (or a part of the order) is shipped.
reprint	Order is getting evaluated to reprint.
deleted	Order is deleted.

Callbacks of our status to your API. The url can be modified in your account settings on https://app.profotonet.nl

URL	Your URL
Method	POST
Retries	Once every 2 hours for 3 days

Field	Type	Description
id	ObjectID	Our unique ObjectId
orderId	Int	Our orderId
referenceId	String	Your unique id
status	String	Status of the order
trackAndTraceCode	String	Track and trace tracking id (barcode) (if present). If the code starts with 3SMILE or 3SPROF (PostNL letters and normal sized package), you can create the link yourself. For example: https://jouw.postnl.nl/?lang=nl#!/track-en-trace/3SMILE0000001/NL/1234AA. If the code start with 3SYSWD (PostNL extra@home for large packages) or GLS then the trackinglink will be send in the trackAndTraceLink.
trackAndTraceLink	String	Track and trace https tracking link (if present).


          {
  id: "507f1f77bcf86cd799439011",
  orderId: 1000023,
  referenceId: 10000000,
  status: "shipped",
  trackAndTraceCode: "3SYSWD0000001",
  trackAndTraceLink: "http://postnl.nl/tracktrace/?B=3SYSWD0000001&P=1234AA&D=NL&L=NL&T=C"
}

Returns a list of all the products which can be ordered using the API. The request might take some time since it will return all the products at once. Cache the results of the request if you need it often.

URL	https://api.profotonet.nl/v1/products
Method	GET

Field	Type	Description
productId	Integer	The unique id of the product used in an entry.
name	String	Full name of the product.
price	Integer	Price of the product in cents.
options	Array	Array with optional options.
options[].name	String	Name of the option.
options[].code	String	Code of the option used in an entry.
options[].attributes	Array	Array of possible attributes of the option.
options[].attributes[].name	String	Name of the attribute.
options[].attributes[].code	String	Code of the attribute used in an entry.
shippingMethods	Array	Array of shippingMethods used for this product.
shippingMethods[].name	String	Name of the shippingMethod.
shippingMethods[].pricing	Object (key-value)	Key-value object containing the prices for the countries. ISO-3166 country codes are used as key for countries with a special price and "default" is set for the rest of the possible countries. The value is the price in cents. Note: the item with the highest shipping price is used as the shipping price for the order.


          {
  "productId": 1002201300190001,
  "name": "Schoolfotoset A - Papiersoort: Glans",
  "price": 127,
  "options": [
    {
      "name": "Witte randen",
      "code": "whiteborder",
      "attributes": [
        {
          "name": "Witte randen",
          "code": "checked"
        }
      ]
    },
    {
      "name": "Optimalisatie",
      "code": "optimalisation",
      "attributes": [
        {
          "name": "Optimalisatie",
          "code": "checked"
        }
      ]
    }
  ],
  "shippingMethods": [
    {
      "name": "Brievenbuspost via PostNL",
      "pricing": {
        "default": 349,
        "nl": 249
      }
    },
    {
      "name": "Brievenbuspost als pakket via PostNL",
      "pricing": {
        "default": 899,
        "nl": 599
      }
    }
  ]
},
{
    "productId": 1003705000500003,
    "name": "Canvas 2cm (50 x 50) - Houten baklijst: Wit",
    "price": 8195,
    "options": [
      {
        "name": "Afwerking randen",
        "code": "canvasedge",
        "attributes": [
          {
            "name": "Geen bewerking",
            "code": "none"
          },
          {
            "name": "Uitrekken",
            "code": "stretch"
          },
          {
            "name": "Spiegelen",
            "code": "mirror"
          },
          {
            "name": "Wit laten",
            "code": "white"
          }
        ]
      }
    ],
    "shippingMethods": [
      {
        "name": "Pakketpost via PostNL",
        "pricing": {
          "default": 899,
          "nl": 599
        }
      }
    ]
  }

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.

URL	https://api.profotonet.nl/v1/order
Method	POST

Request

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, 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	Note: this is for special usecases only and not required, do not use this before contacting us first! 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		Note: this is for special usecases only and not required, do not use this before contacting us first! 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		Note: this is for special usecases only and not required, do not use this before contacting us first! 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.
label	Object	false		Note: this is for special usecases only and not required, do not use this before contacting us first! Custom label used to send with the order (pdf).
label.url	String	true		Url to download the label from.
label.md5	String	false		Optional MD5 of the file for extra checks after the download.


          {
  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: "j.doe@mailprovider.com",
  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"
  },
  label: {
    url: "https://www.testwebsite.nl/DH98sa7daKJhdKShdSD987/KJDShg9a8sd9878HDSsade.pdf",
    md5: "a90790e52d1c0e138edf47c5324ebeeb"
  }
}

Response success

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.


          {
  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
      }
  ]
}

Get information of the order from the system. Return fields might be added in the future on request.

URL	https://api.profotonet.nl/v1/order?referenceId=1000000
Method	GET

Field	Type	Description
referenceId	Integer	Your unique id
test	Boolean	If you are testing set this to true (add &test=true to the url). If you are not testing you can set this to false or not even include it at all. The API will return testing data, even if the referenceId is an existing one.

Response success

Field	Type	Description
id	ObjectId	The objectid assigned to the order.
orderId	Integer	The orderid assigned to the order. Set if the order has been downloaded
status	String	The status assigned to the order.
total	Integer	The total of the order in cents (tax included).
taxTotal	Integer	The total of the tax of the order in cents.
subTotal	Integer	The subtotal of the order in cents (tax included).
shippingTotal	Integer	The shippingtotal of the order in cents (tax included).
shippingTaxTotal	Integer	The total of the tax of the shipping in cents.
startingCostsTotal	Integer	The startingcoststotal of the order in cents (tax included).
startingCostsTaxTotal	Integer	The total of the tax of the startingscosts in cents.
entryTotals	Array	The totals per productId of the order.
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).
entryTotals[].taxTotal	Integer	Total tax of the cartentries ordered under the productId.
trackAndTrace	Array	Track and trace of the order. The order can be split into several parts with each part having a different code.
trackAndTrace[].code	String	Track and trace code of the order (or a part of it).


          {
  id: '507f1f77bcf86cd799439011',
  orderId: 1000023,
  status: "order",
  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
      }
  ],
  trackAndTrace: [
      {
        code: "3SYMFU0000001"
      }
  ]
}

Reprint entries of an order. Reprints can be requested within 28 days of the initial orderdate. Reprints will always be evaluated by the customer support before being submitted. If necessary we will contact you.

This is an optional process and can only be tested if there are processed orders in our system. Reprints can also be handled by contacting our customer support and this is our preferred way to handle this!

URL	https://api.profotonet.nl/v1/reprint
Method	POST

Reasons

damaged	Order or a part of the order was damaged.
incomplete	Order is incomplete.
missing	Order is missing.
swappedpartially	A part of the order was swapped with (a part of) another order.
swappedcompletely	The whole order was swapped with another order.
quality	Quality of the order is not as expected.

Request

Field	Type	Required	Default	Description
test	Boolean	false	false	If test is true, the request is only tested on correctness.
referenceId	String	true		Your unique id. This id is used to find the order to reprint.
entries	Array	true		Array of all the entries.
entries[].referenceId	Integer	true		Your unique entry id. This id is used to find the entry to reprint.
entries[].quantity	Integer	false	The quantity of the entry	Quantity of the entry to reprint.
reason	String	true		The code of the reason for the reprint (see possible values above).
note	String	false		A note can be added to the reprint to help with the evaluation.


          {
  test: true,
  referenceId: 10000000,
  entries: [
    {
      referenceId: 10000,
      quantity: 1
    },
    {
      referenceId: 10001
    }
  ],
  reason: "damaged",
  note: "Order was damaged."
}

Response success

Field	Type	Description
id	ObjectId	The objectid assigned to the reprint.
orderId	Integer	The orderId of the order the reprint was requested for.


          {
  id: '507f1f77bcf86cd799439011',
  orderId: 1000023
}

Profotonet API implementation v1

Basic implementation

Key

Content-type

Responses

Response success

Response error

Resultcodes

Order statuses

Status callback

Get products

Insert order

Request

Response success

Get order

Response success

Reprint order (optional)

Reasons

Request

Response success