Breaking down the Freight Booking API (Ocean) for Carrier Integration (1/2)
Business Network for Logistics
Logistics Business Network (old name for BN4L)
Application Programming Interface
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
In order for the B2B integration to work, both the carrier and the shipper will have to perform these steps in the same order:
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.
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.
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.