# Scurri Platform API

This API allows you to manage consignments, including creating, updating, and retrieving details about shipments including labels and customs invoices.

## Authentication
All requests must be authenticated using either Basic Auth or API token-based authentication. If you have been provided with an API token, you should use token-based authentication.

### API Token
With API token-based authentication, you must include the token in the Authorization header as an API token, e.g. Authorization: token YOUR_API_TOKEN.
Failed requests will return a 401 HTTP code with WWW-Authenticate: Basic response header.


### Basic Auth
With Basic Auth, you have to send the username and password base64-encoded in the standard Basic manner, e.g. Authorization: Basic YXBpdGVzdDphcGkgcGFzc3dvcmQgdGVzdA==.

Here is some sample code in Python to generate the value of the header:
```python`
> import base64
> username = 'apitest'
> password = 'api-test-password'
> print(base64.b64encode((username + ':' + password).encode()).decode())
YXBpdGVzdDphcGktdGVzdC1wYXNzd29yZA==
```


Version: 1.0.0

## Servers

Scurri Sandbox Environment
```
https://sandbox.scurri.co.uk
```

## Security

### TokenAuth

Token-based authentication. Use 'token <your_token>' as the value.

Type: apiKey
In: header
Name: Authorization

## Download OpenAPI description

[Scurri Platform API](https://docs.scurri.com/_bundle/connect/consignments-api/versions/1.0.0/openapi.yaml)

## Carriers

The Carriers API allows you to query Scurri for the carriers that are enabled in your account.

The result contains the identifier for each carrier, which you can use in the rest of the API calls, whenever a Carrier needs to be specified. 
The identifier will never change, so this can be called once to get the values.


### List Available Carriers

 - [GET /_api/v1/company/{company_slug}/carriers](https://docs.scurri.com/connect/consignments-api/versions/1.0.0/openapi/carriers/list_available_carriers.md): List all the carriers for the logged in user

## Carrier Services

The Carrier Services API allows you to query Scurri for the services that are available for each carrier.

The result contains the identifier for each service, which you can use in the rest of the API calls, whenever a Carrier Service needs to be specified.


### List Available Carrier Services

 - [GET /_api/v1/company/{company_slug}/carrierservices](https://docs.scurri.com/connect/consignments-api/versions/1.0.0/openapi/carrier-services/list_available_carrier_services.md): List all the carrier services for the logged in user

## Warehouses

The Warehouses API allows you to retrieve a list of warehouses that you have access to (within a company).

The result contains the identifier for each warehouse, which you can use in the rest of the API calls, whenever a **Warehouse** needs to be specified.


### List Available Warehouses

 - [GET /_api/v1/company/{company_slug}/warehouses](https://docs.scurri.com/connect/consignments-api/versions/1.0.0/openapi/warehouses/list_available_warehouses.md)

## Consignments

This group of API calls allow you to interact with your consignments in Scurri. You can list and
search through them, create new ones, update existing ones, and retrieve their details. To see consignment documents, go to the **Consignment Documents** section.


### List all consignments

 - [GET /_api/v1/company/{company_slug}/consignments](https://docs.scurri.com/connect/consignments-api/versions/1.0.0/openapi/consignments/listconsignments.md): You can use this API call to retrieve the list of consignments in Scurri.

Pagination is provided via the offset and limit GET parameters.

For the offset, we don't use an integer value but instead use the last identifier of the current batch. The next value returned with the response body contains a URL you can use to retrieve the next batch.

Example offset URL: https://sandbox.scurri.co.uk/api/v1/company/test-company/consignments/?offset=000ed1bfb93c43319ec79247f50dfd3c

You can also use this API call to search for consignments using specific criteria, either for a specific identifier or for consignments of a specific status. Searching by identifier only returns a single consignment. 

The Despatched, Delivered and Exception statuses are only available if Tracking has been enabled on your account.

### Import a new consignment

 - [POST /_api/v1/company/{company_slug}/consignments](https://docs.scurri.com/connect/consignments-api/versions/1.0.0/openapi/consignments/importconsignment.md): Creates a new consignment (shipment) for the company. The consignment can be allocated or unallocated, domestic or international.

### Get consignment details

 - [GET /_api/v1/company/{company_slug}/consignment/{shipmentIdentifier}](https://docs.scurri.com/connect/consignments-api/versions/1.0.0/openapi/consignments/getconsignmentdetails.md): Retrieves details of a specific consignment (shipment).

### Update a consignment

 - [PUT /_api/v1/company/{company_slug}/consignment/{shipmentIdentifier}](https://docs.scurri.com/connect/consignments-api/versions/1.0.0/openapi/consignments/updateconsignment.md): Updates a consignment. Can be used to allocate or unallocate the consignment.

### Cancel a consignment

 - [DELETE /_api/v1/company/{company_slug}/consignment/{shipmentIdentifier}](https://docs.scurri.com/connect/consignments-api/versions/1.0.0/openapi/consignments/cancelconsignment.md): Cancels a consignment, taking any necessary actions on the carrier side

## Consignment Documents

You can use this API call to get the label and any customs invoice documents required for a specific consignment, if required.

Keep in mind that a label will be created for each package of the consignment.
## Available label formats
The resulting documents are returned as strings within the JSON response. These are plaintext in the case of ZPL labels, all other formats are base64-encoded binary files. 
Labels can be provided in the following formats:
- PDF: One PDF returned with multiple labels concatenated in a single document (one label per page)
- ZPL: Can be configured as 230 or 300 DPI resolution. It's also possible to specify the required label resolution or compress the label in the request.
- PNG: A ZIP file is returned containing all files
- PNG list: Single file PNGs (non-zipped)


Alternative label formats are also available, for example 8"x4". To enable this feature on your account, contact Scurri support. Once enabled the label customisation parameter can be used.

The label format can be specified in the `documenttype` query parameter, which can take the following values:
- PDF: `application/pdf`
- ZPL: `application/x-zebra-zpl`
- PNG: `image/png`
- PNG list: `image/x-png-list`

## Customs Invoice Documents

Scurri will return the documents the carrier requires, only if the carrier does require them for the specific consignment.Another thing to note about customs invoice documents is that they can be either in a **6"x4"** size (for thermal printer) or in an **A4** size (for a document printer). Your account can be configured, so that **6"x4"** thermal invoices can be concatenated with the respective label. This makes it easier to send each file to the correct printer. Note that setting documenttype to `application/x-zebra-zpl` only impacts labels, not invoices - they remain PDF as they are A4.

## Natively Supported ZPL Carriers
- An Post
- Colissimo
- Deutsche Post
- DPD
- DPD Germany  
- DPD Ireland
- DX  
- Fastway
- Generic Carrier
- Hermes
- Interlink  
- ITD Carrier
- P2P Trakpak  
- ParcelForce  
- PostNL  
- Royal Mail
- Spring Global  
- TNT  
- Tuffnells  
- UKMail
- Yodel


### Get consignment documents

 - [GET /_api/v1/company/{company_slug}/consignment/{shipmentIdentifier}/documents](https://docs.scurri.com/connect/consignments-api/versions/1.0.0/openapi/consignment-documents/getconsignmentdocuments.md): Retrieves documents (e.g., labels) for a consignment. Supports filtering by document type and invoice quantity.

## Manifests

The manifest process marks a list of consignments as ready to be picked up by the carrier.
A manifest always refers to a specific warehouse and carrier. Scurri abstracts away the necessary actions and documentation
 a carrier needs and presents a common interface for the manifest process.

The endpoints in this section allow you to create a manifest for given consignments, and retrieve any relevant documents


### Create a new manifest

 - [POST /_api/v1/company/{company_slug}/manifest](https://docs.scurri.com/connect/consignments-api/versions/1.0.0/openapi/manifests/createmanifest.md): Initiates the manifest process for a given carrier and warehouse, specifying the consignments to include in the manifest.

### Get documents for a specific manifest

 - [GET /_api/v1/company/{company_slug}/manifest/{manifest_id}/documents](https://docs.scurri.com/connect/consignments-api/versions/1.0.0/openapi/manifests/getmanifestdocuments.md): You can use this API call to get the manifest documentation (as an A4-size PDF file) that you need to hand-in to the carrier.

Scurri will return the correct documentation for the specified carrier.

Keep in mind that, because the document generation is kicked off asynchronously by the previous API call, the documents may 
not be ready, when you execute this API call. In that case, you should retry after a while.