Booking
How the Budbee Skrym events are structured
Last updated 12 Sept 2024
This page lists the results from the requirements analysis phase of the budbee booking integration as detailed in the Transporter integration template. Questions answered by the research framework can be found here.
Transport methods endpoints
Delivery postcode validation
For Budbee home only. The only expected values are country code and postal code. More info can be found in Budbee's postcode validation documentation.
Alternatively, they allow users to request all supported postal codes for a given country which may be stored and used for this validation step. More info can be found in Budbee's post code list documentation.
Delivery intervals check
This step is only for Budbee Home. More info can be found in Budbee's delivery windows documentation.
Requesting lockers
Available lockers must be requested from Budbee for box deliveries (if the transport method is Budbee Box). This can be clubbed with the postcode validation step as Budbee can return all lockers sorted by distance to postcode.
Alternatively, a user can fetch all available lockers in a given country and use that. Budbee also allows for fetching by locker ID.
More info can be found in Budbee's box deliveries documentation.
Order creation
Budbee uses the same endpoint to create orders for both Budbee Home and Budbee Box. The DLVBOX
product code is expected incase of box deliveries. More info can be found in Budbee's order creation documentation.
Adding parcels
Budbee expects parcels to be added to an order after it has been created. Only single parcels allowed for Budbee Box, otherwise multiple parcels are allowed. More info can be found in Budbee's add parcels documentation.
Booking a pickup
Budbee does not expose separate endpoints for booking pickups. It appears as if merchants can register Sender Addresses
in the Budbee Merchant Portal. These are the registered locations where Budbee will pickup parcels. More info can be found in Budbee's sender addresses documentation.
Shipment Information
These are the mandatory shipment information fields that Budbee expects when making a booking:
Delivery Address
- Postal Code: string
- Country Code: string
- Street: string
- City: string
Recipient Details
- Name: string
- Phone: string
- Email: string
Parcel Options
- If a parcel can be left outside the door (outsideDoor): boolean
- If signature is required on delivery (requireSignature): boolean
Cart and Collection
- Cart ID: string
- Collection ID: integer
Product Details
- Name: string
- Reference: string
- Quantity: integer
- Unit Price: float
- Currency: string
Transport Method
- Product Code: string
More info can be found in Budbee's orders documentation.
Label Creation
Budbee returns presigned URLs containing labels when a parcel is added to the order. The presigned URLs are only valid for 48 hours, so the labels must be saved by then.
The URL contains a X-Budbee-Signature
query parameter which may be used for requesting labels after that. There are however no mentioned APIs for making this re-request.
More information can be found in Budbee's labels documentation.
Handling unavailable destinations:
Box Deliveries
For box deliveries, we can try requesting lockers for a given postal code as in the request lockers API.
In one option, Budbee returns lockers sorted by distance to given postal code. So we can check if the first locker is further away than a certain threshold, and if so reject the booking.
There are other ways of getting lockers which can be found in Budbee's box deliveries documentation which would involve different approaches based on locker distance.
Home deliveries
Budbee postcode validation API can handle unavailable destinations for other Budbee methods. More info can be found in Budbee's postcode validation documentation.
Cancellations
Budbee offers an endpoint enabling users to cancel booked orders. However, cancellations are not guaranteed with unsuccessful cancellation being denoted by a 403 Forbidden
. More info can be found in Budbee's cancellation documentation.
Booking a shipment
Shipment booking follows slightly different processes based on transport method as shown in the below flowcharts. The output boxes denote the output from a previous step, while the Note boxes denote an active action that must be taken based on the output.
Creating a label
Budbee returns a presigned URL containing labels as detailed in the labels section. The presigned URL contains hardcoded query parameters that can be modified to determine the type of label to download.
The following query parameters can be changed:
fileType
(hardcoded topdf
, but can be changed tozpl
)documentSize
(hardcoded to 10x15, but can be changed to the required size)
More information can be found in Budbee's labels documentation.
Tracking
Budbee offers a tracking endpoint that can be used to fetch a tracking link for a shipment. More info can be found in Budbee's tracking documentation.
A tracking link can be fetched on an order level or on a parcel level.
In Skrym's integration with Budbee, a tracking link is fetched and inserted on both the FreightShipment
and FreightParcel
level, alongside with a tracking reference.
Customs/Tolls
No mention in the documentation of how this is handled. Can double check in Budbee's documentation.
Budbee Addons
Budbee Home Delivery
Budbee addon | Skrym addon | Addon type | Description |
---|---|---|---|
identificationCheckRequired | identification-by-national-id | boolean | Driver must check identification at delivery |
recipientMinimumAge | recipient-minimum-age | number | The recipient must be at least this old at delivery |
recipientMustMatchEndCustomer | recipient-must-match-end-customer | boolean | The recipient must be the same person that booked the order |
numberOfMissRetries | number-of-delivery-retries | number | Number of times that a failed delivery may be retried until returned to warehouse (null for infinite) |
outsideDoor | leave-outside-door | boolean | Is it ok to leave shipment outside door if recipient is not at home |
doorCode | door-code | number | Entry code to door |
additionalInfo | additional-delivery-instructions | string | Additional info to transporter regarding shipment |
requireSignature | require-signature | boolean | Driver must receive a signature from recipient at delivery |
Budbee Box Delivery
Budbee addon | Skrym addon | Addon type | Description |
---|---|---|---|
fraudDetection | identification-check-required-bank-id | string | Expects a string containing a social security number, triggering identification by BankID |