Handover Jobs

A handover job represents the handover of an order to the end consumer or parcel service provider and provides all the necessary information.

Despite general information like the order date, tenant order id or a reference to the corresponding facility a handover job carries handover relevant information like the handover channel (DELIVERY: will it be handed over to a parcel service provider or COLLECT: will it be handed over to the end customer) or handover job cancel reason (it was not handed over due to a no show of the customer, the order was cancelled, etc.).

Creating a Handover Job

A handover will automatically created when a parcel has changed to status FINISHED while the related Pick Job was in status CLOSED or a pick job has changed to status CLOSED and there is at least one Parcel of the related Shipment that is in status FINISHED.

Alternatively a Handover Job can be created via REST Api

Add a new handoverjob

POSThttps://%%HOST%%//api/handoverjobs

Authorization

Body

carrierLogoUrlstring

The URL to the carrier logo

carrierRefstring

carrierTrackingNumberstring

Tracking number for the created shipment

channel*enum

DELIVERYCOLLECT

customAttributesobject

Attributes that can be added to the handover job. These attributes cannot be used within fulfillment processes, but it could be useful to have the informations carried here.

facilityRef*string

The id of the facility reference.

Example: "Esb20gpHBL94X5NdMp3C"

handoverJobLineItemsarray of HandoverLineItem (object)

loadUnitRefsarray of string

Reference to array of load unit Refs

orderDate*string (date-time)

The date this order was created at the supplying system.

Example: "2020-02-03T08:45:50.525Z"

parcelRefstring

The reference to the parcel.

Example: "2fOge2ZGW54K4TgvDTQw"

pickJobRefstring

The reference to the pickjob for which the handoverjob is assigned to

Example: "ca525716-7208-4a63-a2a6-11274eb37f67-0"

processIdstring

Id of the global process related to this entity. For example used for starting the GDPR process and others.

shipmentRefstring

The reference to the shipment belonging to the handoverjob

Example: "Esb20gpHBL94X5NdMp3C"

shortIdentifierstring

The short identifier of the shipment.

statusHandoverjobStatus (enum)

OPENHANDED_OVEROBSOLETECANCELED

targetTime*string (date-time)

The time the handoverjob is expected to be picked up at the facility.

tenantOrderIdstring

Field can be used as a reference number in foreign systems, for example as a reference to the source system's identifier for this order.

Example: "R456728546"

paidboolean

Indicates if the order is already paid

Example: false

tagsarray of TagReference (object)

Tags can only be set when there is no process related with this handoverJob. Setting processId and tags will lead to an validationError.

stickersarray of Sticker (object)

cancelReasonHandoverJobCancelReason (enum)

CONSUMER_NO_SHOWCONSUMER_REJECTSORDER_CANCELED

invoiceAddressConsumerAddress (object)

recipientAddressConsumerAddress (object)

fullIdentifierstring

An information to identify the recipient

Response

The handoverjob was successfully created. The Location header contains the URL of it.

Body

createdstring (date-time)

The date this entity was created at the platform. This value is generated by the service.

Example: "2020-02-03T08:45:51.525Z"

lastModifiedstring (date-time)

The date this entity was modified last. This value is generated by the service.

Example: "2020-02-03T09:45:51.525Z"

version*integer (int64)

The version of the document to be used in optimistic locking mechanisms.

Example: 42

carrierLogoUrlstring

The URL to the carrier logo

carrierRefstring

carrierTrackingNumberstring

Tracking number for the created shipment

channel*enum

DELIVERYCOLLECT

customAttributesobject

Attributes that can be added to the handover job. These attributes cannot be used within fulfillment processes, but it could be useful to have the informations carried here.

facilityRef*string

The id of the facility reference.

Example: "Esb20gpHBL94X5NdMp3C"

handoverJobLineItemsarray of HandoverLineItem (object)

loadUnitRefsarray of string

Reference to array of load unit Refs

orderDate*string (date-time)

The date this order was created at the supplying system.

Example: "2020-02-03T08:45:50.525Z"

parcelRefstring

The reference to the parcel.

Example: "2fOge2ZGW54K4TgvDTQw"

pickJobRefstring

The reference to the pickjob for which the handoverjob is assigned to

Example: "ca525716-7208-4a63-a2a6-11274eb37f67-0"

processIdstring

Id of the global process related to this entity. For example used for starting the GDPR process and others.

shipmentRefstring

The reference to the shipment belonging to the handoverjob

Example: "Esb20gpHBL94X5NdMp3C"

shortIdentifierstring

