Profotonet API implementation v1

Basic implementation

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.

Responses

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

Order statuses

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.

Status callback

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"
}

Get products

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 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.

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. 
{
  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"
  }
}

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 order

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 order (optional)

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
}