Tailor Made

Before you start

Step 1: Set up

OAUTH_CLIENT_ID

Keep this value private and safe! This is your OAuth2 Client ID that you will use to authenticate with the Partner API.

OAUTH_CLIENT_SECRET

Keep this value private and safe! This is your OAuth2 Client Secret that you will use to authentica te with the Partner API.

API_URL

This is your Base URL for the Partner API, to which you will then append the relevant endpoint paths.

Step 2: Environments

Test / Stage

An environment with limited functionalities, where you can test the integration.

Production

Use this environment with caution, as it is live and connected to real end users.

Step 3: Process of requesting a delivery

Follow these steps to successfully request a delivery and perform other related actions:

3.1 Authenticate yourself /auth sessions

Authentication is based on OAuth 2.0 standard, Client Credentials grant.

In order to use the API, you must attach the access token to Authorization header as a Bearer token.

See an example of a successful integration:

POST /api/v1/ auth sessions

{

"grant_type”: "client_credentials”,

"client_id": “string”,

"client_secret": “string”

}

Status Code 200

{

"access_token”: “client_credentials”,

"token_type": “Bearer”,

"expires_in”: 3600

}

Further responses, which might occur:

400

The server cannot or will not process the request due to something that is perceived to be your error (e.g., not to spec request syntax, invalid request message). You are to modify the request before sending it again.

401

Not Authorized. You are either using an expired Access token to access the data or trying to initialize Auth session with invalid data.

403

Account disabled. Your account had been disabled, contact support.

3.2 List all available origins/origins

This call will list all available pick up point (PUP locations where BoxNow can pick up all your parcels from typically your warehouses.

You can list all your warehouses using /origins API call which has the same parameters as /destinations API call where you do not specify parameters latlng, radius or requiredSize, but you specify locationType as “warehouse”. You refer to this location by its ID (locationid).

Moreover there is one specific location called any-apm that can be listed by the same way and using locationType as “any-apm”, it returns just one location-any-apm. You can refer to it by its ID (locationid). Usage of this will be explained in the next section.

Below is the parameter availa ble for you to filter all Origin locations:

See an example of a successful integration:

GET /api/v1/ origins

curl -X ‘GET’\

'…/origins\

-H 'accept: application/json’

Status Code 200

{

"data": [

{

"id": "string",

"type": "warehouse",

"image": "https://via.placeholder.com/175",

"lat": "48.940819584637266",

"lng": "12.366962491028423",

"title": "Warehouse 1",

"name": "Main Warehouse",

"addressLine1": "ul.Tsar Boris III",

"addressLine2": "Sofia",

"postalCode": "1000",

"country": "BG",

"note": "Next to Super market"// can be null

}

]

}

Further responses, which might occur:

Error Code

400

The server cannot or will not process the request due to something that is perceived to be your error (e.g., malformed request syntax, invalid request message). You are to modify the request before sending it again.

401

Not Authorized. You are either using an expired Access token to access the data or trying to initialize Auth session with invalid data.

403

Account disabled. Your account had been disabled, contact support.

3.3. List all available destinations /destinations

This call will list all available APM (Automatic Parcel Machine) locations where we can deliver your parcel to.

Beloware the parameters available for you to filter all APM locations:

See an example of a successful integration:

GET api/v1/ destinations

curl X ‘GET’\

‘.../destinations\

-H 'accept: application/json'

Status Code 200

{

"data": [

{

"id": "string",

"type": "apm",

"image": "https://via.placeholder.com/150",

"lat": "48.78081955454138",

"lng": "12.446962472273063",

"title": "1842 - Building SIVEN, Hladilnika",

"name": "1842 - бул. Черни връх №47А, София, 1407",

"addressLine1": "bul. Cherni Vrah 47A",

"addressLine2": "string",

"postalCode": "1407",

"country": "BG",

"note": "You can find it behind the pet shop"

}

]

}

Alternatively, refer to section 4 for a Java Script snippet you can embed into your web to display all available APMs via a pop-up/iframe widget, or for a brief description of a successful custom map integration.

id

When requesting a delivery, you will refer to these records by id-More commonly:

locationId

Further responses, which might occur:

Error Code

400

The server cannot or will not process the request due to something that is perceived to be your error (e.g., malformed request syntax, invalid request message). You are to modify the request before sending it again.

401

Not Authorized. You are either using an expired Access token to access the data or trying to initialize Auth session with invalid data.

403

Account disabled. Your account had been disabled, contact support.

3.4 Request a delivery /delivery requests

Use this call to order a delivery of a parcel (or multiple parcels). This is the main call you will be using to create any type of delivery requests.

Once a successful request for delivery is made:

• (optional) We will send you an email notifying you of a successful delivery request creation with a PDF label attached. Parameter notifyOnAccepted needs to be populated for this function (See Appendix 6.3).
• (Described below) Alternatively, you should fetch the PDF label for each parcel using the GET/parcels/{id}/label.pdf call print it and stick it to the parcel(s).
• We will send a courier to pick up the parcel(s) at the agreed pick up times.
• We will also notify the customer that

1. We have received a delivery order and that a parcel will be delivered to them.
2. We have successfully delivered their parcel(s) to the specified destination APM with the necessary details for collecting the parcel(s).

See an example of a successful integration:

POST api/v1/ delivery requests

{

"orderNumber": “string”,

"invoiceValue": “25.50”,

"paymentMode":”prepaid”,

”amountToBeCollected": “0.00",

"allowReturn”: true,

"origin”:{

"contactNumber":“+3598XXXXXXXX”,

"contactEmail”: “[email protected]”,

"contactName": “Ivan Ivanov",

"locationId":”string”

},

“destination”:{

"contactNumber": "+3598XXXXXXXX”,

"contactEmail”: “[email protected]”,

"contactName” "Ivan Petrov",

"locationId":”string”

},

"items”: [

{

"id": “string”,

"name": “Smartphone”

"value”: “3.45”,

"weight”: 0

}

]

}

