SAP Business Network for Logistics – REST API Integration series: Post #1

[Saif]

Breaking down the Freight Booking API (Ocean) for Carrier Integration (1/2)

Glossary:

Acronym	Definition
BN4L	Business Network for Logistics
LBN	Logistics Business Network (old name for BN4L)
TM	Transportation Management
API	Application Programming Interface
MIL	Manage Integration Logs

The SAP Business Network Freight Collaboration solution connects shippers and their logistics partners on a secure network for optimized collaboration and insights, integrated tightly with core business processes for efficiency and resilience. More details can be found here.

The Freight booking document is a primary transportation document for Ocean and Air. The processes supported in SAP BN4L for Ocean scenario are explained here. In this post, the focus is on usage of booking API and the minimum data that is required for a successful end-end integration.

Booking Subcontracting process

Pre-requisite

In order for the B2B integration to work, both the carrier and the shipper will have to perform these steps in the same order:

1. Carrier to maintain webhook and its credentials.

1. Shipper to configure partner connection.

Also, refer blog for tips.

Use Case 1: Booking Confirmation & Updates

Booking confirmation and Updates

As shown above, booking confirmation and updates involves several API exchanges between SAP TM, BN4L, and Carrier systems.

Receiving a booking

An example of a Freight Booking Request that can be used to build the integration.

Breaking down Business Partner details:

Key Business Partners and key field

Note: The technicalId for the tracking process for a Booking would be different from the above. Clients should rely on the Tracking Consumer API call for the relevant technicalId.

In addition to the above, the JSON has other fields within the transportationOrderBooking object, as explained below.

Other Business Partner details

Things to know:

• Refer to the specification for an exhaustive list of Business partner types supported by the API.

• Since SAP TM supports defining custom codes, BN4L supports mapping to the common definition of codes as listed here. Codes that have a mapping are explained here. So, if you are receiving codes that are not listed, shipper to check if the codes are mapped in "Assign Codes" app.

• URL as an attachment is not supported yet. Only files are supported.

Responding to a booking

To respond to a booking, refer to the provider API specification that explains the various fields that can be sent to the shipper. In this post, we will focus on the bare minimum that is required for a successful Booking confirmation call.

API endpoint: https://l20398-iflmap.hcisbp.eu1.hana.ondemand.com/http/v1/FreightBookingConfirmation

Method: POST

Authentication: Use the oauth2.0 client credentials to get a token and pass on the bearer token to the API.

Break down of Booking confirmation Provider API call

While the below shows the minimum mandatory information required, there are more fields in the payload that can be sent back as part of the confirmation so that the shipper receives it.

#Sample Booking confirmation payload (When carrier is sending the confirmation call):
{
    "technicalId": "xri://sap.com/id:LBN#10010001410:QW9_172:FreightBooking:6300003001-0001010581",
    "senderParty": {
        "lbnId": "10010001721<Carrier>"
    },
    "recipientParty": {
        "lbnId": "10010001721<Carrier>"
    },
    "documentRecipientParty": {
        "lbnId": "10010001410<Shipper>"
    },
    "transportationOrderBooking": {
        "freightBookingId": "6300003001",
        "acceptanceStatusCode": "AP",
        "baseBusinessTransactionDocumentReference": {
            "id": "6300003001",
            "typeCode": "1122"
        }
    }
}

#Sample Booking confirmation payload (When Network Partner is sending the confirmation call) 
{
    "technicalId": "xri://sap.com/id:LBN#10010001410:QW9_172:FreightBooking:6300003001-0001010581",
    "senderParty": {
        "lbnId": "10010002311<Network Partner>"
    },
    "recipientParty": {
        "lbnId": "10010001721<Carrier>"
    },
    "documentRecipientParty": {
        "lbnId": "10010001410<Shipper>"
    },
    "transportationOrderBooking": {
        "freightBookingId": "6300003001",
        "acceptanceStatusCode": "AP",
        "baseBusinessTransactionDocumentReference": {
            "id": "6300003001",
            "typeCode": "1122"
        }
    }
}

Of course, one could send more than what is shared above, in that case, make sure you understand the datatypes of the various fields published in the API spec above and the supported code lists for some of the fields (egs: UOM). BN4L only accepts these whitelisted values.

Note: Shippers need to enable carriers to send attachments. Without this, carriers will not be able to send attachments.

Things to be aware of with this API:

• The API will complain with the below error if you send the wrong carrier LBN ID in the payload

• Gives a 401 Unauthorised if you send the wrong credentials, as shown below.

• Sometimes, you may send the wrong shipper LBN ID, miss a mandatory field in the payload, or send incorrect data. In some cases, you may receive a 200 OK, and it may look like the API call was successful, but there are other asynchronous calls that happen in the background which may fail. Hence, these are logged in the Manage Integration Logs app. Make sure to check the app, if you feel, your updates are not going through. Or if the shipper complains that the updates are not received.

In the below case, the wrong recipient LBN IDs were sent.

 

Note: The shipper will also have an equivalent Manage Integration Logs application where they will be able to monitor calls between the Network and TM. If there are no supporting logs in your MIL application, you can also double-check for any logs with the shipper.

Receiving updates to a booking

Updates to a booking can be done by a shipper at any point, typically before or after confirmation. Usually, changes are not made once the booking is in execution. BN4L, uses the same POST API used to receive a booking to also send updates. The payload has "actionCode" field which distinguishes if it is a Create or an Update.

"01" - Create | "02" - Update

 

More Booking scenarios/use cases are continued at SAP Business Network for Logistics – REST API Integration series: Post #2

Subscribe for updates via the RSS feeds. Also, subscribe to the tags to get updates on new content.