The short identifier of the shipment.

statusHandoverjobStatus (enum)

OPENHANDED_OVEROBSOLETECANCELED

targetTime*string (date-time)

The time the handoverjob is expected to be picked up at the facility.

tenantOrderIdstring

Field can be used as a reference number in foreign systems, for example as a reference to the source system's identifier for this order.

Example: "R456728546"

paidboolean

Indicates if the order is already paid

Example: false

tagsarray of TagReference (object)

Tags can only be set when there is no process related with this handoverJob. Setting processId and tags will lead to an validationError.

stickersarray of Sticker (object)

cancelReasonHandoverJobCancelReason (enum)

CONSUMER_NO_SHOWCONSUMER_REJECTSORDER_CANCELED

invoiceAddressConsumerAddress (object)

recipientAddressConsumerAddress (object)

fullIdentifierstring

An information to identify the recipient

anonymizedboolean

Indicates if gdpr related data was anonymized

Example: false

idstring

The id of this handoverjob. It is generated during creation automatically and suits as the primary identifier of the described entity.

Example: "95EWrieX09OmeriXIUbb"

documentsarray of PrintableDocument (object)

stickersarray of Sticker (object)

documentsRefstring

Reference to the documents collection from this entity

carrierKeystring

Key of the carrier that is used for this entity

Request

const response = await fetch('https://%%HOST%%//api/handoverjobs', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "facilityRef": "Esb20gpHBL94X5NdMp3C",
      "targetTime": "2024-09-07T23:26:11.818Z",
      "channel": "DELIVERY",
      "orderDate": "2020-02-03T08:45:50.525Z"
    }),
});
const data = await response.json();

Response