items: weight

If the parcel weight is unknown, pass 0.

These parameters are the main identifiers of pick up & delivery locations:

origin: locationId

The warehouse where the parcel will be picked up from.

destination: locationId

Automatic Parcel Machine (APM) where the parcel will be delivered to.

Also,

do not forget to pass us the following personal details with each delivery request:

Sender:

1. Name

Recipient:

1. Name
2. Phone number
3. Email

Status Code 200

{

"referenceNumber":”string”,

"parcels”:[

{

"id":”string”

}

]

}

Note:In the above example, the “items correspond to parcels, but item ID is eshop unique ID (reference number, if you will). If you do not have unique ID of each item then create it by order number combined with sequential item number or any other way. Whileparcel ID (parcels ID)is BoxNow internal unique ID used further to refer to the parcel.

For sending from APM you can use origin any APM and destination specific APM.

For delivering to APM where customer will pick up from the same APM you can use both origin and destination location any-APM.

Further responses, which might occur:

Error Code

400

Bad Request. The server cannot or will not process the request due to something that is perceived to be your error (e.g., malformed request syntax, invalid request message). You are to modify the request before sending it again.

401

Not Authorized. You are either using an expired Access token to access the data or trying to initialize Auth session with invalid data.

403

Account disabled. Your account had been disabled, contact support.

3.5 Fetch a PDF label /parcels/{id}/label.pdf

Use this call to request a .pdf file with a label you shoold print a stick onto each parcel.

Only this parameter is available to you:

    
<div id="boxnowmap"></div>
    
<script type="text/javascript">
    
var _bn_map_widget_config = {
    
partnerId: 123,
    
parentElement: "#boxnowmap"
    
afterSelect: function(selected){
    
alert(selected.boxnowLockerPostalCode);
    
    
alert(selected.boxnowLockerAddressLine1);
    
    
alert(selected.boxnowLockerId);

    
    
}
    
};
    
    
(function(d){var e = d.createElement("script");e.src = "https://widget-cdn.boxnow.bg/map-widget/client/v5.js";e.async = true;e.defer = true;d.getElementsByTagName("head")[0].appendChild(e);})(document);</script>

	

<div id="boxnowmap"></div>