APIs in SAP Business Network Freight Collaboration

Provider API for Dock Appointment Scheduling

As a shipper, you can use this inbound service to create dock appointment requests and confirmed dock appointments in your SAP Logistics Business Network based on the information from your external systems such as a transportation system, warehouse management system, yard management system and so on. You can also use this service to provide a guest user access to your customers and carriers who are not on SAP Logistics Business Network and enable them to maintain the appointment details in SAP Logistics business network.

Technical Name

GenericAppointment_In

Description

You can perform the following in your SAP Business Network for Logistics system:

  • Create an appointment request

    Note that to create an appointment request, you must send the appointment status as 01 from your external system to your SAP Business Network for Logistics system.

  • Book an appointment

    Note that to book an appointment, you must send the appointment status as 03 and the appointment ID from your external system to your SAP Business Network for Logistics system.

  • Update an appointment request

    Note that to update an appointment request, you must send the appointment status as 01 and the appointment ID from your external system to your SAP Business Network for Logistics system.

  • Update a booked appointment

    Note that to update an appointment request, you must send the appointment status as 03 and the appointment ID from your external system to your SAP Business Network for Logistics system.

Note that SAP Business Network for Logistics accepts only 700 items in a dock appointment.

Prerequisites

You have performed the following:

  • You have created a shipper and carrier business partner in your SAP Business Network for Logistics and your external system.

  • In your external system, you have the LBN ID and you have mapped the LBN ID with the business partner.

  • You have created a location master data in your SAP Business Network for Logistics and then created a docking location for this location. You must use this location and location ID in the webservice SOA Manager interface.

  • You have created the loading point ID in your SAP Business Network for Logistics. You must use this loading point ID in the webservice SOA Manager interface.

Structure

They system has different fields categorized under different nodes. Each node contains various fields. Below are some of the important fields displayed by the system:

Technical Name Field Description Node
OrderingPartyLbnId Ordering Party LBN ID* Contains the ordering party ID maintained in the SAP Business Network for Logistics system Appointments
CarrierLbnId Carrier LBN ID* Contains the carrier ID maintained in the SAP Business Network for Logistics system Appointments
SenderSystemId Sender System ID* Contains the ID of sender system Appointments
AppointmentStatusCode Appointment Status Code

Contains one of the following status codes:

01 – Appointment Request Created

02 – Pending Confirmation

03 – Confirmed

 Appointments
LoadingActivityType Loading Activity Type

Contains one of the following activity types:

01 - Loading

02 – Unloading

03 – Loading/Unloading

 Appointments
CargoItemDescription Cargo Item Description Contains the cargo item description Appointment Cargo Item
DangerousGoodsAreContained Dangerous Goods Are Contained Contains the information whether dangerous goods are contained Appointment Cargo Item
CreatedAt Created At Contains the date and time at which the note was created Appointment Note
DocumentId Document ID Contains the document ID of the source business document from your external system (For example, freight order, transport unit, yard order). Appointment Reference Document
DocumentType Document Type

Contains one of the following types of reference document.

1311 –Transportation Unit Appointment (Extended Warehouse Management)

1122 –Transportation Order (Transportation Management)

YO –Yard Order (Yard Logistics)

 Appointment Reference Document

Note that the fields marked with * are mandatory fields.

Guest User Access

You can provide a guest user access to your customers and carriers who are not on SAP Business Network for Logistics and enable them to maintain the appointment details in SAP Business Network for Logistics system.

Once you provide a guest user access, the system generates an URL and sends it to the carrier in an email. To validate the authenticity of the accessing personnel, when the carrier navigates to the URL, the system prompts the carrier to enter additional appointment information such as the order number or delivery ID of the appointment. Once the carrier passes the security validation, the carrier can view the appointment details, select the time slots, and save the appointment. The customer can also invite a carrier to access this appointment and select the time slots.

The appointments which allow guest user access must contain the following:

  • Additional customer contact details such as the email address

  • Appointment type as EX

  • Role code as LBN_02

  • Document reference type as one of the following:

    Document Reference Type Code Description
    1122 Transportation Order
    614 Freight Order
    YO Yard Order
    612 Shipment Order
    73 Outbound Delivery
    58 Inbound Delivery
    001 Purchase Order
    114 Sales Order

You must also retrieve the email address of the customer from the business partner directory in your external system and pass the information through this service.

Acceptable Date and Requested Time Period

When a carrier maintains an appointment in the SAP Business Network for Logistics system with the Self-Book Dock Appointments app, they maintain the time slots based on the time frames in the source document such as the freight order.

An appointment is booked only when it contains a time slot. Otherwise, the system updates the status of the appointment as provisional. The time slots are not booked for a provisional appointment and so the customers send the appointment requesting for a time slot if it is available. If it is not available, we still want to create the appointment but if it is available already book the appointment.

When you send an appointment to the customer, the customer sends the requested and acceptable period. Acceptable time period corresponds to a broader horizon based on the time frames in the source document such as the freight order. Requested time period is a time slot that the carrier prefers to book an appointment.

When the customer sends the appointment to SAP Business Network for Logistics system, the system sets the status of this appointment as Pending Confirmation as the customer does not know whether the time slot is available or not. The system checks if the appointment can be booked for that requested time period. If yes, the system changes the appointment status from Pending Confirmation to Confirmed. If that time slot cannot be booked, then the system updates the appointment status from Pending Confirmation to Provisional.

Create an Appointment Without Reference Document

The system enables you to create an appointment without a reference document. You can later add the details such as reference document details, order details, delivery ID, and so on. You can also add additional reference document details or replace a reference document.

Enable Overbooking

When you enable overbooking for a loading point, you can create multiple appointments or block a time slot multiple times irrespective of the capacity of the loading point. You can also enable overbooking only for a carrier or only for you as a shipper depending on your settings for that loading point.

In the appointment confirmation, a new node has been added for messages. You can view the messages in the following scenarios:

  • If a customer creates an appointment via API, the system creates a confirmation message for the same.

  • If the loading point is not set for overbooking and if preferred time slot is not available, the system does not create the appointment and creates an error message for the same.

  • When the customer sends the appointment with the status as Pending Confirmation and the system changes the appointment status to either Confirmed or Provisional, the system provides a message for the same.

Notes and Attachments

You can use this inbound API to update the SAP Business Network for Logistics system with the notes from your external systems.

You can use this inbound API to update the SAP Business Network for Logistics system with the attachments from your external systems.