{
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42,
  "carrierLogoUrl": "text",
  "carrierRef": "text",
  "carrierTrackingNumber": "text",
  "channel": "DELIVERY",
  "facilityRef": "Esb20gpHBL94X5NdMp3C",
  "handoverJobLineItems": [
    {
      "article": {
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 0,
        "attributes": [
          {
            "category": "descriptive",
            "key": "%%subtitle%%",
            "priority": 100,
            "value": "585er Gold"
          }
        ]
      },
      "picked": 20,
      "quantity": 21,
      "substituteLineItems": [
        {
          "article": {
            "imageUrl": "text",
            "tenantArticleId": "4711",
            "title": "Cologne Water",
            "weight": 0,
            "attributes": [
              {
                "category": "descriptive",
                "key": "%%subtitle%%",
                "priority": 100,
                "value": "585er Gold"
              }
            ]
          },
          "priority": 0,
          "quantity": 21,
          "scannableCodes": [
            "text"
          ]
        }
      ],
      "tags": [
        {
          "value": "text",
          "id": "text"
        }
      ],
      "stickers": [
        {
          "key": "LGMl2DuvPnfPoSHhYFOm",
          "priority": 100,
          "nameLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "name": "SomeName",
          "color": "#19b6b5"
        }
      ]
    }
  ],
  "loadUnitRefs": [
    "text"
  ],
  "orderDate": "2020-02-03T08:45:50.525Z",
  "parcelRef": "2fOge2ZGW54K4TgvDTQw",
  "pickJobRef": "ca525716-7208-4a63-a2a6-11274eb37f67-0",
  "processId": "text",
  "shipmentRef": "Esb20gpHBL94X5NdMp3C",
  "shortIdentifier": "text",
  "status": "OPEN",
  "targetTime": "2024-09-07T23:26:11.818Z",
  "tenantOrderId": "R456728546",
  "paid": false,
  "tags": [
    {
      "value": "text",
      "id": "text"
    }
  ],
  "stickers": [
    {
      "key": "LGMl2DuvPnfPoSHhYFOm",
      "priority": 100,
      "nameLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      },
      "name": "SomeName",
      "color": "#19b6b5"
    }
  ],
  "cancelReason": "CONSUMER_NO_SHOW",
  "invoiceAddress": {
    "companyName": "Speedy Boxales Ltd.",
    "firstName": "Maxine",
    "lastName": "Muller",
    "salutation": "Frau",
    "email": "test@try.de",
    "addressType": "POSTAL_ADDRESS"
  },
  "recipientAddress": {
    "companyName": "Speedy Boxales Ltd.",
    "firstName": "Maxine",
    "lastName": "Muller",
    "salutation": "Frau",
    "email": "test@try.de",
    "addressType": "POSTAL_ADDRESS"
  },
  "fullIdentifier": "text",
  "anonymized": false,
  "id": "95EWrieX09OmeriXIUbb",
  "documents": [
    {
      "id": "text",
      "documentType": "PDF",
      "documentCategory": "EXTERNAL",
      "status": "AVAILABLE",
      "operations": [
        "PRINT"
      ],
      "name": "text",
      "path": "text",
      "priority": 0
    }
  ],
  "documentsRef": "text",
  "carrierKey": "text"
}

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/handoverjobs' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "carrierRef": "d802fcce-42ac-0f1s-d311-e6f97687353a",
    "channel": "DELIVERY",
    "facilityRef": "f92fcec6-dc65-4532-af40-e057683ad873",
    "handoverJobLineItems": [
        {
            "article": {
                "customAttributes": {},
                "imageUrl": "string",
                "tenantArticleId": "4711",
                "title": "Cologne Water",
                "weight": 10,
                "attributes": [
                    {
                        "category": "descriptive",
                        "key": "%%subtitle%%",
                        "priority": 100,
                        "value": "585er Gold"
                    }
                ]
            },
            "quantity": 21,
            "handedOverQuantity": 20,
            "substituteLineItems": [
                {
                    "article": {
                        "customAttributes": {},
                        "imageUrl": "string",
                        "tenantArticleId": "4711",
                        "title": "Cologne Water",
                        "weight": 0,
                        "attributes": []
                    },
                    "priority": 0,
                    "quantity": 21,
                    "handedOverQuantity": 20,
                    "scannableCodes": [
                        "978020137962"
                    ],
                    "partialStockLocations": [
                        {
                            "quantity": 21,
                            "location": {
                                "locationRef": "string",
                                "scannableCodes": [
                                    "978064813962"
                                ]
                            }
                        }
                    ]
                }
            ]
        }
    ],
    "orderDate": "2023-07-08T08:45:50.525Z",
    "pickJobRef": "ccf150a3-91a7-4c16-a301-f246ef2db6c6",
    "processId": "49609d17-e26c-487f-8f2c-86ddc02e0863",
    "shipmentRef": "be67a593-fad7-4250-be61-7a3cc87820ea",
    "shortIdentifier": "SH31",
    "status": "OPEN",
    "targetTime": "2023-07-06T08:03:36.197Z",
    "tenantOrderId": "R456728546",
    "paid": false,
    "cancelReason": "CONSUMER_NO_SHOW",
    "invoiceAddress": {
        "street": "Schanzenstr.",
        "houseNumber": "30",
        "postalCode": "51063",
        "city": "Köln",
        "country": "DE",
        "phoneNumbers": [
            {
                "value": "0177-555-6273",
                "label": "private",
                "type": "MOBILE"
            }
        ],
        "additionalAddressInfo": "3. Etage",
        "salutation": "Herr",
        "firstName": "Homer",
        "lastName": "Simpson",
        "addressType": "POSTAL_ADDRESS"
    },
    "recipientAddress": {
        "street": "Schanzenstr.",
        "houseNumber": "30",
        "postalCode": "51063",
        "city": "Köln",
        "country": "DE",
        "phoneNumbers": [
            {
                "value": "0177-555-6273",
                "label": "private",
                "type": "MOBILE"
            }
        ],
        "additionalAddressInfo": "3. Etage",
        "salutation": "Herr",
        "firstName": "Homer",
        "lastName": "Simpson",
        "addressType": "POSTAL_ADDRESS"
    },
}
'

Mandatory Fields

channel

The channel describes whether this order will be collected by the customer or by a parcel service provider. The value can either be COLLECT or DELIVERY

facilityRef

The id of the facility this order is handed over in

orderDate

The date and time this order was placed

targetTime

The date and time this handover job has to be handed over

Optional Fields

carrierLogoUrl

The url to the logo of the carrier for displaying purposes in the Backoffice

carrierRef

The id of the carrier in case this is an order fulfilled by a parcel service provider

carrierTrackingNumber

The tracking number provided by the parcel service provider.

customAttributes

Additional information you might want to add to this Handover Job.

handoverJobLineItems

The items that the Handover Job contains.

loadUnitRefs

The ids of the Load Units used in the picking process of this order.

parcelRef

The id of the Parcel used

pickJobRef

The id of the related Pick Job

processId

The id of the related Process

operativeProcessRef

The id of the related Operative Process

shipmentRef

The id of the related shipment.

shortIdentifier

A short id

status

The status of the Handover Job it should be created in. Can be: OPEN, HANDED_OVER, OBSOLETE, CANCELED (created in OPEN when not provided)

