Data model
If you are a regular user of our website printoclock.com, you are used to create carts and place orders with 1.N items inside.
On the API side, even if we use the same backend, we have decided to allow only one item per order (to keep it simple for now).
If you go to our website, and browse a product, Business card for example, you will have several options to choose from (sizes, material, print side, …, quantity and delay) each of this option can be combined. The combination of all of these is a variant.
To quickly explain what is our data model, this is a commented response to a GET on orders/{id} on our API :
{
"externalReference":"MYREF", //your own order reference (the one you POSTed) - not mandatory
"customer":{ //the customer the order has been placed for (understand "the owner of the order", one of your own customers)
"defaultAddress":{ //this customer default address (this is not the delivery address)
"id":4872964, //address id in our system
"firstName":"John",
"lastName":"Doe",
"phoneNumber":"0605040301",
"company":"Customer company",
"provinceCode":"FR-31",
"provinceName":"HAUTE-GARONNE",
"street":"1 rue de la paix",
"city":"Toulouse",
"postcode":"31000"
},
"externalCustomerId":null, //this customer ID in your system - not mandatory
"id":266118, //this customer ID in our system
"email":"customer@email.com" //this customer email in our system - not mandatory, we don't need your customer email address to process order, but you can provide it if you want
},
"billingAddress":{ //billing address for this order
"id":4880437, //address id in our system
"firstName":"",
"lastName":"",
"phoneNumber":"",
"company":"YOUR COMPANY NAME",
"provinceCode":"FR-01",
"provinceName":"AIN",
"street":"123 as ABC",
"city":"PARIS",
"postcode":"01234"
},
"shipments":[ //shipments linked to this order
{
"packages":[ //packages in shipment (depending on carriers your order may be splitted in several packages)
{
"tracking":null, //trakcing number of the package
"weight":4, //weight of the package
"id":9533983, //id in our system
"trackingUrl":null //tracking url for this package
}
],
"shippingAddress":{ //shipping address for this shipment.
"id":4880438, //address id in our system
"firstName":"Jeanne",
"lastName":"D'arc",
"phoneNumber":"0102030405",
"company":null,
"provinceCode":"FR-31",
"provinceName":"HAUTE-GARONNE",
"street":"15 bis rue des toulousains",
"city":"Toulouse",
"postcode":"31000"
},
"id":2266287, //shipment Id in our system
"state":"ready", //shipment state (see state section for details.)
"tracking":null, //
"createdAt":"2020-11-23T09:55:55+01:00",
"updatedAt":"2020-11-23T09:55:55+01:00",
"numberPackages":1, //count of packages
"weight":4, //total weight of shipment (sum of packages)
"orderItems":[ "..." ] //items in this shipment (see items node below for details).
}
],
"currencyCode":"EUR", //currency of this order (EUR is the only one available for now)
"localeCode":"fr", //locale of this order (fr is the only one available for now)
"shippingState":"ready", //shipping state of the order (combined state of all shipments states - see state section for details.)
"paymentState": "credit_granted", //payment state of the order (see state section below for details.)
"id":1475362, //order id in our system
"checkoutCompletedAt":"2020-11-23T09:55:55+01:00",
//exact datetime of when the order has been placed (start date for all estimated production and delivery date)
"number":"001137567", //order reference in our system
"items":[ //list of items (products) in order - on the API side 1 item per 1 order for now.
{
"documentState": "string", //state of the document you provide (see state section below for details)
"manufacturingState": "string", //state of the production of your item
"userInputs":[ //user input data - you will see there data that need to be posted to create order but that is not in a preselected list (like item.options)
{
"option":{
"code":"dimensions", //the option code for dimensions
"name":"Dimensions"
},
"optionValue":null,
"value":"200x200" //the value we received
},
{
"option":{
"code":"quantity", //the option code for quantity
"name":"Quantité"
},
"optionValue":null,
"value":"1" //the value we received
}
],
"number":"001137567-1", //order item reference in our system (order reference suffixed)
"estimatedDeliveryDate":"2020-11-30T00:00:00+01:00",
//estimated delivery date (calculated by our system)
"estimatedShippedDate":"2020-11-27T00:00:00+01:00",
//estimated shipping date (end of production)
"externalReference":null, //order item reference in your system
"productName":"Lino personnalisé",
//product name in order locale
"variantName":"x1 Lino personnalisé Classique (gratuite et express) J+5 Lino ignifugé 200cm x 200cm",
//variant name in order locale (the variant is the result of options combinations)
"id":1648120, //order item id in our system
"productCode":"LINO", //product unique code in our system
"variantCode":"LINO_LINOM3_CLA_J5", //variant unique code in our system
"shippingAddress":{ //shipping adress for this item you POSTed.
"id":4880438, //shipping adress id in our system (note : it's the same id as the adress in shipments[0].shippingAddress)
"firstName":"Jeanne",
"lastName":"D'arc",
"phoneNumber":"0102030405",
"company":null,
"provinceCode":"FR-31",
"provinceName":"HAUTE-GARONNE",
"street":"15 bis rue des toulousains",
"city":"Toulouse",
"postcode":"31000"
},
"weight":4, //calculated weight of your item
"packageCount":1, //calculated package count of your item depending on carrier and weight
"carrier":{ //carrier selected to deliver your item
"name":"DPD",
"code":"dpd",
"id":2
},
"options":[ //options of your item
{
"code":"CLA", //option value unique code
"option":{
"code":"check_service", //option unique code
"name":"Vérification de fichier"
//option name in locale
},
"value":"Classique (gratuite et express)"
//option value in locale
},
{
"code":"J5",
"option":{
"code":"delay",
"name":"Délais"
},
"value":"J+5"
},
{
"code":"LINOM3",
"option":{
"code":"material",
"name":"Papier"
},
"value":"Lino ignifugé"
}
],
"quantity":1 //total quantity (depending on product, quantity could be a user input or option value, whatever it is, the final quantity is displayed here)
}
],
"total":"124,80€", //total including tax
"state":"new", //order state (see below)
"estimatedDeliveryDate":"2020-11-30T00:00:00+01:00"
//order estimated delivery date (maximum date of all items.estimatedDeliveryDate - here it's the same as long as 1 order has 1 item on API side)
}
States
order.state
These are the main order states.
| state | Description |
|---|---|
| new | Order is created in our system |
| fulfilled | Order is fulfilled - all items in order are delivered |
| cancelled | Order is cancelled |
order.payment_state
This is the state of the payment of the order.
| state | Description |
|---|---|
| awaiting_payment | We are waiting for payement |
| partially_paid | Payment is not complete |
| paid | Payment is complete, production can start |
| credit_granted | Credit is granted but payment is not yet complete, production can start |
| awaiting_refund | Payment has to be refunded |
| partially_refunded | Part of payment has been refunded |
| refunded | Payment has been refunded |
| cancelled | Payment has been cancelled |
On the API side, the payment is done at the end of month depending on your commercial agreement with us.
We do not provide options to use a credit card for payment for now, so all orders are “credit_granted” when placed.
order.shippingState
This is the combined shipping state of all shipments in your order.
| state | Description |
|---|---|
| ready | Waiting for shipment |
| partially_shipped | At least one of the shipments has been shipped |
| shipped | All shipments have been shipped |
| partially_delivered | At least one of the shipments has been delivered |
| delivered | All shipments have been delivered |
| cancelled | All shipments have been cancelled |
If one shipment si delivered and an other one is shipped, the shippingState will be “partially_delivered”.
In the context of our API an order have only one item (for now) and an item has only one shipment (for now), so the order.shippingState and order.shipments[0].state should be the same.
order.items[0].document_state
This is the state of the provided document(s) for your item in your order.
| state | Description |
|---|---|
| awaiting_source_upload | We are waiting for your document |
| awaiting_source_download | Document uploaded |
| source_downloaded | Document received in our office |
| awaiting_validation | Document awaiting for beeing checked |
| validation_in_progress | Check in progress, someone is working on the document |
| awaiting_proof_validation | Proof has been requested, document is sent to validation |
| proof_accepted | Proof accepted |
| awaiting_final_validation | A problem has been found during the check process, a corrected document is produced and sent to validation |
| final_accepted | Correction approved |
| ready_to_print | Document is ready to be printed |
| skipped | No need for document validation |
| cancelled | Document process has been cancelled |
Note : This is a simplified version, most of “cancel” transition are not displayed. An order is “cancelable” until work on the document has not started (validation_in_progress)
order.items[0].manufacturing_state
This is the manufacturing state of your item in your order.
| state | Description |
|---|---|
| new | Awaiting for production of your item |
| ready | Production of item has started |
| printed | Item has been printed, if finishing is required, finishing can start |
| packed | Item has been packed, shipment can be done |
order.shipments[0].state
This is the state of the shipment.
| state | Description |
|---|---|
| ready | Shipment is waiting to be done |
| labeled | A tracking label has been printed for this shipment |
| shipped | Shipment is shipped |
| delivered | Shipment is delivered |
| not_delivered | Shipment is not delivered, a problem has occured |
| stored | Shipment has been sent back to us and stored in our factory |
| cancelled | Shipment has been cancelled |
Note : shipment state is the state of 1 shipment (it’s different from order shipping state that is the combined state of all shipment)