Information specific to our Budbee integrations

On this page you can find information that has more detail regarding our
integrations with Budbee.

Note that the Budbee integration is subject to change due to the ongoing merging process
between Instabox, Porterbuddy and Budbee. 
We are staying in close touch with Instabee regarding these changes and will make updates to these pages when applicable.


Budbee

How the Budbee Skrym events are structured

This page lists the results from the requirements analysis phase of the budbee booking integration as detailed in the .
Questions answered by the  can be found .
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 .
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 .
Delivery intervals check
This step is only for Budbee Home. More info can be found in .
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 .
Order creation
Budbee uses the same endpoint to create orders for both Budbee Home and Budbee Box. The DLVBOXproduct code is expected incase of box deliveries. More info can be found in .
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 .
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 .
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 .
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 .
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  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 .
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 .
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.


<MermaidChart
heading="Budbee Home"
chart={graph TD;     A[Start] --> B[Delivery postcode validation]     B -->|Output: Validated postcode| C[Requesting delivery intervals]     C -->|Output: Chosen interval| D[Note: Save chosen interval]     D --> E[Checkout]     E --> F[Creating an order]     F -->|Output: Order ID| G[Note: Save Order ID]     G --> H[Adding parcels]     H -->|Output: Label| I[Note: Save Label]     I --> J[End]}
/>


<MermaidChart
heading="Budbee Box"
chart={graph TD;     A1[Start] --> B1[Requesting valid lockers]     B1 -->|Output: Selected box| C1[Note: Save selected box]     C1 --> D1[Checkout]     D1 --> E1[Creating an order]     E1 -->|Output: Order ID| F1[Note: Save Order ID]     F1 --> G1[Adding parcels]     G1 -->|Output: Label| H1[Note: Save Label]     H1 --> I1[End]}
/>


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 to pdf, but can be changed to zpl)
documentSize (hardcoded to 10x15, but can be changed to the required size)

More information can be found in .
Tracking
Budbee offers a tracking endpoint that can be used to fetch a tracking link for a shipment. More info can be found in .
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 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|

Booking

In the below diagram, we illustrate how the integration
between Skrym and Budbee works for fetching the shipment events.
You can read more about their various events in the .
<MermaidChart
title="Tracking Events Flow"
subtitle="This illustrates how Skrym receives events from Budbee. Note that the retailer needs to configure access for Skrym in the Budbee portal."
chart="
sequenceDiagram
autonumber
participant MsgConsumer as Consumer
create participant Retailer as Retailer
MsgConsumer ->>+Retailer: Places order
Note over Retailer: Picking & Packing
create participant Skrym as Skrym
Retailer ->>Skrym: Initialize tracking
create participant Budbee as Budbee
Retailer ->>+Budbee: Create order
Budbee ->>Retailer: Pickup
  Note over Budbee: Retailer must add Skrym as<br/> subscriber to Budbee events
  Budbee->>+Skrym: Event Webhook
  Note over Skrym: Analyze/translate event
  Skrym->>Retailer: Event Webhook
  Retailer-->>MsgConsumer: Notification (e-mail/SMS)

  Budbee->>-MsgConsumer: Delivery

"
/>

Budbee event structure
Budbee uses a structure for their events. The basis of the structure that every event contains.
The header contains some identifying information:
Headers
Authorization: basic auth or OAuth2
Budbee-Event: Name of event to trigger webhook
Budbee-Event-ID: ID of the event (Corresponds to the `key` in the `event` table)
Content-Type: application/json
Timestamp: time of event trigger


Body
{
  "event": "GENERIC_EVENT",
  "eventData": {
    "tmsId": "ABCD",
    "cartId": "1234",
    "budbeeOrderToken": "a75dd44k",
    "shipmentId": "0000A5464644",
    "packageId": "3573847654593475837465345"
  }
}

Budbee also adds some additional information for some of the events, such an example can be the CHANGED_TO_LOCKER_DELIVERY that contains the lockers locations and name as well as the reason and responsible party for creating the event.

  The Webhooks we receive are on a parcel-by-parcel level, meaning that we
  register one event for each parcel. This means that every Budbee event that we
  store, has a `parcelD` stored as a `trackingReference` instead of a
  `shipmentID`

{
  "event": "CHANGED_TO_LOCKER_DELIVERY",
  "eventData": {
    "tmsId": "ABCD",
    "cartId": "1234",
    "budbeeOrderToken": "a75dd44k",
    "shipmentId": "0000A5464644",
    "packageId": "3573847654593475837465345",
    "reason": "Not home during expected delivery",
    "responsible": "CONSUMER",
    "street": "longstreet 321",
    "postalCode": "123 45",
    "city": "capital of nowhere",
    "lockerName": "The convenient locker"
  }
}