tenantOrderId

The id you use internally for this order.

paid

A boolean flag that indicates whether this order has already been paid for or not

tags

The tags that are related to this Handover Job

stickers

Stickers that are related to this Handover Job.

cancelReason

The reason this hand over has been cancelled. Can be: CONSUMER_NO_SHOW, CONSUMER_REJECTS, ORDER_CANCELLED

invoiceAddress

Address of the invoice.

recipientAddress

Address of the recipient.

fullIdentifier

A longer identifier

transfers

Transfers related to this Handover Job.

Finishing a Handover Job

Call a single action on a given Handover job

POSThttps://%%HOST%%//api/handoverjobs/{handoverJobId}/actions

Authorization

Path parameters

handoverJobId*string

Reference to the handover job you want to call the action for

Body

HandoverJobActionsParameter (any of)

Response

Updated Handover job in the body.

Body

createdstring (date-time)

The date this entity was created at the platform. This value is generated by the service.

Example: "2020-02-03T08:45:51.525Z"

lastModifiedstring (date-time)

The date this entity was modified last. This value is generated by the service.

Example: "2020-02-03T09:45:51.525Z"

version*integer (int64)

The version of the document to be used in optimistic locking mechanisms.

Example: 42

carrierLogoUrlstring

The URL to the carrier logo

carrierRefstring

carrierTrackingNumberstring

Tracking number for the created shipment

channel*enum

DELIVERYCOLLECT

customAttributesobject

Attributes that can be added to the handover job. These attributes cannot be used within fulfillment processes, but it could be useful to have the informations carried here.

facilityRef*string

The id of the facility reference.

Example: "Esb20gpHBL94X5NdMp3C"

handoverJobLineItemsarray of HandoverLineItem (object)

loadUnitRefsarray of string

Reference to array of load unit Refs

orderDate*string (date-time)

The date this order was created at the supplying system.

Example: "2020-02-03T08:45:50.525Z"

parcelRefstring

The reference to the parcel.

Example: "2fOge2ZGW54K4TgvDTQw"

pickJobRefstring

The reference to the pickjob for which the handoverjob is assigned to

Example: "ca525716-7208-4a63-a2a6-11274eb37f67-0"

processIdstring

Id of the global process related to this entity. For example used for starting the GDPR process and others.

shipmentRefstring

The reference to the shipment belonging to the handoverjob

Example: "Esb20gpHBL94X5NdMp3C"

shortIdentifierstring

The short identifier of the shipment.

statusHandoverjobStatus (enum)

OPENHANDED_OVEROBSOLETECANCELED

targetTime*string (date-time)

The time the handoverjob is expected to be picked up at the facility.

tenantOrderIdstring

Field can be used as a reference number in foreign systems, for example as a reference to the source system's identifier for this order.

Example: "R456728546"

paidboolean

Indicates if the order is already paid

Example: false

tagsarray of TagReference (object)

Tags can only be set when there is no process related with this handoverJob. Setting processId and tags will lead to an validationError.

stickersarray of Sticker (object)

cancelReasonHandoverJobCancelReason (enum)

CONSUMER_NO_SHOWCONSUMER_REJECTSORDER_CANCELED

invoiceAddressConsumerAddress (object)

recipientAddressConsumerAddress (object)

fullIdentifierstring

An information to identify the recipient

anonymizedboolean

Indicates if gdpr related data was anonymized

Example: false

idstring

The id of this handoverjob. It is generated during creation automatically and suits as the primary identifier of the described entity.

Example: "95EWrieX09OmeriXIUbb"

documentsarray of PrintableDocument (object)

stickersarray of Sticker (object)

documentsRefstring

Reference to the documents collection from this entity

carrierKeystring

Key of the carrier that is used for this entity

Request

const response = await fetch('https://%%HOST%%//api/handoverjobs/{handoverJobId}/actions', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "CANCEL",
      "payload": {
        "handoverJobCancelReason": "CONSUMER_NO_SHOW"
      }
    }),
});
const data = await response.json();

Response

