Delivery Application Integration Flow

This guide outlines the end-to-end integration flow for a Delivery application connecting to the POS Hub platform. This flow is essential for developers building integrations for last-mile delivery services.

The primary responsibilities of a Delivery application are to:

1. Receive delivery quote requests from POS Hub and return pricing and availability.
2. Dispatch a delivery job when a quote is accepted.
3. Provide real-time status updates for the delivery.
4. Handle delivery cancellations.

High-Level Integration Diagram

This diagram illustrates the key interactions between the user, POS Hub, your Delivery application, and the external Delivery service.

Step 1: Onboarding and Authentication

The first step is for a merchant to install your application in their POS Hub location. This connects their location with your application and authorizes your app to request and manage deliveries on their behalf.

1. Installation: A user navigates to the "Apps" section in their POS Hub location and installs your Delivery application.
2. Authorization Redirect: POS Hub redirects the user to your application's redirect uri endpoint. Your application should then redirect the user to the external delivery service's OAuth2 authorization page or provide another means of onboarding (such as a manual API key entry).
3. User Consent & Token Exchange: The user logs into their delivery service account and grants your application the necessary permissions. The service then redirects back to your application with an authorization code. Your application exchanges this code for an access token and a refresh token.
4. Store Credentials: Your application must securely store the access token, refresh token, and any other necessary identifiers associated with the POS Hub location.

Step 2: Delivery Quoting

When a user needs a delivery, POS Hub will request quotes from all installed and enabled delivery applications. This is handled by your application's /get-delivery-quote endpoint.

Your implementation of /get-delivery-quote must:

1. Receive Delivery Details: Accept a POST request from POS Hub containing the delivery payload, which conforms to the POS Hub DeliveryEntity schema.
2. Transform Data: Convert the standardized POS Hub delivery data into the format required by the external delivery service's quoting API.
3. Request Quote from Delivery Service: Use the stored credentials to make an API call to the external delivery service to get a quote.
4. Return Transformed Quote: Respond to POS Hub with an array of quotes, each conforming to the DeliveryQuote schema. This allows a single provider to return multiple options (e.g., standard vs. express delivery).

Step 3: Delivery Dispatch

Once the user selects a quote, POS Hub will call your /dispatch-delivery-quote endpoint to initiate the delivery.

Your implementation of /dispatch-delivery-quote must:

1. Receive Dispatch Request: Accept a POST request from POS Hub containing the selected DeliveryQuote and the full DeliveryEntity.
2. Create Delivery Job: Use the quote and delivery details to make an API call to the external delivery service to create a new delivery job.
3. Return Dispatched Delivery Details: Respond to POS Hub with the details of the dispatched delivery, conforming to the DispatchedDelivery schema. This response should include the external delivery ID and a tracking URL, if available.

Step 4: Real-time Status Updates

As the delivery progresses, the external delivery service will send updates to your application, typically via webhooks. Your application is responsible for relaying these updates to POS Hub.

Your webhook handler for delivery status updates should:

1. Receive Status Update from Delivery Service: Listen for incoming webhook events from the external delivery service.
2. Transform the Status: Convert the delivery service's status into the appropriate POS Hub DriverStatus enum value.
3. Update POS Hub: Make a PATCH request to the POS Hub /v1/accounts/{accountId}/locations/{locationId}/deliveries/{deliveryId}/dispatch/{dispatchId} endpoint to update the delivery status. You can also include other details like the driver's name, vehicle information, and current location.
4. Acknowledge the Webhook: Return a 200 OK response to the external delivery service.

Step 5: Delivery Cancellation

If a user needs to cancel a delivery, POS Hub will call your /cancel-delivery endpoint.

Your implementation of /cancel-delivery must:

1. Receive Cancellation Request: Accept a POST request from POS Hub containing the deliveryId and dispatchId.
2. Cancel Job with Delivery Service: Make an API call to the external delivery service to cancel the delivery job.
3. Acknowledge the Request: Return a 200 OK response to POS Hub to confirm the cancellation.