Introduction

Welcome to Swepelago Partner API Docs. This API is used to access Swepelago API endpoints, which is used for placing and managing orders.

You can find the overview, menu and search to left. Examples will be to the right.

Get started by clicking Authentication in the menu to the left.

Changelog

Version 0.1.6b (current)

2019-03-10
- Added TLS to all endpoints (https). Old endpoints will still work but will be redirected to https.

Version 0.1.5b

2018-07-29
- Order validations
- Removed time lock on Orders & Packages. Instead they are now locked when the order has been planned. (Order.status = CONFIRMED)
- Corrections in documentation:
-- Order.latitude -> Order.receiverLatitude
-- Order.longitude -> Order.receiverLongitude
-- Removed trackingId from Order, it only exists on Packages

Authentication

First you need to call the /auth endpoint to get an access token:

curl "https://api.swepelago.se/v1/partner/auth"
  -X POST
  -D '{
        "email": "test@example.com",
        "password": "myPassword123"
      }'

The above command returns JSON structured like this:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyIxIjoiMSJ9.6nGeRjbkt5ww8lhPe_Uycm_S1E0CvuzwRTVSbh1Sz3c",
  "user": {
    "id": 1,
    "email": "michael@example.com",
    "name": "Michael Hedström",
    "phone": "0700000000",
    "organisationId": 1,
    "organisation": {
      "id": 1,
      "organisationNumber": "559094-5688",
      "name": "SwePelago AB",
      "address": "Götgatan 1",
      "city": "Stockholm",
      "postalCode": "11646",
      "reference": "Michael Hedström"
    }
  },
  "expires": "1523559633"
}

# And then you just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: Bearer <AccessToken>"

Make sure to replace <AccessToken> with your personal access token.

We use access tokens to allow access to the API. To retrieve a token you must first have an account. For more information about becoming a Swepelago Partner, please visit our partner page.

Before accessing any other endpoint, you must first fetch an access token from this endpoint using your email and password.

Our API expects for the access token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer <AccessToken>

HTTP Request

POST https://api.swepelago.se/v1/partner/auth

Body Parameters

Parameter	Description
email	Email of your Swepelago Partner-account
password	Password of your Swepelago Partner-account

Orders

Orders are the main objects of the API and will contain information about when and how to deliver associated Packages. Below are the methods we provide for Creating, Reading, Updating and Deleting orders.

Create an Order

curl "https://api.swepelago.se/v1/partner/orders"
  -X POST
  -H "Authorization: Bearer <AccessToken>"
  -D '{
        "externalId": "78388",
        "deliveryDate": "2018-06-17",
        "messageToCaptain": "",
        "messageToAdmin": "",
        "receiverName": "Michelangelo",
        "receiverEmail": "michelangelo@swepelago.se",
        "receiverPhone": "+46701335161",
        "receiverLatitude": "59.295503",
        "receiverLongitude": "18.710280",
        "verifyIdentity": false,
        "verifyAge": 18,
        "packages": [
          {
            "type": "SMALL",
            "trackingId": "943110093",
            "transport": "CHILLED",
            "weight": "9000",
            "width": "100",
            "height": "100",
            "depth": "75"
          },
          {
            ...
          }
        ]
      }'

The above command returns the created order JSON structured like this:

{
  "id": 2,
  "externalId": "78388",
  "status": "RECEIVED",
  "deliveryDate": "2018-06-17",
  "messageToCaptain": "",
  "messageToAdmin": "",
  "receiverName": "Michelangelo",
  "receiverEmail": "michelangelo@swepelago.se",
  "receiverPhone": "+46701335161",
  "receiverLatitude": "59.295503",
  "receiverLongitude": "18.710280",
  "verifyIdentity": false,
  "verifyAge": 20,
  "createdAt": "2018-06-16 16:35:23+0200",
  "updatedAt": "2018-06-16 16:35:23+0200"
}

This endpoint creates an order. Each order has one or more packages to be delivered and you may optionally add these Packages when creating the order.

HTTP Request

POST https://api.swepelago.se/v1/partner/orders