{
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42,
  "carrierLogoUrl": "text",
  "carrierRef": "text",
  "carrierTrackingNumber": "text",
  "channel": "DELIVERY",
  "facilityRef": "Esb20gpHBL94X5NdMp3C",
  "handoverJobLineItems": [
    {
      "article": {
        "imageUrl": "text",
        "tenantArticleId": "4711",
        "title": "Cologne Water",
        "weight": 0,
        "attributes": [
          {
            "category": "descriptive",
            "key": "%%subtitle%%",
            "priority": 100,
            "value": "585er Gold"
          }
        ]
      },
      "picked": 20,
      "quantity": 21,
      "substituteLineItems": [
        {
          "article": {
            "imageUrl": "text",
            "tenantArticleId": "4711",
            "title": "Cologne Water",
            "weight": 0,
            "attributes": [
              {
                "category": "descriptive",
                "key": "%%subtitle%%",
                "priority": 100,
                "value": "585er Gold"
              }
            ]
          },
          "priority": 0,
          "quantity": 21,
          "scannableCodes": [
            "text"
          ]
        }
      ],
      "tags": [
        {
          "value": "text",
          "id": "text"
        }
      ],
      "stickers": [
        {
          "key": "LGMl2DuvPnfPoSHhYFOm",
          "priority": 100,
          "nameLocalized": {
            "de_DE": "Wert",
            "en_US": "Value",
            "ru_RU": "значение"
          },
          "name": "SomeName",
          "color": "#19b6b5"
        }
      ]
    }
  ],
  "loadUnitRefs": [
    "text"
  ],
  "orderDate": "2020-02-03T08:45:50.525Z",
  "parcelRef": "2fOge2ZGW54K4TgvDTQw",
  "pickJobRef": "ca525716-7208-4a63-a2a6-11274eb37f67-0",
  "processId": "text",
  "shipmentRef": "Esb20gpHBL94X5NdMp3C",
  "shortIdentifier": "text",
  "status": "OPEN",
  "targetTime": "2024-09-07T23:26:11.818Z",
  "tenantOrderId": "R456728546",
  "paid": false,
  "tags": [
    {
      "value": "text",
      "id": "text"
    }
  ],
  "stickers": [
    {
      "key": "LGMl2DuvPnfPoSHhYFOm",
      "priority": 100,
      "nameLocalized": {
        "de_DE": "Wert",
        "en_US": "Value",
        "ru_RU": "значение"
      },
      "name": "SomeName",
      "color": "#19b6b5"
    }
  ],
  "cancelReason": "CONSUMER_NO_SHOW",
  "invoiceAddress": {
    "companyName": "Speedy Boxales Ltd.",
    "firstName": "Maxine",
    "lastName": "Muller",
    "salutation": "Frau",
    "email": "test@try.de",
    "addressType": "POSTAL_ADDRESS"
  },
  "recipientAddress": {
    "companyName": "Speedy Boxales Ltd.",
    "firstName": "Maxine",
    "lastName": "Muller",
    "salutation": "Frau",
    "email": "test@try.de",
    "addressType": "POSTAL_ADDRESS"
  },
  "fullIdentifier": "text",
  "anonymized": false,
  "id": "95EWrieX09OmeriXIUbb",
  "documents": [
    {
      "id": "text",
      "documentType": "PDF",
      "documentCategory": "EXTERNAL",
      "status": "AVAILABLE",
      "operations": [
        "PRINT"
      ],
      "name": "text",
      "path": "text",
      "priority": 0
    }
  ],
  "documentsRef": "text",
  "carrierKey": "text"
}

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/handoverjobs/HANDOVER-JOB-ID/actions/' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "FINISH_HANDOVER_JOB",
    "version": 7,
    "lineItems": [
      {
        "id": "58b8cfa6-c36c-46fb-a6fb-f0fa32228c01",
        "handedOverQuantity": 100,
      }
    ]
}'

Optional Fields

lineItems

lineItems that have (not) been handed over. You can pass an array of line items that have been handed over (or not) including substitute items and add information about items that have been refused (by the customer).

Cancelling a Handover Job

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/handoverjobs/HANDOVER-JOB-ID/actions/' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "CANCEL",
    "version": 7,
}'

Setting refused reasons for a Handover Job

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/handoverjobs' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "UPDATE_LINEITEM",
    "version": 7,
    "lineItem": {
      "id": "a1b993cd-073f-487f-ac48-52fac9a97b65",
      "refused": [
        {
          "quantity": 1,
          "reasonLocalized": {
            "de_DE": "kaputt",
            "en_US": "broken"
          }
        }
      ]
    }
}'

While you can configure available refused reasons via the Handover Job Configuration, the reasons that are passed with this request will not be validated against those that have been configured. This gives you the flexibility between having e.g. free forms for the refused reasons as well as providing pre-defined ones for your clients.

Passing no reason is not allowed. To pass no reasons an appropriate reason (e.g. 'No Reasons') should be used.

PreviousCustom Service NextAdd External Documents

Last updated 1 month ago