TransFollow freight document Lifecycle

1.Freight document lifeCycle

Creating a freight document.

Freight documents are created by an accountholder that will be known as the submitter of this document. The submitter must be logged in. Creation is done by a call POST /freightdocuments providing a request body that contains at least all the mandatory attributes. The API Endpoint Specifications describe what these are. The roles of Consignor, Place Of Taking Over and Consignee are mandatory. A Carrier role may be included from the start or added later, while the freight document is in draft. Roles can be occupied by accounts, by subaccounts, or by email addresses of people without an account. When a freight document is created everyone with a role is notified about this fact. When a person has a role in the freight document (via an email address) and does not have a TransFollow account, the user is informed via email. All parties will have role-specific separate access to the freight document, according to their permissions. A freight document can be created in DRAFT, which means some changes still are allowed. Place Of Delivery and Substitute Carriers can be added to the freight document after it's creation in DRAFT. Or it is created in state ISSUED.

Delegating the original role's rights to a different account.

Every user that has the original role on a freight document can delegate his or her rights - of a specific role within this freight document - to another account or to a subaccount. Delegation can be done on account level or in the context of one freight document. In case of an account delegation the DELEGATE receives the rights until the rights are withdrawn (for every existing and new freight document). If an account has more roles than one each role can be delegated separately (at account level or per freight document). The original account can share his rights (e.g. to sign for an approval as carrier) with another account. This account will receive all default (belonging to the role) rights, including the DELEGATE right itself. The original account will still have all rights as well. The delegate account can itself delegate its newly received rights to a third account.

Structured Goods.

It is possible to add a collection of structured Goods. Structured goods objects can contain goods (type GOOD) and/or returnable transport items (type RTI). The objects have a predefined set of fields, some of which are mandatory. See the API specification for details.

Changing a freight document.

Freight documents can only be changed by the submitter of the document and only as long as the document has the DRAFT status. The submitter cannot replace the roles of Consignor, Consignee or Carrier, only add them while in DRAFT status. If replacing them is needed a new freight document must be created. The submitter can change many things on the freight document. The API specification details all of them. Updating is done by a call PUT /freightdocuments/{id}, providing a request body that holds a complete set of desired sub-entities and attributes. Please note that all sub-entities that are not included in the request body will be processed as empty, which can lead to loss of data. See the API Endpoint Specifications for an example.

Cancelling a freight document

Freight documents that not have been delivered, so with status DELIVERED, can be cancelled by calling POST /freightdocuments/{freightDocumentId}/cancel. Cancelled freight documents will be not visible anymore for any of the roles.

Issuing a freight document.

Freight documents can be issued by the submitter of the document only. Issuing means that the document changes status from DRAFT to ISSUED, or otherwise is created with status ISSUED. Changing from DRAFT is done by a call to POST /freightdocuments/{id}/issue. The submitter account will be deducted with on credit for each issued freight document. From this moment on the document is in business, the main content of the document is legally fixed for the rest of it's lifecycle. Only a select set of data, like ETA's (Estimated Time of Arrival), license plates, real times of arrival or departure, and details of goods may change. Additions in the form of comments (with optional attachments) are allowed in the context of a cargo transfer from one party to the next.

TransFollow Process

Signing a freight document

A freight document starts it's legal life with status ISSUED. At every main transfer of cargo it's status must change further. After being picked up by the carrier it will become TRANSIT. After being handed over at the destination it will become DELIVERED. During the TRANSIT state cargo can be transferred to subsequent carriers. At every cargo transfer a process of 'signing' for - or approving of - the transfer must be excecuted by the two parties involved, one of which is always the carrier. It is therefore not possible to approve a cargo transfer directly between consignor (sender) and consignee (receiver of the goods). The approval process is described below.

Following the status of a freight document

A freight document can be updated with status information, approvals and comments. The carrier can also update the various time attributes, goods details, and license plates, while being underway. All this information is available to every party (or subsitute party) that is assigned a role in the freight document. Relevant changes can be viewed by polling the freight document or by accessing it after a notification. A client system can get notified through a so-called subscription on a freight document. When a status changes for the freight document (to ISSUED, TRANSIT or DELIVERED for example) the subscription will execute a POST call to a callback URL at the clients system.

2.Approval of a freight document on cargo transfer


Before transferring goods the parties involved might want to add a comment to the freight document. This is possible, but only on the device of the carrier and only after the document is ISSUED. Pictures can be added to a comment as attachments.

Starting a transfer approval

The two parties present at every transfer, more specific at collection, delivery or transfer between carriers, will start the approval process in the same manner every time. The carrier (the carrier that transfers the goods in case of two subsequent carriers) will select the right freight document on his device and chooses which cargo transfer is being approved. He then has a choice between an implicit approval - without evidence - and an approval with evidence. An implicit approval can be used when the other party is not present yet but is trusted to pick up the goods later. When not implicit, the two parties have a choice between two types of evidence: a TransFollow Approval (TFA) or a Sign-on-Glass Approval (SGA). If they agree on the right method they can start the chosen procedure even without being online.

Approval Activity

The TFA is the strongest method in terms of provability and non-repudiation. It requires that both (or at least the carrier) counterparties have access to the FreightDocument in issued or transit state. Since the parties were known in their respective roles (Consignor, Carrier or Consignee) when the freight document was issued, they have access to a subset of transactional secrets s1, s2 and s3. Together with authenticating secrets these form the raw ingredients for the TFA approval handshake.

The signing process of a freight document requires two mobile devices. One device is used by the party that represents the consignor or consignee and needs the TF Android app to be installed. The second device is used by the carrier and it needs an mobile application in which the TF Android App integration interface is integrated. If integration with a TMS is not required, the carrier can also use the TF Android app as a standalone app.