Early Bird

This page lists the results from the requirements analysis phase of the postnord booking integration as detailed in this GitHub issue.
Questions answered by the  can be found .
The sources are the  as well as a  provided by Earlybird.
Booking flow & data types - general information
The Earlybird booking flow is relatively straight forward. There is an authentication phase, an address check, a booking request and an endpoint for fetching available add-on services.
The most intuitive flow would be to first authenticate, then check the address, then find available add-ons and finally make the booking. The data returned by the booking can be used for tracking directly.
All dates appear to be using RFC3339 with timezone.
<MermaidChart
heading="Earlybird shipment booking"
chart={graph TD;     A[Authenticate] -->|Authentication Success| B[Check Address]     B -->|Address Valid| C[Fetch Add-ons]     C -->|Add-ons Received| D[Make Booking]     D -->|Booking Success| E[Tracking] }/>

<MermaidChart
heading="Earlybird shipment booking"
chart={`sequenceDiagram
autonumber
participant S as Skrym
participant EB as Early Bird
S->>+EB: Authenticate
EB-->-S: OK
S->>+EB: Check Address
EB-->-S: OK
S->>+EB: Fetch Add-ons
EB-->-S: Add-ons[]
Note over EB: Add-ons include sms notification and ID-check
S->>+EB: Make Booking
EB-->-S: OK
S->>EB: Tracking
`}/>
Authentication
EarlyBird has two methods of authentication. We either store the retailer's credentials in the DB and use them to authenticate or use our own credentials stored in . If using our own credentials, we need to include the retailer's customer number in the request, where applicable. The latter method is simpler since we only need the customer number from the retailer.
The authentication process is the same for both methods. The /users/authenticate endpoint takes a username and password and returns a time-limited token that can be used in subsequent calls. So, before making any calls to the EarlyBird API, obtain a token and include it (together with the customer number if needed) in the request. We don't need to store the token anywhere since the next time we need to make a call or a series of calls, we can simply obtain a new token.
Address checking
Address checking via bookings/checkaddress should be done before booking. The fields and their specifications are as follows (from earlybird):

The endpoint also serves as Earlybird's availability fetch. It will respond with information about delivery windows, relevant terminals, distance and so on if the address is serviceable. If it isn't, several of these will be unpopulated - specifically the date and sortHub fields in the response.
Earlybird claim complete coverage of Sweden.
Booking pickups
No mentions of pickups or any booking which requires an explicit address for the sender.
Booking shipments
The senderbooking endpoint is called to book an order. It returns various data points pertaining to the booking - things which have technically already been returned by address/availability checks. However, it's worth noting that it may also return the bar codes to be put on labels, or the labels themselves ready to print, provided the relevant fields are set in the request. Said bar code can also be directly used for tracking.
None of the input parameters indicate that this endpoint can be used for pickups at multiple different locations merging into the same shipment, or that a shipment can even contain multiple packages.

Here are the fields for label printing:

On success, the senderbooking endpoint will return the label in the requested FileFormat as a base64 encoded string in the response.
Tracking link
The bar code returned by the call to senderbooking can be directly used as a tracking link by prepending https://earlybird.se/tracking/?id=.
Handling unavailable destinations
Earlybird claim complete coverage in Sweden. If Earlybird do not have coverage for a destination, the checkAddress call will simply not return a SortHub meaning the address is not serviceable.
Cancellations
Earlybird confirm there is no way to cancel bookings via their api.
Addons
EarlyBird's senderbooking endpoint does not explicitly dedicate a field for addons. Nevertheless, the currently supported skrym-addons can be mapped to the following fields in the senderbooking request body:
| Earlybird addon    | Type | Description                           | Required     | Skrym Addon |
|---------------|------|---------------------------------------|--------------|----------|
| package.eml   | Int | If notification by e-mail (1) – default 0 | Yes | email-notification |
| package.sms   | Int  | If notification by SMS (1) – default 0 | Yes | sms-notification |
| package.identification | Int  | If requires ID at delivery (1) (only for HEM) | No | identification-by-national-id |
| receiver.doorCode | string | The code to the door of the building | No | door-code |
| senderItem.SupplierMessage | string | Message to be put on the delivery note | No | additional-delivery-instructions |
| package.handOver | Int | If parcel requires hand over (1) (HEM) | No | require-signature |
| package.bankId | Int | If ID requires Bank-Id (1) (HEM) | No | identification-by-bank-id |
The booking/getadditions endpoint is connected to only 3 of these add-ons: the handOver, identification and bankId. Calling it with a customerNo and senderId, it returns bool for each of the 3 values signalling which of them are activated for the specific sender:
{
  "handOver": true,
  "identification": true,
  "bankId": true
}

These values are used for the Home Service (HEM with code 8930). If one specifies any one of them in the senderboking while not being activated for that sender and customer, the senderbooking endpoint will return an error.
Customs/Tolls
No information. Earlybird only operate within sweden, however they claim to ship "from Sweden" on their .
Booking Implementation
The actual booking logic in bookEarlybird in booking/earlybird.utils.go is slightly different than proposed above.
It start with authentication, providing the Bearer token to make any subsequent calls to EarlyBird, then checks if the booking can be made with the requested transport method to the request address by the caller, and if so makes the booking and extracts labels and tracking link.
The process can be summarized in the following flowchart:
<MermaidChart
heading="Earlybird booking"
chart={graph TD;     A[Authenticate] --> B[Check delivery options and set product code]     B --> C[Check enabled additions and address]     C --> D[Transform SkrymBooking to EarlyBird booking]     D --> E[Make the booking]     E --> F[Get labels and tracking link] }/>
The setting of product code (what EarlyBird calls their transport methods) works by getting all the deliver options for the requested address and caller, checking if the requested transport method is among them, and if not, it sets it to EarlyBird's standard 8900 method.
This is because 8900 seems to be the standard delivery method that is available for most addresses. If 8900 is not available then the booking will return error already at the validation step.
Validation
Before the booking reaches the handler (and thus bookEarlybird), it needs to pass general and EarlyBird-specific validation.
Notably, the EarlyBird-specific validation checks if the requested transport method can deliver to the address and if not it checks if 8900 is available to be used as fallback. If not, it will append an error.
There are also 3 special addons: IdentificationByNationalID, RequireSignature, IdentificationByBankId that need to be enabled by EarlyBird for each of their customers. The validation appends errors if the caller wants to apply any of these addons, but does not have the permission from EarlyBird to do so. This is so that shipments that are meant to be picked up by a specific person or need to check persons age don't get booked without those requirements.

Booking

Skrym regularly polls Early Bird in order to get the latest events for your shipments. These events are
then translated to the Skrym event structure, but the original events are also stored.
Inferring transport method from events
Skrym defaults to labelling Early Bird shipments as using their mailbox delivery service (Postlådeleverans).
However, if an event occurs that has an event code specific to the home delivery service, Skrym updates the transport
method for the shipment to instead be home delivery.
Setting up the integration
There is no setup required for the Early Bird integration. Skrym will automatically poll Early Bird for events for any
shipments booked with Early Bird.