URL Parameters

None

Body Parameters

Parameter	Description
externalId	Partner's internal id
deliveryDate	Wanted delivery date for the order
messageToCaptain	A message to captain of the boat delivering the order
messageToAdmin	A message to the Swepelago administrator that plan routes etc
receiverName	Recipient of the packages in the order
receiverEmail	Email of the recipient
receiverPhone	Phone number of the recipient
receiverLatitude	Delivery location
receiverLongitude	Delivery location
verifyIdentity	Identity verification of the recipient performed by the captain. Possible values: `true`, `false`. If this value is `true`, the recipient's name must match the name in receiverName
verifyAge	Age verification of the recipient performed by the captain. Integer. Defaults to `0` (meaning no age verification)
packages	An array of Packages which will be associated with the order

Validations

Parameter	Description
externalId	Required, Unique per partner
deliveryDate	Cannot be earlier than today
messageToCaptain	Max length 999
messageToAdmin	Max length 999
receiverEmail	Well formatted email address
receiverPhone	Not null
receiverLatitude	Number between -90 and 90
receiverLongitude	Number between -180 and 180

Get All Orders

curl "https://api.swepelago.se/v1/partner/orders"
  -H "Authorization: Bearer <AccessToken>"

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "externalId": "78362",
    "status": "DELIVERED",
    "deliveryDate": "2018-06-15",
    "messageToCaptain": "The dock with a yellow boat",
    "messageToAdmin": "",
    "receiverName": "Rembrandt",
    "receiverEmail": "rembrandt@swepelago.se",
    "receiverPhone": "+46704936169",
    "receiverLatitude": "18.707720",
    "receiverLongitude": "59.290591",
    "verifyIdentity": false,
    "verifyAge": 0,
    "createdAt": "2018-06-14 11:29:42+0200",
    "updatedAt": "2018-06-14 12:48:06+0200"
  },
  {
    "id": 2,
    "externalId": "78388",
    "status": "RECEIVED",
    "deliveryDate": "2018-06-17",
    "messageToCaptain": "",
    "messageToAdmin": "",
    "receiverName": "Michelangelo",
    "receiverEmail": "michelangelo@example.com",
    "receiverPhone": "+46701335161",
    "receiverLatitude": "18.710280",
    "receiverLongitude": "59.295503",
    "verifyIdentity": false,
    "verifyAge": 18,
    "createdAt": "2018-06-16 16:35:23+0200",
    "updatedAt": "2018-06-16 16:35:23+0200"
  }
]

This endpoint retrieves all orders.

HTTP Request

GET https://api.swepelago.se/v1/partner/orders

Query Parameters

Parameter	Default	Description
includePackages	false	If set to true, the result will also include order packages.

Get specific Order

curl "https://api.swepelago.se/v1/partner/orders/2"
  -H "Authorization: Bearer <AccessToken>"

The above command returns JSON structured like this:

{
  "id": 2,
  "externalId": "78388",
  "status": "RECEIVED",
  "deliveryDate": "2018-06-17",
  "messageToCaptain": "",
  "messageToAdmin": "",
  "receiverName": "Michelangelo",
  "receiverEmail": "michelangelo@example.com",
  "receiverPhone": "+46701335161",
  "receiverLatitude": "18.710280",
  "receiverLongitude": "59.295503",
  "verifyIdentity": false,
  "verifyAge": 18,
  "createdAt": "2018-06-16 16:35:23+0200",
  "updatedAt": "2018-06-16 16:35:23+0200"
}

This endpoint retrieves a specific order.

HTTP Request

GET https://api.swepelago.se/v1/orders/<ID>

URL Parameters

Parameter	Description
ID	The ID of the order to retrieve

Update an Order

curl "https://api.swepelago.se/v1/partner/orders/2"
  -X PATCH
  -H "Authorization: Bearer <AccessToken>"
  -D '{
        "receiverName": "Leonardo da Vinci",
        "receiverEmail": "davinci@swepelago.se"
      }'

The above command returns the updated JSON structured like this:

{
  "id": 2,
  "externalId": "78388",
  "status": "RECEIVED",
  "deliveryDate": "2018-06-17",
  "messageToCaptain": "",
  "messageToAdmin": "",
  "receiverName": "Leonardo da Vinci",
  "receiverEmail": "davinci@swepelago.se",
  "receiverPhone": "+46701335161",
  "receiverLatitude": "18.710280",
  "receiverLongitude": "59.295503",
  "verifyIdentity": false,
  "verifyAge": 18,
  "createdAt": "2018-06-16 16:35:23+0200",
  "updatedAt": "2018-06-16 16:35:23+0200"
}

This endpoint partially updates a specific order.

Orders and packages can only be updated/deleted when Order.status is RECEIVED.

HTTP Request

PATCH https://api.swepelago.se/v1/partner/orders/<ID>

URL Parameters

Parameter	Description
ID	The ID of the order to update

Body Parameters

Parameter	Description
externalId	Partner's internal id
deliveryDate	Wanted delivery date for the order
messageToCaptain	A message to captain of the boat delivering the order
messageToAdmin	A message to the Swepelago administrator that plan routes etc
receiverName	Recipient of the packages in the order
receiverEmail	Email of the recipient
receiverPhone	Phone number of the recipient
receiverLatitude	Delivery location
receiverLongitude	Delivery location
verifyIdentity	Identity verification of the recipient performed by the captain. Possible values: `true`, `false`. If this value is `true`, the recipient's name must match the name in receiverName
verifyAge	Age verification of the recipient, performed by the captain. Integer. Defaults to `0` (meaning no age verification)

Delete an Order

curl "https://api.swepelago.se/v1/partner/orders/2"
  -X DELETE
  -H "Authorization: <Token>"

The above command will respond with HTTP status 200.

This endpoint deletes a specific order.

Orders and packages can only be updated/deleted when Order.status is RECEIVED.

HTTP Request

DELETE https://api.swepelago.se/v1/partner/orders/<ID>

URL Parameters

Parameter	Description
ID	The ID of the order to delete

Update order status

curl "https://api.swepelago.se/v1/partner/orders/status?externalId=1234567&status=DELIVERED"
  -X POST
  -H "Authorization: Bearer <AccessToken>"

The above command returns 200 - OK if successful, otherwise error

This endpoint allows partners to update the status of their own orders. Only orders with status PLANNED or ON_ROUTE can be updated.

HTTP Request

POST https://api.swepelago.se/v1/partner/orders/status

Query Parameters

Parameter	Description
externalId	Partner's internal order id
status	New status. Possible values: `DELIVERED`, `RETURNED`

Packages

Create a Package

curl "https://api.swepelago.se/v1/partner/orders/2/packages"
  -X POST
  -H "Authorization: Bearer <AccessToken>"
  -D '{
        "type": "SMALL",
        "trackingId": "943110093",
        "transport": "CHILLED",
        "weight": "9000",
        "width": "100",
        "height": "100",
        "depth": "75"
      }'

The above command returns the updated JSON structured like this:

{
  "id": 1,
  "orderId": 2,
  "type": "SMALL",
  "trackingId": "943110093",
  "status": "INFORMATION",
  "transport": "CHILLED",
  "classification": null,
  "weight": "9000",
  "width": "100",
  "height": "100",
  "depth": "75",
  "createdAt": "2018-06-16 16:36:23+0200",
  "updatedAt": "2018-06-16 16:36:23+0200"
}

This endpoint creates a package and associates it to an Order.

Each order has one or more packages to be delivered and you may also add these Packages when creating the order.

HTTP Request

POST https://api.swepelago.se/v1/partner/orders/<OrderID>/packages

URL Parameters

Parameter	Description
OrderID	ID of the order the package should be associated with

Body Parameters

Parameter	Description
type	Description of the package size. Possible values: `SMALL`, `MEDIUM`, `LARGE`, `UNKNOWN` (default)
trackingId	If omitted, this will be automatically generated. This value cannot be changed after creation.
transport	Transportation requirement. Possible values: `DRY` (default), `CHILLED`, `FROZEN`
classification	Reserved for future use
weight	Weight of the package in grams
width	Width of the package in centimeters
height	Height of the package in centimeters
depth	Depth of the package in centimeters

