Ctrlk
API documentationIncident managementFeedback
Edit

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 If there are multiple parcels, a handover job is created for each parcel in status FINISHED.

  • 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:

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:

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

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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body

HandoverConfigurationForCreate

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

createdstring · date-timeOptional

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-timeOptional

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

Example: 2020-02-03T09:45:51.525Z
versioninteger · int64Required

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

Example: 42
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 pack jobs are used for this tenant. This is a alpha feature and might be completely replaced in the future. Please only use in communication with the fulfillmenttools team.

Example: true
put
/api/configurations/handover

Last updated