This article is the third part of the Youredi Best Practices Series intended to help all logistics industry actors increase their operational efficiency and grow business.
In this part, we explain how to transfer binary files, such as PDFs or images, from your system to your trading partners as part of an API message.
Preamble
Although digitizing the paperwork process is running at full speed in the world of logistics and supply chain, some procedures still need to be done in an old-fashioned way with the involvement of paper-based documentation. One example of such a case is processing the Bill of Lading (B/L or BoL) - one of the main documents used to execute transportation transactions by sea, air, or road.
Even though there are a vast number of solutions available today to digitalize the B/L routine, the traditional method of processing the document still dominates: the moment cargo is loaded to a vessel, the carrier/freight forwarder issues a paper-based B/L and transfers it to the exporter of the cargo. Next, the exporter sends the document to the importer/consignee via courier services such as DHL or FedEx. The process is expensive and might take up to a few weeks before the document is delivered to the recipient, which often (especially with air freight) exceeds cargo transportation time. This leads to a situation when parties involved in the freight chain might need to get a digital copy of the original B/L (PDF or digital image) to speed up the trade transactions and cargo processing.
EDI technology, widely used today in logistics, cannot transmit binary data such as PDF or images in any way. All that can be sent via EDI is the waybill - so-called IFTMCS or manifest messages - which rather provides a description of cargo and cannot be used as a legal copy of the original paper document.
Today, the most common way to transfer digital copies of documents to trading partners is to send them by email. However, email is not the most secure and reliable channel, leading to many global logistics and supply chain actors seeking modern alternatives. One of those is transmitting binary files as a part of API messages.
Problem statement: Enabling the transfer of binary files via API is a challenging task for many
API, as a technology based on JSON format and HTTP/HTTPS protocols, does not work with binary data straightaway. First, such files should be well prepared, and only then can they be integrated and pushed as a part of API messages.
How to attach and transfer binary files (PDFs, images, or anything else) as a part of an API message
To transfer an image or PDF file via API, which is a digital copy of B/L in this case, it is necessary to first prepare it by converting binary code into a character string. To do that can be used Base64 encoding schemes that represent binary data in an ASCII string and makes it acceptable for JSON protocol. After the Base64 conversion, the encoded PDF/image file can be easily added as a character string to the payload and sent along with other fields of an API message.
In case you are in the position of being the recipient of the message, you need to go through the process oppositely - receive the message, extract the piece representing the received document, decode it back to binary format, and save it as a file.
The whole process of transferring a binary file from one API to another can be outlined as the following:
A flow of actions on a sender's side:
1 - Read a binary file from the system
2 - Convert the file into Base64 format (a format that works for API messaging)
3 - Integrate converted binary documents to an API message
4 - Send the API message to a recipient
Necessary actions on the recipient side:
5 - Receive the message
6 - Extract the encoded data from the received payload
6 - Decode it into binary code
7 - Save as a binary file to your system
Although the process looks relatively simple, Read-Convert-Transmit-Decode-Save, it might be a challenge for many systems to do the work, especially when the process needs to be automated and scalable.
Solution
To overcome this challenge, you can use Youredi's fully managed data integration solution capable of handling the transfer of binary files with API in the most efficient way and executing the process described above in a blink of an eye. The solution is cloud-based and built upon Youredi iPaaS working with any data format or protocol. It works as a layer between your system and the system of your trading partner, so you need not change anything in your existing IT setup.
What if the recipient's API does not support Base64 decoding?
Some APIs might be designed so they cannot convert the Base64 back to binary format. In that case, we are not sending a binary document as a Base64 encoded payload inside an API message. Instead, in the API message, we just send a reference for the binary document along with the instruction of how the file was sent and make the file transfer via our SFTP server, or some other file transfer protocol suitable for binary data transfers, to the recipient's IT system. Being equipped with the reference and instruction, the recipient can match the API message with a corresponding binary document received via SFTP.
Relying on the Youredi solution, you will always have digital copies of the necessary transportation process documents at hand when you need them, even though your current data integration setup is not designed to work with binary documents or Base64 decoding.
Benefits and key takeaways
Whether you are a sender or a recipient of a binary document, leveraging Youredi's solution, you ensure the automation and scalability of your data transfer process.
Besides that, you will get reliable and seamless connectivity with your trading partners and guaranteed secure data transfer.
To get the solution working, you need not change anything in your system or allocate additional resources. The Youredi team will manage the whole process from deployment to maintenance, and configures the Youredi solution to adapt to your existing API or system interface.
About Youredi best practices series
The best practices series objective is to share with you - industry stakeholders - information and advice on how to be better and more efficient in this market.
This series focuses on tangible, detailed challenges and respective solutions we have deployed with and for our clients and partners.
These use cases are presented to help companies understand there is an affordable, modern, proven, and rapid way to solve these challenges.
If you missed our previous episodes, we discussed:
- How to automate EDI-204s, Truckload Tender Process
- Best practices for ocean shipment tracking
- Why and how to track your ocean shipments (On-demand webinar:)
Youredi works with many local, regional, and global logistics and supply chain management organizations, service providers, software companies, brokers, manufacturers, (e)retailers and others.
To learn more about Youredi or the solutions we provide, don't hesitate to schedule an online meeting with our team of integration experts or contact us via this form.
