Fulfillment Resource

Introduction

Fulfillments in the Open Publishing ecosystem are task or orders for print and/or shippment to an external logistics partner.

Example URL

https://api.openpublishing.com/resource/v3/fulfillments/[ID]

Allowed methods: GET, POST, PUT.

List fulfillments:

https://api.openpublishing.com/resource/v3/fulfillments

Search for all fulfillments of order:

https://api.openpublishing.com/resource/v3/fulfillments?order_id=[ORDER-ID]

Search for all fulfillments of business partner:

https://api.openpublishing.com/resource/v3/fulfillments?business_partner_id=[BUSINESS-PARTNER-ID]

Fields

Business Partner

business_partner Subobject contains link to business partner to which the fulfillment object is linked to. The object itself contains the _id of the business partner and their screenname.

Products

The products field contains a list of shipped products. Each element contains the ean of the shipped product, if available, the quantity of the to-be-shipped items and a link to a product. The product itself is a dict containing an _id and the title of the product.

Shipping information

The shipping field contains a list of shipping events related to the fulfillment.

provider is the parcel service. Values can be dhl, fedex or ups. tracking_id is the package tracking number provided by the parcel service. shipped_at contains the unix timestamp when the parcel was shipped.

The shipping status is transmitted in the field status and contains the values new (hasn't been shipped yet), shipped (is on the way to the recipient) or delivered (has been delivered to the recipient).

Shipping address information

first_name, last_name, line2, line3 street, state, zip, city contains the fields of the shipping address. country contains the 2-character ISO code of the country. email and phone refer to contact information to the recipient.

Processed

processed is a boolean value indicating if the fullfillment was already processed by OP - i.e. transmitted to the logistics partner.

Realm

realm is the Open Publishing terminology for tenant. It contains a dict with _id and name and screenname.

Example JSON

{
   "_id": 1,
   "business_partner": {
      "_id": 128,
      "screenname": "Julius Mittenzwei"
   },
   "city": "München",
   "country": "DE",
   "email": "example@example.com",
   "first_name": "John Doe",
   "last_name": "Mittenzwei",
   "line2": "Example LLC",
   "line3": null,
   "order": {
      "_id": 1633388953
   },
   "phone_number": null,
   "processed": true,
   "products":
      [
         {
            "ean": "9783638627177",
            "product": {
               "_id": 190,
               "title": "Rezension zu: Schönbach, Klaus - Zeitungen in den Neunzigern: Faktoren ihres Erfolgs"
            },
            "quantity": 1
         }
      ],
   "realm": {
      "_id": 23,
      "name": "testpublisher",
      "screenname": "Test Publisher"
   },
   "shipping":
      [
         {
            "provider": "dhl",
            "shipped_at": 1633423692,
            "status": "shipped",
            "tracking_id": "12345"
         }
      ],
   "state": null,
   "street": "Marienstr. 17",
   "zip": "80331"
}

Logging

Each fulfillment has a logging endpoint to post log entries. URL:

https://api.openpublishing.com/resource/v3/fulfillments/[ID]/log
https://api.openpublishing.com/resource/v3/fulfillments/[ID]/log/[ID]

Allowed methods: GET, POST.

Example JSON:

{
    "_id": 22,
    "created": 1641134450,
    "message": "Something happened",
    "type": "error"
}

Files

Additionally files associated with a fulfillment may be stored to the following endpoint. URL:

https://api.openpublishing.com/resource/v3/fulfillments/[ID]/files
https://api.openpublishing.com/resource/v3/fulfillments/[ID]/files/[ID]

For adding files, POST to above URL with an multipart/form encoded body with the following parameters:

file the file itself
type of the file. An arbitrary string, e.g. EDItXReturnsReport.

The URL also supports GET for retrieving information about uploaded files. It contains a JSON with the following fields:

file_name : File name of uploaded file.
file_size : File size in bytes.
mime_type : mime type of file, e.g. application\/xml.
href : URL to download file.
labels : labels of file - at the moment read only.
properties : Properties of file - at the moment read only.
sha1 : SHA1 checksum of uploaded file..
timestamp : Unix timestamp when file was uploaded.
type : type of the file. An arbitrary string, e.g. EDItXReturnsReport.