Instabox

Instabox currently provides support for tracking in the form of a webhook that Skrym can subscribe to.
At the moment, Instabox only supports adding one subscriber to the webhook, meaning that if you are already sending
the events to another system, there are one of two workarounds:

Skrym forwards the events to the other system
The other system forwards the events to Skrym

Both these solutions are possible, but the first one is the most common and easier to set up.
We are of course hoping that with the current merger of Instabox and Budbee, the tracking will be improved and that
it will become possible to add multiple event subscribers.
Inferring transport method from events
Skrym will infer if it is a Box or Home Delivery based on the events, since there are events that are specifically tied to the methods, for example:

CustomerPickupCheckpoint: Picked up at locker by customer
CustomerHomeDeliverySuccess: Home delivery was successfull, parcel is delivered to customer

Setting up the integration
To set up the integration, you need to contact Instabox and ask them to add Skrym as a subscriber to the webhook.
You should include the following details in the email:

The URL to the Skrym webhook: https://api.skrym.com/tracking.InstaboxTrackingWebhook

At the moment, Instabox does not support using authentication for the webhook, so you do not need to provide any authentication details.
If Instabox asks you to use authentication details, please contact Skrym for further instructions.

Tracking

This page lists the results from the requirements analysis phase of the Instabox booking integration as detailed in the .
Transport methods endpoints
Availability
One API for all transport methods. API takes in a Service Code to differentiate between the transport methods. It is possible to do availability checks for multiple transport methods with a single call by passing in multiple service codes. More info can be found in .
Prebooking
One API for all transport methods. Instabox requires a prebooking to be registered after an order is confirmed in the checkout. This is usually when a customer clicks on complete purchase, meaning that the payment has gone through in the checkout. More info can be found in .
Order creation
One API for all transport methods. Preferably called after an order has been packed. More info can be found in .
Return enabling
One API for all transport methods, and the same URL as the order creation. This API is called after a successful booking request and enables a user to create a return from the Instabox portal.
This can always be called, even though the retailer has not enabled returns with Instabox. More info can be found in .
Booking a pickup
Instabox does not expose any specific APIs for scheduling pickups. However, they do indicate that they will use agreed upon pickup times for availability checks, which implies that a merchant can register pickups with Instabox on their side.
Shipment Information
These are the mandatory shipment information fields that Instabox expects when making a booking:

Delivery Address

Country code: string
Street: string
Postal code: string


Sender details

Name: string
Street: string
Postal code: string
City: string
Country code: string


Their service code for which transport method is used : string
A sort code indicating which Instabox pickup point is applicable: string
Order ID: string
Parcel ID: string (this field has specific constraints on how it should be generated)
Availability token: string
Package details

Width: float
Height and Depth (or) Diameter: float



There are a few other fields that they recommend and strongly recommend, but aren't mandatory as well as ones that are semi-required based on other fields. They also have better More info can be found in .
Label Creation
Instabox has a specific order creation endpoint that can be used to get labels after a booking has been made. For this, the parcel ID (as provided in the booking) for which the label is required should be provided. More info can be found in  under Label Endpoint v1.
Handling Unavailable Destinations
Home deliveries
Instabox's  takes in destination details and provides details accordingly. It should sufficiently handle problematic destinations.
Locker deliveries
In case of locker/service point deliveries, we can also double-check that the closest location suggested by Instabox is within a given threshold to avoid unsuitable options being chosen. This is however not a concern during booking, but more so in the checkout stage.
More information can be found in .
Cancellations
No mention about cancellations in the documentation. It is therefore assumed that Instabox does not support cancellation of orders that have already been placed. Can double-check in .
Booking a shipment
These are the following steps that must be taken to make a successful booking with Instabox:

Availability check : in checkout

Store availability token from the chosen option


Prebooking: after exiting checkout phase

Returns a promised ETA that can be saved if needed


Order creation: in warehouse
Enable returns: after successful booking and delivery

Enables a user to create a return from the Instabox portal



Instabox specific booking requirements
Instabox allows only a single parcel to be shipped per shipment. This is validated through the Instabox specific
validation function.
Creating a label and storing a label
Instabox has a specific order creation endpoint that can be used to get labels after a booking has been made as mentioned in the labels section.
It takes in a lot of different fields as input allowing for the most suitable type of label to be generated. These fields include:

format: default: pdf. Can choose between pdf and png
template: default: a6. Can choose between a6 and a7

