Introduction
Welcome to the to.photo API! You can use our API to access to.photo API endpoints, which will serve you 24/7 with beautiful, high quality photo products.
Workflow
This section will describe a typical workflow between an App, the to.photo API and the inner processes for a better understanding.
In this example workflow we use Series as the showcase. Series is a mobile App, giving you the possibility to take a series of congruent images over a long period of time. Series has an mobile Client App, called Series-App, and the Server Application, called Series-Server.
At a given time the App will start the checkout process. First it is necessary to determine the domain specific resulting products, to be able to calculate the prices to be displayed.
The App gives a segment order to the to.photo API via the Series server. This order has information about the used images, including sizes and meta data (which design, text, etc.). Additionally the order specifies a Processor, this implies which products will be segmented. A processor is a domain specific implementation of a product. The API generates an OrderID and determines, based on the processor, how many pictures would be generated and whether additional data would be added. The cart now holds the calculated amount of products.
The Series server now defines the cart value depending on the product(s) with it's own price logics and delivers this information back to the App. The App shows the cart to the customer ans initiates the checkout by request, here the address data will be collected and the payment processed. This data will also be sent to the API. Finally the Series server will send a finalize order to the API (upload all images and additional data in a single ZIP archive). The API will unzip the archive, verifies the order and saves it to the hard drive and the database. Additionally while finalization production specific OrderIDs will be allocated. In the end the order is queued for the asynchronous rendering process.
The API returns the generated order. The App acknowledges the successful order placement, the App server processes the payment and the order is finished.
Roles
3 roles are distinguished throughout this documentation.
| Name | Abbreviation | Description |
|---|---|---|
| Server | S | Everything the server does in response to API-requests |
| Mandator | M | Integrational role between Server und User/Frontend. Some data originates from the user and is just routed through to the server while some is process / workflow specific |
| User / Customer | U | The User who is ordering photo products through the system. In general the order process has indirect character via additional meta information available in the domain of the mandator's domain |
Portal / Mandator
Portals are mandator specific and are meant to describe a specific project or public facing product.
It is thinkable to correlate specific price and / or product profiles to a portal at mandator-side.
Authentication
to.photo uses Basic Auth to allow access to the API. To get new Basic Auth Credentials contact your personal Key Account Manager.
to.photo expects for the Basic Auth to be included in all API requests to the server in a header that looks like the following:
Authorization: yourkeyhere
The supplied token has to match the Portal and Mandator.
Orders
Resource
The order resource along with its subresources is the central resource of to.photo. Its parameters are listed in the following table. Each API-function always accepts or returns a complete orderstructure. Depending on the function some parameters may be omitted (see specific documentation of the functions)
| Parameter | Type | Originating Role | Description |
|---|---|---|---|
| version | String | S,C,M | As of the time of writing, always 1.0 |
| orderId | long | S | Unique id of this resource. Always ands with 0. The up to 9 possible subcarts fill the last digit |
| orderdate | long | C (or S if not given) | Unix timestamp of the order's date |
| mandator | int | C | The mandator given by the to.photo admin. See Portal / Mandator |
| portal | int | C | The portal given by the to.photo admin. See Portal / Mandator |
| client | client | C | Optional. See Client for more details |
| status | string | S | See Status for more details |
| statusHistory | array | S | Array of StatusEntry-subresources. See StatusEntry for more details |
| customer | customer | C | See Customer for more details |
| projects | array | C | Array of Project-subresources. See Project for more details |
| bunches | array | C | Array of Bunch-subresources. See Bunch for more details |
| payload | array | C | Array of Payload-subresources. See Payload for more details |
| cart | cart | S | See Cart for more details |
| payment | payment | M | See Payment for more details |
Status
An order can have multiple status. Some status require or need an explicit acknowledge action, because they may lead to additional steps on mandator side (e.g. signal shipment to external shop system).
| Name | Auto-Acknowledged | Description |
|---|---|---|
| Temporary | Y | The order is in a creational state. It hasn't been ordered in a legal manner yet. Customer data and payment-information may be added |
| Transferred | Y | The order's payload (binary data, images, etc.) has been finally transferred. Processing may start now |
| New | Y | Intermediate state. Ready to be further processed. |
| Enqueued | Y | The order has been enqueued for processing and exporting |
| Exporting | Y | The order is actively processing and the output will be generated by the producer (e.g. written to disk or uploaded to another server) |
| Exported | Y | The order has been exported |
| Producing | Y | The order has been picked up by the producer and will be produced somewhen in the near future |
| Produced | N | The order has been succesfully produced. |
| Shipped | N | The order has been handed to the freight forwarder |
| Delivered | Y | The order has been handed over to the user |
| Failed | N | An exception occured while processing the order. Additional information maybe found via the StatusHistory |
| Test | Y | The order is for testing purposes and won't be charged or physically produced |
| Canceled | Y | The order is canceled and won't be processed any further |
Subresources
Subresources only 'live' within their parent order resource.
Client
The client subresource describes the used client (Handheld, Desktop-App ...). This may be important in some cases to interpret the submitted data in a special manner.
| Parameter | Type | Originating Role | Description |
|---|---|---|---|
| type | string | C | May be one of APP, Desktop, Web |
| device | Device | C | See Device for more details |
| version | strin | C | Any string describing the version of the software client |
Device
| Parameter | Type | Originating Role | Description |
|---|---|---|---|
| model | string | C | string describing the model. For example Apple iPhone 6S |
| device | Device | C | string describing the os. For example iOS 11.3 |
StatusEntry
StatusEntry JSON
{
"acknowledged": true,
"date": "1525505632181",
"status": "Temporary"
}
| Parameter | Type | Originating Role | Description |
|---|---|---|---|
| status | string | S | See Status for mode details |
| date | long | S | Unix timestamp of this status effective date |
| acknowledged | bool | S | Has this status already been acknowledged (automatically or manually) |
| metadata | map | S | Optional metadata in a free key-value manner (e.g. tracking numbers) |
Customer
Customer and Address JSON
"customer": {
"billingaddress": {
"city": "Berlin",
"country": "DE",
"firstname": "Max",
"lastname": "Mustermann",
"street": "Musterstraße 33",
"zipcode": "12587"
},
"deliveryaddress": {
"city": "Berlin",
"country": "DE",
"firstname": "Gunda",
"lastname": "Gaukelei",
"street": "Schloß 666",
"zipcode": "12587"
},
"email": "m.mustermann@example.com"
}
The Customer consists of two separate addresses for billing and delivery along with a separate email-address.
| Parameter | Type | Originating Role | Description |
|---|---|---|---|
| billingaddress | address | C | See Address for more details |
| deliveryaddress | address | C | See Address for more details |
| string | C | The customer's email-address |
Address
The attributes have the same meaning as in other customer or address related systems. The following table therefore does only provide some extra details on specific attributes.
| Parameter | Type | Description |
|---|---|---|
| country | string | Must be provided as ISO 3166-1 ALPHA-2 |
Project
Project and Processor JSON
{
"count": 1,
"identifier": "custom1",
"title": "Zaubertasse mit pers\u00f6nlichem Foto zum selbst gestalten",
"processor": {
"identifier": "photo.to.amazonmarketplace.AmazonStandardCupProcessor",
"metadata": {
"passthrough": "true",
"sku": "14621100"
}
}
}
A Project describes one logical unit in the domain of the mandator (e.g. one series of photos of a specific event). Projects are a preliminary form of subcart-items and are evaluated according to the given meta-information and processors.
| Parameter | Type | Originating Role | Description |
|---|---|---|---|
| count | number | C | Desired occurence of this project. While the final products are determined by the processor. Their counts are multiplied with this project count |
| identifier | string | M | An unique identifier of this project which is used throughout this order |
| title | string | M (indirect C) | A description to be used as a human readable explanation |
| processor | processor | M (indirect C) | See Processor for more details |
Processor
A Processor describes the server-side implementation, which analyses a project's data and determines and generates the final products. While standard implementations are existing, specific domain implementations are often needed.
| Parameter | Type | Description |
|---|---|---|
| identifier | string | Identifier of the processor. Currently the full qualified classname of the Java class. May be extended in the future to other schemes. |
| metadata | map | Optional metadata in a free key-value manner (e.g. feature flags, color schemes, ...) |
Bunch
Bunch and BunchItem JSON
{
"project": "custom1",
"items": [
{
"type": "Payload",
"mimetype": "application/zip",
"reference": "custom1.zip",
"metadata": {
"main": true
}
}
]
}
A Bunch describes all items which belong to a project. The Processor will use the bunches to decide which product he will create. Multiple bunches may belong to a project. They represent one logical part of a project. In case of a photo book the page count could be determined based on the count and variety of the bunches and it's BunchItems
| Parameter | Type | Originating Role | Description |
|---|---|---|---|
| project | string | M | Identifier of the project this bunch belongs to |
| items | array | M | Array of BunchItems-subresources. See BunchItem for more details |
BunchItem
A BunchItem is a subpart of a Bunch. While one BunchItem could consist of a photograph, another could add a title string or some cliparts to be rendered ontop of the photograph. For binary data BunchItems just "link" to items of Payload. They may reference to network content as well (see type parameter), which has to be downloaded upon processing.
| Parameter | Type | Originating Role | Description |
|---|---|---|---|
| type | string | M | Describes the type of this item. May be one of 'Payload', 'Url' or (direct) 'Text' |
| mimetype | string | M | Must be provided as RFC6838 |
| reference | string | M | The 'body' of this item. Describes filename, url or content depending on the type parameter. |
| metadata | map | M | Optional metadata in a free key-value manner (e.g. tags, descriptors, significance) |
Payload
Payload JSON
{
"mimetype": "application/zip",
"name": "custom1.zip"
}
A Payload describes one file in the finally posted zip file. In difference to a BunchItems a Payload has no direct connection to a Project. This decoupling enables shared resources. As duplicate filenames within a zip file are not allowd there won't be 2 Payloads with the same name.
| Parameter | Type | Originating Role | Description |
|---|---|---|---|
| mimetype | string | M | Must be provided as RFC6838 |
| name | string | M | The file name |
Cart
Cart and Subcart JSON
{
"subcarts": [
{
"orderId": 811,
"paymentOrderId": "333-1111111-2222222",
"producer": "Allcop",
"producerOrderId": "123456",
"producerOrderUniqueIdentifier": "944400123456",
"qos": "Standard",
"shipping": 3450,
"items": [
{
"count": 1,
"price": 14230,
"processorIndex": 0,
"project": "custom1",
"sku": "14621100"
}
],
"voucher": {
"code": "AMZNMutti",
"description": "Amazon Gutschein",
"value": 7530
}
}
]
}
A Cart encapsulate one or more Subcarts. In the latter case multiple producers are involved who ship their goods separately to the customer. Therefore each producer or even more specific each producer's place of production leads to a separate Subcart. Each Subcart is treated as a separate suborder, while the Payment applies to all of them. Since the mandator is responsible for price management shipping has to be provided by the mandator and not by the server.
Subcart
| Parameter | Type | Originating Role | Description |
|---|---|---|---|
| orderId | number | S | Unique id |
| paymentOrderId | string | M | Domain and mandator specific identifier. May be mapped to an external shopsystem (Shopify, Amazon, Ebay) |
| producer | string | S | The producer. Currently only Allcop |
| producerOrderId | string | S | The unique id in the producers name- and numberingspace |
| producerOrderUniqueIdentifier | string | S | Optional identifier for special mappings (used in Allcop status files) |
| qos | string | M | Quality of service. One of Standard or Express |
| shipping | number | M | Shipping costs in tenth of minor units |
| items | array | S | Array of `SubcartItem'-subresources. See SubcartItem for more details |
| voucher | voucher | M | See Voucher for mode details |
SubcartItem
SubcartItem JSON
{
"count": 1,
"price": 14230,
"processorIndex": 0,
"project": "custom1",
"sku": "14621100"
}
A SubcartItem describes cart item with the same meaning as in related cart / checkout systems.
| Parameter | Type | Originating Role | Description |
|---|---|---|---|
| count | number | S | Count of this item |
| price | number | M | Item price in tenth of minor units |
| processorIndex | number | S | Index of this item within its project / processor's space. The processor determines n products which lead to separate SubcartItems. This determination is fixed and reproducable. To identify the items later on the incrementing index is assigned in order of appearance. |
| project | string | S | Reference to the project's identifier |
| sku | string | S | Stock keeping unit which donates a specific product (e.g. 20 page, 10x10cm, softcover, pure photobook) |
Voucher
Voucher JSON
{
"code": "AMZNMutti",
"description": "Amazon Gutschein",
"value": 7530
}
A Voucher describes the discount to be applied to a Subcart.
| Parameter | Type | Originating Role | Description |
|---|---|---|---|
| code | string | C | The code the user entered during the checkout |
| description | string | M | Human readable description. May be printed on the invoice |
| value | string | M | Absolute amount of discount in tenth of minor units |
Payment
Payment JSON
{
"provider": "Amazon",
"metadata": {
"orderid": "333-2222222-111111"
}
}
The Payment contains all information which refer to the order's payment. If something like authorize and capture is used, the involved ids and receipts are saved within this node.
| Parameter | Type | Originating Role | Description |
|---|---|---|---|
| provider | string | M | The type of payment. Currently onle Amazon is supported. Advance, Invoice, Paypal, Paypal Authorize and Capture and Stripe are planned as well. |
| metadata | map | M | Optional metadata in a free key-value manner (e.g. ids, tokens, flags) |
Create Order
Request
Path: POST /v1/orders
Headers: Accept: application/json
Headers: Content-Type: application/json
{
"mandator": 1,
"portal": 1000,
"version": "1.0",
"projects": [
{
"title": "Schlüsselanhänger aus Acryl mit persönlichem Foto zum selbst gestalten",
"count": 1,
"identifier": "custom1",
"processor": {
"identifier": "photo.to.amazonmarketplace.AmazonPhotoKeychainProcessor",
"metadata": {
"sku": "14560000"
}
},
}
],
"bunches": [
{
"project": "custom1",
"items": [
{
"type": "Payload",
"reference": "custom1.zip",
"mimetype": "application/zip"
}
]
}
],
"payload": [
{
"name": "custom1.zip",
"mimetype": "application/zip"
}
]
}
Response
Headers: Content-Type: application/json
{
"orderId": 1230,
"status": "Temporary",
"mandator": 0,
"portal": 1000,
"version": "1.0",
"orderdate": 0,
"projects": [
{
"title": "Schlüsselanhänger aus Acryl mit persönlichem Foto zum selbst gestalten",
"count": 1,
"identifier": "custom1",
"processor": {
"identifier": "photo.to.amazonmarketplace.AmazonPhotoKeychainProcessor",
"metadata": {
"sku": "14560000"
}
},
}
],
"cart": {
"subcarts": [
{
"orderId": 1231,
"paymentOrderId": null,
"producer": "Allcop",
"producerOrderId": null,
"producerOrderUniqueIdentifier": null,
"items": [
{
"sku": "14560000",
"count": 1,
"price": 0,
"description": null,
"project": "custom1",
"processorIndex": 0
}
],
"shipping": 0,
"voucher": null,
"qos": "Standard"
}
]
},
"bunches": [
{
"project": "custom1",
"items": [
{
"type": "Payload",
"reference": "custom1.zip",
"mimetype": "application/zip",
"metadata": null
}
]
}
],
"payload": [
{
"name": "custom1.zip",
"mimetype": "application/zip",
"metadata": null
}
],
"statusHistory": [
{
"status": "Temporary",
"date": 1526583658842,
"acknowledged": true,
"metadata": null
}
]
}
Use the order resource to initialise a new order. Upon initialization it is not necessary to provide all details of an order. All of the other details are added during an orders lifecycle. The following table lists all the mandatory parameter for this request.
Payload params
| Parameter | Description |
|---|---|
| mandator | Needed for proper authorization |
| portal | Needed for proper authorization |
| projects | Needed for segmentation |
| bunches | Needed for segmentation |
| payload | Needed for segmentation |
Error Response
Error Response
{
"status": "UNPROCESSABLE_ENTITY",
"timestamp": "2018-01-01 12:34:56.789",
"message": "More than 9 Subcarts are not allowed",
"debugMessage": "More than 9 Subcarts are not allowed"
}
422 UNPROCESSABLE ENTITY
The order would lead to more then 9 Subcarts.
Checkout Order
Request (JSON same as in response)
Path: POST /v1/orders/:orderid/checkout
Headers: Accept: application/json
Headers: Content-Type: application/json
{
"orderId": 1230,
"status": "Temporary",
"version": "1.0",
"mandator": 1,
"portal": 1000,
"orderdate": 1524845291000,
"payment": {
"provider": "Amazon",
"metadata": {
"orderid": "111-22222222-3333333"
}
},
"customer": {
"email": "mm@example.com",
"telephone": null,
"telefax": null,
"billingaddress": {
"title": "Herr",
"firstname": "Max",
"lastname": "Mustermann",
"company": "to.photo",
"street": "Musterstrasse",
"housenumber": "10",
"zipcode": "12345",
"city": "Berlin",
"country": "DE"
},
"deliveryaddress": {
"title": "Herr",
"firstname": "Max",
"lastname": "Mustermann",
"company": "to.photo",
"street": "Musterstrasse",
"housenumber": "10",
"zipcode": "12345",
"city": "Berlin",
"country": "DE"
}
},
"projects": [
{
"title": "Schlüsselanhänger aus Acryl mit persönlichem Foto zum selbst gestalten",
"count": 1,
"identifier": "custom1",
"processor": {
"identifier": "photo.to.amazonmarketplace.AmazonPhotoKeychainProcessor",
"metadata": {
"sku": "14560000"
}
},
"outputs": null
}
],
"cart": {
"subcarts": [
{
"orderId": 1231,
"paymentOrderId": "111-22222222-3333333",
"producer": "Allcop",
"producerOrderId": null,
"producerOrderUniqueIdentifier": null,
"items": [
{
"sku": "14560000",
"count": 1,
"price": 5950,
"description": null,
"project": "custom1",
"processorIndex": 0
}
],
"shipping": 3450,
"voucher": {
"code": "Gutschein",
"description": "Amazon Gutschein",
"value": 1790
},
"qos": "Standard"
}
]
},
"bunches": [
{
"project": "custom1",
"items": [
{
"type": "Payload",
"reference": "custom1.zip",
"mimetype": "application/zip",
"metadata": null
}
]
}
],
"payload": [
{
"name": "custom1.zip",
"mimetype": "application/zip",
"metadata": null
}
],
"statusHistory": [
{
"status": "Temporary",
"date": 1526583658842,
"acknowledged": true,
"metadata": null
}
]
}
After initialization you will need to enrich the order with checkout data. This contains all data collected in the checkout process.
URL params
| Parameter | Type | Description |
|---|---|---|
| orderId | number | orderId to be updated / checked out |
Payload params
| Parameter | Description |
|---|---|
| payment | Paymentdata which was collected during the checkout process |
| customer | Customer which was collected during the checkout process |
| cart | Enriched with prices, payment-ids, vouchers ... |
Error Response
Error Responses
{
"status": "NOT_FOUND",
"timestamp": "2018-01-01 12:34:56.789",
"message": "Order not found",
"debugMessage": "Order not found"
}
404 NOT FOUND
No order found
{
"status": "CONFLICT",
"timestamp": "2018-01-01 12:34:56.789",
"message": "Carts are different",
"debugMessage": "Carts are different"
}
409 CONFLICT
The order is not temporary (anymore) and can not be changed.
or:
The carts are different, please get the actual cart from order get.
Finalize Order
Request
Path: POST /v1/orders/:orderid/data
Headers: Accept: application/zip
Headers: Content-Type: multipart/mixed
Response
Headers: Content-Type: application/json
{
"orderId": 1230,
"status": "Enqueued",
"version": "1.0",
"mandator": 1,
"portal": 1000,
"orderdate": 1524845291000,
"payment": {
"provider": "Amazon",
"metadata": {
"orderid": "111-22222222-3333333"
}
},
"customer": {
"email": "mm@example.com",
"telephone": null,
"telefax": null,
"billingaddress": {
"title": "Herr",
"firstname": "Max",
"lastname": "Mustermann",
"company": "to.photo",
"street": "Musterstrasse",
"housenumber": "10",
"zipcode": "12345",
"city": "Berlin",
"country": "DE"
},
"deliveryaddress": {
"title": "Herr",
"firstname": "Max",
"lastname": "Mustermann",
"company": "to.photo",
"street": "Musterstrasse",
"housenumber": "10",
"zipcode": "12345",
"city": "Berlin",
"country": "DE"
}
},
"projects": [
{
"title": "Schlüsselanhänger aus Acryl mit persönlichem Foto zum selbst gestalten",
"count": 1,
"identifier": "custom1",
"processor": {
"identifier": "photo.to.amazonmarketplace.AmazonPhotoKeychainProcessor",
"metadata": {
"sku": "14560000"
}
},
"outputs": null
}
],
"cart": {
"subcarts": [
{
"orderId": 1231,
"paymentOrderId": "111-22222222-3333333",
"producer": "Allcop",
"producerOrderId": "600556",
"producerOrderUniqueIdentifier": null,
"items": [
{
"sku": "14560000",
"count": 1,
"price": 5950,
"description": null,
"project": "custom1",
"processorIndex": 0
}
],
"shipping": 3450,
"voucher": {
"code": "Gutschein",
"description": "Amazon Gutschein",
"value": 1790
},
"qos": "Standard"
}
]
},
"bunches": [
{
"project": "custom1",
"items": [
{
"type": "Payload",
"reference": "custom1.zip",
"mimetype": "application/zip",
"metadata": null
}
]
}
],
"payload": [
{
"name": "custom1.zip",
"mimetype": "application/zip",
"metadata": null
}
],
"statusHistory": [
{
"status": "Temporary",
"date": 1526583658842,
"acknowledged": true,
"metadata": null
},
{
"status": "Transferred",
"date": 1526583814113,
"acknowledged": true,
"metadata": null
},
{
"status": "New",
"date": 1526583814115,
"acknowledged": true,
"metadata": null
},
{
"status": "Enqueued",
"date": 1526583814210,
"acknowledged": true,
"metadata": null
}
]
}
After all you need to finalize the order and send it to production.
Therefore you send all the payload image data, packaged as a ZIP archive, to the server. The successful upload will trigger the production process, no further call is needed.
URL Params
| Parameter | Type | Description |
|---|---|---|
| orderId | number | orderId to be loaded |
Payload params
| Parameter | Type | Description |
|---|---|---|
| file | file | the zip file containing all of the payload-items |
Error Response
Error Responses
{
"status": "NOT_FOUND",
"timestamp": "2018-01-01 12:34:56.789",
"message": "Order not found",
"debugMessage": "Order not found"
}
404 NOT FOUND
No order found
{
"status": "CONFLICT",
"timestamp": "2018-01-01 12:34:56.789",
"message": "Only temporary orders can receive data",
"debugMessage": "Only temporary orders can receive data"
}
409 CONFLICT
The order is not temporary (anymore) and can not be changed.
Order Status Acknowledge
Request
Path: PUT /v1/orders/:orderid/status
Headers: Accept: application/json
Headers: Content-Type: application/json
{
"status": "Shipped",
"date": 1526583814210,
"acknowledged": true,
"metadata": {
"tracking": "343242342ddfa234243"
}
}
Response
Headers: Content-Type: application/json
{
"status": "Shipped",
"date": 1526583814210,
"acknowledged": true,
"metadata": {
"tracking": "343242342ddfa234243"
}
}
Acknowledge an order status as processed.
URL Params
| Parameter | Type | Description |
|---|---|---|
| orderid | long | The ID of the order which status to acknowledge |
Payload params
The statusentry to be acknowledged
Error Response
Error Response
{
"status": "NOT_FOUND",
"timestamp": "2018-01-01 12:34:56.789",
"message": "Order not found",
"debugMessage": "Order not found"
}
404 NOT FOUND
No order found
{
"status": "CONFLICT",
"timestamp": "2018-01-01 12:34:56.789",
"message": "Entry can not be acknowledged",
"debugMessage": "Entry can not be acknowledged"
}
409 CONFLICT
The status entry can not be acknowledged
Read Order
Request
Path: GET /v1/orders/:orderid
Headers: Accept: application/json
Headers: Content-Type: application/json
Response
Headers: Content-Type: application/json
{
"orderId": 1230,
"status": "Enqueued",
"version": "1.0",
"mandator": 1,
"portal": 1000,
"orderdate": 1524845291000,
"payment": {
"provider": "Amazon",
"metadata": {
"orderid": "111-22222222-3333333"
}
},
"customer": {
"email": "mm@example.com",
"telephone": null,
"telefax": null,
"billingaddress": {
"title": "Herr",
"firstname": "Max",
"lastname": "Mustermann",
"company": "to.photo",
"street": "Musterstrasse",
"housenumber": "10",
"zipcode": "12345",
"city": "Berlin",
"country": "DE"
},
"deliveryaddress": {
"title": "Herr",
"firstname": "Max",
"lastname": "Mustermann",
"company": "to.photo",
"street": "Musterstrasse",
"housenumber": "10",
"zipcode": "12345",
"city": "Berlin",
"country": "DE"
}
},
"projects": [
{
"title": "Schlüsselanhänger aus Acryl mit persönlichem Foto zum selbst gestalten",
"count": 1,
"identifier": "custom1",
"processor": {
"identifier": "photo.to.amazonmarketplace.AmazonPhotoKeychainProcessor",
"metadata": {
"sku": "14560000"
}
},
"outputs": null
}
],
"cart": {
"subcarts": [
{
"orderId": 1231,
"paymentOrderId": "111-22222222-3333333",
"producer": "Allcop",
"producerOrderId": "600556",
"producerOrderUniqueIdentifier": null,
"items": [
{
"sku": "14560000",
"count": 1,
"price": 5950,
"description": null,
"project": "custom1",
"processorIndex": 0
}
],
"shipping": 3450,
"voucher": {
"code": "Gutschein",
"description": "Amazon Gutschein",
"value": 1790
},
"qos": "Standard"
}
]
},
"bunches": [
{
"project": "custom1",
"items": [
{
"type": "Payload",
"reference": "custom1.zip",
"mimetype": "application/zip",
"metadata": null
}
]
}
],
"payload": [
{
"name": "custom1.zip",
"mimetype": "application/zip",
"metadata": null
}
],
"statusHistory": [
{
"status": "Temporary",
"date": 1526583658842,
"acknowledged": true,
"metadata": null
},
{
"status": "Transferred",
"date": 1526583814113,
"acknowledged": true,
"metadata": null
},
{
"status": "New",
"date": 1526583814115,
"acknowledged": true,
"metadata": null
},
{
"status": "Enqueued",
"date": 1526583814210,
"acknowledged": true,
"metadata": null
}
]
}
Load an order
URL params
| Parameter | Type | Description |
|---|---|---|
| orderId | number | orderId to be loaded |
Error Response
Error Response
{
"status": "NOT_FOUND",
"timestamp": "2018-01-01 12:34:56.789",
"message": "Order not found",
"debugMessage": "Order not found"
}
404 NOT FOUND
No order found
{
"status": "GONE",
"timestamp": "2018-01-01 12:34:56.789",
"message": "Order is canceled",
"debugMessage": "Order is canceled"
}
410 GONE
The Order is already canceled
Cancel Order
Request
Path: DELETE /v1/orders/:orderid
Headers: Accept: application/json
Headers: Content-Type: application/json
Response
Headers: Content-Type: none
For some reason you maybe want to cancel your shortly placed order.
URL Params
| Parameter | Type | Description |
|---|---|---|
| orderid | long | The ID of the order which should be canceled |
Success Response
Code
204
Content
No Content
Error Response
Error Response
{
"status": "NOT_FOUND",
"timestamp": "2018-01-01 12:34:56.789",
"message": "Order not found",
"debugMessage": "Order not found"
}
404 NOT FOUND
No order found
{
"status": "CONFLICT",
"timestamp": "2018-01-01 12:34:56.789",
"message": "Only temporary orders can receive data",
"debugMessage": "Only temporary orders can receive data"
}
409 CONFLICT
The order is not temporary (anymore) and can not be changed.
{
"status": "GONE",
"timestamp": "2018-01-01 12:34:56.789",
"message": "Order is canceled",
"debugMessage": "Order is canceled"
}
410 GONE
The Order is already canceled
Portals
Resource
Unacklowdged Orders
Request
Path: GET /v1/portals/:portalid/orders/unacknowledged
Headers: Accept: application/json
Response
Headers: Content-Type: application/json
[{
"orderId": "270",
"bunches": [
{
"items": [
{
"mimetype": "application/zip",
"reference": "custom1.zip",
"type": "Payload"
}
],
"project": "custom1"
}
],
"cart": {
"subcarts": [
{
"items": [
{
"count": 1,
"price": 11900,
"processorIndex": 0,
"project": "custom1",
"sku": "14631000"
}
],
"orderId": 123,
"paymentOrderId": "testorder",
"producer": "Allcop",
"producerOrderId": 123,
"producerOrderUniqueIdentifier": "94440000123",
"shipping": 3450
}
]
},
"customer": {
"billingaddress": {
"city": "Musterstadt",
"country": "DE",
"firstname": "Max",
"lastname": "Mustermann",
"street": "Musterstrasse 14",
"zipcode": "12345"
},
"deliveryaddress": {
"city": "Musterstadt",
"country": "DE",
"firstname": "Max",
"lastname": "Mustermann",
"street": "Musterstrasse 14",
"zipcode": "12345"
},
"email": "test@test.test"
},
"mandator": 0,
"orderdate": 1518800013000,
"payload": [
{
"mimetype": "application/zip",
"name": "custom1.zip"
}
],
"portal": 1000,
"projects": [
{
"count": 1,
"identifier": "custom1",
"processor": {
"identifier": "photo.to.amazonmarketplace.AmazonStandardCupProcessor",
"metadata": {
"sku": "14631000"
}
},
"title": "Tasse (14631000)"
}
],
"status": "Enqueued",
"statusHistory": [
{
"date": 1518806466415,
"status": "Shipped",
"acknowledged": false
}
]
}]
Load this portals orders with unacknowledged statuses.
URL Params
portalId=[integer]
Error Response
no special error responses
Unacklowdged Orders by Status
Request
Path: GET /v1/portals/:portalid/orders/status/:status/unacknowledged
Headers: Accept: application/json
Response
Headers: Content-Type: application/json
Load this portals orders with unacknowledged statuses by specific status.
Content-Type
application/json
URL Params
portalId=[integer]
status=[string]
[{
"orderId": "270",
"bunches": [
{
"items": [
{
"mimetype": "application/zip",
"reference": "custom1.zip",
"type": "Payload"
}
],
"project": "custom1"
}
],
"cart": {
"subcarts": [
{
"items": [
{
"count": 1,
"price": 11900,
"processorIndex": 0,
"project": "custom1",
"sku": "14631000"
}
],
"orderId": 123,
"paymentOrderId": "testorder",
"producer": "Allcop",
"producerOrderId": 123,
"producerOrderUniqueIdentifier": "94440000123",
"shipping": 3450
}
]
},
"customer": {
"billingaddress": {
"city": "Musterstadt",
"country": "DE",
"firstname": "Max",
"lastname": "Mustermann",
"street": "Musterstrasse 14",
"zipcode": "12345"
},
"deliveryaddress": {
"city": "Musterstadt",
"country": "DE",
"firstname": "Max",
"lastname": "Mustermann",
"street": "Musterstrasse 14",
"zipcode": "12345"
},
"email": "test@test.test"
},
"mandator": 0,
"orderdate": 1518800013000,
"payload": [
{
"mimetype": "application/zip",
"name": "custom1.zip"
}
],
"portal": 1000,
"projects": [
{
"count": 1,
"identifier": "custom1",
"processor": {
"identifier": "photo.to.amazonmarketplace.AmazonStandardCupProcessor",
"metadata": {
"sku": "14631000"
}
},
"title": "Tasse (14631000)"
}
],
"status": "Enqueued",
"statusHistory": [
{
"date": 1518806466415,
"status": "Shipped",
"acknowledged": false
}
]
}]
´´´
### Error Response
_no special error responses_
Errors
Error Response
an example Error Object
{
"status": "GONE",
"timestamp": "2018-01-01 12:34:56.789",
"message": "Order is canceled",
"debugMessage": "Order is canceled"
}
An Error Response consists of an HTTP status code and an Error Object.
The HTTP status codes are used to categorize the Errors in the "standard" manner, so 4xx for clientside/request Errors and 5xx for serverside Errors. For further information see the List of HTTP status codes on Wikipedia.
The additional Error Object gives you more information about the Error. Usually the message field (and if applicable the debug message filed) will tell you more about the Errors cause.
Standard Error Responses
| HTTP Status | Description | Meaning |
|---|---|---|
| 400 | Bad Request | Your request is invalid. |
| 401 | Unauthorized | Your API key is wrong. |
| 403 | Forbidden | You tried to access a ressource which wasn't made for your eyes, sorry NSA! |
| 404 | Not Found | The specified ressource could not be found. |
| 405 | Method Not Allowed | You tried to access a ressource with an invalid method. |
| 406 | Not Acceptable | You requested a format that isn't json. |
| 410 | Gone | The ressource requested has been removed from our servers. |
| 500 | Internal Server Error | We had an unexpected problem with our server. Try again later. The problem is reported to an Administrator immediately. |
| 503 | Service Unavailable | We're temporarily offline for maintenance. Please try again later. |