Handover

This article focuses on the handover process for developers. For information on the handovers in the store operations process, see the Handoverarticle in the Operations appsection.

A handover job represents the handover of an order to the end consumer or shipping provider.

As well as general information like the order date, tenant order ID, or a reference to the corresponding facility, a handover job carries handover relevant information. This covers:

• Handover channel:

  • Delivery: will be handed over to a shipping service provider

  • Pick up: will it be handed over to the end customer

• Handover job cancel reason: Can be defined if the parcel(s) weren't handed over

A handover job is automatically created when:

• A parcel has changed to status FINISHED while the related pick job was in status CLOSED

• A pick job has changed to status CLOSED and there is at least one parcel of the related shipment that has the status FINISHED

Automatic versus manual handover job completion

A handover job is completed (set to status HANDED_OVER) automatically when a track-and-trace event is received from a carrier with track-and-trace enabled (if a carrier integration is in place).

It's possible to manually set a handover job to status HANDED_OVER, which triggers the handover event even before the carrier has physically scanned or picked up the parcel. In this case, the information from the handover job, such as items and quantities, is used to mark all associated line items as handed over. This ensures that line item quantities are passed correctly.

Currently, it's not possible to restrict the manual action based on user roles or permissions. As a result, users can manually trigger a handover event even before the carrier picked up the parcel.

Handover configuration

The handover configuration allows users to define rules for the handover process.

The handover configuration is available at /api/configurations/handover (see the handover configuration endpoint section for more information) and affects the whole system regardless of the user role or the facility.

In the handover configuration, you can define:

• The reasons a handover was refused

Handover refuse reasons

The refused reason configuration defines the options a user can choose from if a handover job is refused by a consumer and the product is marked with the reason.

You need to add the availableRefusedReasons array. For the option to be available, active needs to be set to true. You can then input a refusedReasonLocalized object and set up different inputs for different languages.

Localization for reasons

The response has a refusedReason field that contains one of the locales provided by refusedReasonLocalized object. Which exact translation was chosen depends on the locale set in the authorization token when sending the request to the GET endpoint.

If no locale was provided by the client or the locale is not available in the refusedReasonLocalized object, the answer will default to the tenant locale. If the tenant locale is also not available in the refusedReasonLocalized object, then the first key-value pair will be selected.

Handover configuration endpoints

To access the current handover configuration, use the endpoint below:

GET https://{your-tenant-name}.api.fulfillmenttools.com/api/configurations/handover

To update the current handover configuration, use the endpoint below:

Endpoint

PUT https://{your-tenant-name}.api.fulfillmenttools.com/api/configurations/handover

Request body

Response body

Update handover configuration

put

This part of the API is in Beta status. For details please check the api-release-life-cycle documentation. Updates the handover configuration for the tenant. If the configuration does not exist, it will be created.

Authorizations

BearerToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

HandoverConfigurationForCreate

availableRefusedReasonsanyOptional

AvailableRefuseReasonForCreation

createStandaloneHandoverJobsbooleanOptionalDeprecated

This part of the API is deprecated. For details please check the api-release-life-cycle documentation.

If true, a handover job will be created out of a valid routing plan. It is only possible, if no pickjob nor packjobs are used for this tenant. This is a alpha feature and might be completly replaced in the future. Please only use in communication with the FFT team.

Example: true

versionnumberRequired

Responses

200

The handover configuration was successfully updated.

application/json

HandoverConfiguration

400

Invalid input. See response for details

application/json

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this endpoint

application/json

put

/api/configurations/handover

HTTPcURLJavaScriptPython

PUT /api/configurations/handover HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 42

{
  "availableRefusedReasons": [],
  "version": 1
}

{
  "availableRefusedReasons": [],
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42
}