Tracking a delivery order (Java)
In this use case, the user requests for a live delivery tracking link that can be rendered on the application.
Code snippets
Client calls the BAP server to trigger track:
@PostMapping("/delivery/track_order")
public ResponseEntity trackOrder(
@RequestHeader HttpHeaders headers,
@RequestBody ClientOrderRequest request) {
var response = bapApplicationService.trackOrder(request, headers);
return ResponseEntity.ok(response);
}
BAP server generates the protocol request body
/*
Example Request JSON:
{
"context": {
"domain": "delivery",
"country": "IND",
"city": "std:080",
"action": "track",
"core_version": "0.9.2",
"bap_id": "https://mock_bap.com/",
"bap_uri": "https://mock_bap.com/beckn/",
"transaction_id": "1239890342",
"message_id": "123793824",
"timestamp": "2021-06-23T08:29:27.933Z"
},
"message": {
"order_id": "order_1"
}
}
*/
public Response trackOrder(ClientOrderRequest request, HttpHeaders headers) {
// Generate message id
var messageId = UUID.randomUUID().toString();
// Check if transaction id exists in the request.
// Generate if not exists
var txnId = StringUtils.hasText(request.getTransactionId())
? request.getTransactionId()
: UUID.randomUUID().toString();
// Construct the Context based on the request parameters
var context = Context.builder().domain(request.getDomain())
.action(Context.ActionEnum.track)
.messageId(messageId)
.transactionId(txnId)
.transactionId(UUID.randomUUID().toString())
.timestamp(new Date().toString())
.build();
// Construct the protocol specific object to be passed to the BPP
// to track the active order
var trackRequest = TrackRequest.builder()
.context(context)
.message(StatusMessage.builder()
.orderId(request.getOrderId())
.callbackUrl(request.getTrackingCallbackUrl())
.build())
.build();
return invokeTrack(trackRequest, headers);
}
}
BAP server calls protocol track to the network
public Response invokeTrack(TrackRequest request, HttpHeaders headers) {
// Call to look up function which returns the the public key and BPP Endpoint to be called
var url = lookUp(headers);
// Call BPP Track api from the returned endpoint.
// Construct request headers with the public key
var responseEntity = apiClient.post(url[0] + Context.ActionEnum.track,
constructRequestHeaders(),
request,
Response.class);
// Validate the received response
if (responseEntity.getBody() == null || responseEntity.getBody().getError() != null ||
"NACK".equals(responseEntity.getBody().getMessage().getAck().getStatus())) {
// Return custom error to the client
return null;
}
return Response.of("ACK", null);
}
BAP receives protocol on_track
/*
Example Response JSON:
{
"context": {
"domain": "delivery",
"country": "IND",
"city": "std:080",
"action": "on_track",
"core_version": "0.9.2",
"bap_id": "https://mock_bap.com/",
"bap_uri": "https://mock_bap.com/beckn/",
"transaction_id": "1239890342",
"message_id": "123793824",
"timestamp": "2021-06-23T08:31:04.045Z"
},
"message": {
"tracking": {
"url": "https://track.bpp.com?order_id=order_1",
"status": "active"
}
}
}
*/
@PostMapping("/bap/on_track")
public ResponseEntity onTrack(
@RequestHeader HttpHeaders headers,
@RequestBody OnTrackRequest request) {
var response = bapCallbackApplicationService.onTrack(request, headers);
return ResponseEntity.ok(response);
}
public Response onTrack(OnTrackRequest request, HttpHeaders headers) {
// Validate the headers received
var isHeadersValid = validateHeaders(headers);
// Construct and return error if the received headers are invalid
if (!isHeadersValid) return null;
// Store the data received based on message id for the client to poll
saveToDB(request);
return Response.of("ACK", null);
}
Client polls BAP to get the on_track results
// Endpoint for the client to poll the order tracking based on the message id
@GetMapping("/delivery/on_track_order")
public ResponseEntity onTrackOrder(
@PathVariable(ClientRoutes.PARAM_MESSAGE_ID) String messageId,
@RequestHeader HttpHeaders headers) {
var data = bapApplicationService.get(messageId);
return ResponseEntity.ok(data);
}