More info can be found in  under Label Endpoint v1.
The labels created when making a booking with instabox are a combination of the following: parcel id, format and template. In total there will be four different labels stored in the database for the same order where it is a combination
of parcel id each time then either pdf or png and then either a6 or a7.
The following data is stored in the database for each label:

Data

A byte array of the label image


Label

ObjectPath: freightObjectId.format.fileName this is Instabox specific because there are multiple formats that it can be.
FreightObjectId: the id of the booking
Format: the format of the label, for Instabox this is either pdf or png.
Size: Instabox return either "a6" or "a7"
Content type: this denotes the file format the label image is saved in. Instabox is either application/pdf or image/png
CreatedAt: the time the label was created



Customs/Tolls
No mention in the documentation of how this is handled. Can double-check in .
Addons
Delivery Settings
| Setting                 | Type        | Required/Semi-Required/Optional | Allowed Values                           |
| ----------------------- | ----------- | ------------------------------- | ---------------------------------------- |
| leave_by_door         | Boolean     | Optional                        |                                          |
| door_code             | String      | Optional                        |                                          |
| delivery_instructions | String      | Optional                        |                                          |
| notify_by             | String Enum | Optional                        | RING_DOORBELL, KNOCK_ON_DOOR, NONE |
Identification Options
| Setting                          | Type        | Required/Semi-Required/Optional | Allowed Values                                                     |
| -------------------------------- | ----------- | ------------------------------- | ------------------------------------------------------------------ |
| type                           | String Enum | Required                        | ALREADY_IDENTIFIED, ANY_PERSON, AGE_LIMIT, SPECIFIC_PERSON |
| verify_person_using            | String Enum | Semi-required                   | national_ identification_ number                                 |
| minimum_age                    | Integer     | Semi-required                   |                                                                    |
| national_identification_number | String      | Semi-required                   |                                                                    |
The type addon
The type addon is special in the sense that it is related to other addons and makes some of then sem-required. The below flowcharts demonstrate how the different values for addon type affects other addons
<MermaidChart
heading="ALREADY_IDENTIFIED Flow"
chart={graph TD;     Start[Identification Type = Already Indentified] --> End[End: Person already verified];}
/>
<MermaidChart
heading="ANY_PERSON Flow"
chart={graph TD;     Start[Identification Type = Any Person] --> End[End: Any person can identify];}
/>
<MermaidChart
heading="AGE_LIMIT Flow"
chart={graph TD;     Start[Identification Type = Age Limit] --> IsMinAgeDefined{Min Age Defined?};     IsMinAgeDefined -->|Yes| VerifyAge[End: Verify age];     IsMinAgeDefined -->|No| End[End: Error];}
/>
<MermaidChart
heading="SPECIFIC_PERSON Flow"
chart={graph TD;     Start[Identification Type = Specific Person] --> IsVerifyPersonUsingDefined{Verify Person Using exists};     IsVerifyPersonUsingDefined -->|Yes| WhatIsVerifyPersonUsing[Verify person using national ID];     IsVerifyPersonUsingDefined -->|No| End[End: Error];     WhatIsVerifyPersonUsing -->IsNationalIdDefined{national ID defined};     IsNationalIdDefined -->|Yes| VerifyNationalID[End: Verify with National ID];     IsNationalIdDefined -->|No| End[End: Error];}
/>
Addon Mapping
Delivery Settings
These addons are only applicable for Instabox home delivery ("INSTAHOME"):
| Instabox addon          | Skrym addon                        | Addon type | Description                                                                                   |
| ----------------------- | ---------------------------------- | ---------- | --------------------------------------------------------------------------------------------- |
| leave_by_door         | leave-outside-door               | boolean    | Is it ok to leave shipment outside door if recipient is not at home                           |
| door_code             | door-code                        | number     | Entry code to door                                                                            |
| delivery_instructions | additional-delivery-instructions | string     | Additional info to transporter regarding shipment                                             |
| notify_by             | notify-home-delivery-by          | enum       | How the courier should notify their arrival. enum: RING_DOORBELL, KNOCK_ON_DOOR or NONE |
Identification Options
These addons are applicable for Instabox Home Delivery and Locker Delivery ("INSTAHOME", "EXPRESS" and "COLLECT_IN_STORE"):
| Instabox addon           | Skrym addon                     | Addon type | Description                    |
| ------------------------ | ------------------------------- | ---------- | ------------------------------ |
| identification_options | identification-by-minimum-age | object     | Identify by age                |
| identification_options | identification-by-national-id | object     | Identify by national id number |
The following object notation is stored in addon_object 