Get All Packages

curl "https://api.swepelago.se/v1/partner/orders/2/packages"
  -H "Authorization: Bearer <AccessToken>"

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "orderId": 2,
    "type": "SMALL",
    "trackingId": "943110093",
    "status": "INFORMATION",
    "transport": "CHILLED",
    "classification": null,
    "weight": "9000",
    "width": "100",
    "height": "100",
    "depth": "75",
    "createdAt": "2018-06-16 16:36:23+0200",
    "updatedAt": "2018-06-16 16:36:23+0200"
  },
  {
    ...
  }
]

These endpoints retrieves all packages, overall or for a specific OrderID.

HTTP Request

GET https://api.swepelago.se/v1/partner/orders/<OrderID>/packages GET https://api.swepelago.se/v1/partner/packages

URL Parameters

Parameter	Description
OrderID	The ID of the Order that the packages belong to

Get specific Package

curl "https://api.swepelago.se/v1/partner/orders/2/packages/1"
  -H "Authorization: Bearer <AccessToken>"

The above command returns JSON structured like this:

{
  "id": 1,
  "orderId": 2,
  "type": "SMALL",
  "trackingId": "943110093",
  "status": "INFORMATION",
  "transport": "CHILLED",
  "classification": null,
  "weight": "9000",
  "width": "100",
  "height": "100",
  "depth": "75",
  "createdAt": "2018-06-16 16:36:23+0200",
  "updatedAt": "2018-06-16 16:36:23+0200"
}

This endpoint retrieves a specific package.

HTTP Request

GET https://api.swepelago.se/v1/partner/packages/<ID>

URL Parameters

Parameter	Description
ID	The ID of the package

Update a Package

curl "https://api.swepelago.se/v1/partner/packages/1"
  -X PATCH
  -H "Authorization: Bearer <AccessToken>"
  -D '{
        "transport": "FROZEN"
      }'

The above command returns the updated JSON structured like this:

{
  "id": 1,
  "orderId": 2,
  "type": "SMALL",
  "trackingId": "943110093",
  "status": "INFORMATION",
  "transport": "FROZEN",
  "classification": null,
  "weight": "9000",
  "width": "100",
  "height": "100",
  "depth": "75",
  "createdAt": "2018-06-16 16:36:23+0200",
  "updatedAt": "2018-06-16 16:36:23+0200"
}

This endpoint partially updates a specific package.

Orders and packages can only be updated/deleted when Order.status is RECEIVED.

HTTP Request

PATCH https://api.swepelago.se/v1/partner/packages/<ID>

URL Parameters

Parameter	Description
ID	The ID of the package to update

Body Parameters

Parameter	Description
type	Description of the package size. Possible values: `SMALL`, `MEDIUM`, `LARGE`, `UNKNOWN` (default)
transport	Transportation requirement. Possible values: `DRY` (default), `CHILLED`, `FROZEN`
classification	Reserved for future use
weight	Weight of the package in grams
width	Width of the package in centimeters
height	Height of the package in centimeters
depth	Depth of the package in centimeters

Delete a Package

curl "https://api.swepelago.se/v1/partner/packages/1"
  -X DELETE
  -H "Authorization: <AccessToken>"

The above command will respond with HTTP status 200.

This endpoint deletes a specific order package.

Orders and Packages can only be updated/deleted when Order.status is RECEIVED.

HTTP Request

DELETE https://api.swepelago.se/v1/partner/packages/<ID>

URL Parameters

Parameter	Description
ID	The ID of the package to delete

Errors

The Swepelago API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid. For example malformed request, missing or invalid parameter. Response body will include a failure description.
401	Unauthorized -- Your access token is either wrong or not provided.
403	Forbidden -- You do not have access to the resource.
404	Not Found -- The specified resource could not be found.
418	I'm a teapot.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.