Fulfillment Service API

Fulfillment Object

A Fulfillment Object models a process to deliver products to a customer during a self-checkout.

{
  "state": "allocating",
  "lineItems": [
    { "id": "7b725216-6887-11ea-b541-68f7286a148f", "sku": "sku-1", "amount": 2, "scannedCode": "..."},
    { "id": "a9389782-6887-11ea-8d3d-68f7286a148f", "sku": "sku-2", "amount": 1, "scannedCode": "..."}
  ]
  "links": {
    "fulfillment": { "href": "/a-project/checkout/fulfillments/6697512a-6887-11ea-965e-68f7286a148f" }
  }
}

Property	type	Description
state	string	State of the Fulfillment (see below)
lineItems	LineItem[]	Array of Line Items (see below)
links	Links	Link object containing a link to the corresponding fulfillment in the Snabble platform
error	Error[]	Array of Error Objects (see below)

Line Item

Property	type	Description
id	string	Identifier of the Line Item
sku	string	SKU of the product in Snabble
amount	number	Amount to be delivered
scannedCode	string	Code scanned by the customer

Error Object

Property	type	Description
refersTo`	string	ID of the related line item
type	string	Type of the error (ie. outOfStock, other have to be defined)
itemsAvailable	number	Number of available items (in case of low stock)
message	string	An optional error message

Fulfillment State

State	Description
open	A new fulfillment
allocating	Service is currently reserving the products
allocated	Products are reserved and ready to be delivered
processing	Delivering the products
processed	Successfully delivered the products
aborted	Client abort
allocationFailed	Reservation failed
allocationTimedOut	A successful reservation has timed out
failed	Delivery failed

Create A New Fulfillment

Initially the Snabble platform creates a new entity in the service. The state is allocating and the service should reserve the requested amounts or otherwise respond with an appropriate error.

Request

POST /service

{
  "state": "allocating",
  "lineItems": [
    { "id": "7b725216-6887-11ea-b541-68f7286a148f", "sku": "sku-1", "amount": 2, "scannedCode": "..."},
    { "id": "a9389782-6887-11ea-8d3d-68f7286a148f", "sku": "sku-2", "amount": 1, "scannedCode": "..."}
  ]
  "links": {
    "fulfillment": { "href": "/a-project/checkout/fulfillments/6697512a-6887-11ea-965e-68f7286a148f" }
  }
}

Response

201 Created
Location: /service/id/132

{
  "id": "6697512a-6887-11ea-965e-68f7286a148f",
  "state": "allocated",
  "shopID": "123",
  "lineItems": [
    { "id": "7b725216-6887-11ea-b541-68f7286a148f", "sku": "sku-1", "amount": 2, "scannedCode": "..."},
    { "id": "a9389782-6887-11ea-8d3d-68f7286a148f", "sku": "sku-2", "amount": 1, "scannedCode": "..."}
  ]
}

Error Case

In case of an error the service should respond with HTTP Status Code 400 and optionally add an array of error objects to the response.

Error response

400 Bad Request

{
  "id": "6697512a-6887-11ea-965e-68f7286a148f",
  "state": "allocationFailed",
  "shopID": "123",
  "lineItems": [
    { "id": "7b725216-6887-11ea-b541-68f7286a148f", "sku": "sku-1", "amount": 2, "scannedCode": "..."},
    { "id": "a9389782-6887-11ea-8d3d-68f7286a148f", "sku": "sku-2", "amount": 1, "scannedCode": "..."}
  ],
  "errors": [
    { "refersTo": "7b725216-6887-11ea-b541-68f7286a148f", "type": "outOfStock", "itemsAvailable": 1, "message": "..." }
  ]
}

Update A Fulfillment

After the payment is successfully processed by Snabble, the platform updates the state of the entity with the state processing. The service triggers the delivery by the vending machine.

PUT /service

{
  "state": "processing",
  "lineItems": [
    { "id": "7b725216-6887-11ea-b541-68f7286a148f", "sku": "sku-1", "amount": 2, "scannedCode": "..."},
    { "id": "a9389782-6887-11ea-8d3d-68f7286a148f", "sku": "sku-2", "amount": 1, "scannedCode": "..."}
  ]
  "links": {
    "fulfillment": { "href": "/a-project/checkout/fulfillments/6697512a-6887-11ea-965e-68f7286a148f" }
  }
}

Response

201 Created
Location: /service/id/132

{
  "id": "6697512a-6887-11ea-965e-68f7286a148f",
  "state": "processed",
  "shopID": "123",
  "lineItems": [
    { "id": "7b725216-6887-11ea-b541-68f7286a148f", "sku": "sku-1", "amount": 2, "scannedCode": "..."},
    { "id": "a9389782-6887-11ea-8d3d-68f7286a148f", "sku": "sku-2", "amount": 1, "scannedCode": "..."}
  ]
}

The service might also respond with a fulfillment in state processing. Then it has to update the fulfillment if it finished the delivery.

The service might also update the fulfillment with error states as described above.