Integration Essentials
Prerequisite
Please make sure that you have already read and followed the instructions mentioned here.
Limitations
Please make sure you have already read and are aware of:
Get Rate
Sample Request
curl --location --request POST 'https://api-sandbox.flashbox.co/scheduled-service/api/v1/requests/preview' \
--header 'Authorization: Bearer Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"pick_up_address": {
"text": "L6T5E5"
},
"drop_offs": [
{
"address": {
"text": "M5S1T8"
},
"parcels": [
{
"unit": "g",
"values": 5000
}
]
}
]
}'
Sample Response
{
"status": "success",
"code": 200,
"message": "Successfully done.",
"object": {
"pick_ups": [
{
"address": {
"saved_address_id": null,
"lat": "43.7199132",
"lng": "-79.6765217",
"text": "L6T5E5",
"city": "gta",
"person_name": null,
"person_phone_country_code": null,
"person_phone": null,
"plate_number": null,
"unit_number": null,
"postal_code": "l6t 5e5",
"description": null
},
"scheduled_date": "2022-08-12",
"time_slot_code": "10am-2pm",
"time_slot": {
"city": "gta",
"code": "10am-2pm",
"name": "10:00 AM - 2:00 PM",
"closing_margin": 0,
"from_time": 1050,
"to_time": 1170
},
"time_slot_datetime_start": "2022-08-12T17:30:00+00:00",
"time_slot_datetime_end": "2022-08-12T19:30:00+00:00",
"drop_offs": [
{
"address": {
"text": "M5S1T8",
"postal_code": "m5s 1t8",
"lat": "43.6684946",
"lng": "-79.3962671",
"region": "toronto",
"city": "gta",
"google_place_id": "ChIJzbG_XLs0K4gRbpUzBIkgffI",
"location_service_postal_code": "m5s 1t8"
},
"parcels": [
{
"unit": "g",
"values": 5000,
"parcel_size_code": "small",
"price": 9
}
],
"pick_up_shipment_type": "SAME",
"scheduled_date": "2022-08-12",
"time_slot_code": "4:00pm-10:00pm",
"pick_up_scheduled_date": "2022-08-12",
"time_slot": {
"city": "gta",
"code": "4:00pm-10:00pm",
"warehouse_service_zone_code": "A",
"closing_margin": 10,
"from_time": 1200,
"to_time": 1560
},
"time_slot_datetime_start": "2022-08-12T20:00:00+00:00",
"time_slot_datetime_end": "2022-08-13T02:00:00+00:00",
"price": 0,
"parcel_summary": {
"SAME": {
"small": {
"code": "small",
"note": "iPhone case",
"icon_url": "https://storage.googleapis.com/flb-misc/parcel/size/icon/small%403x.png",
"count": 1
}
}
}
}
],
"drop_offs_total_price": 0,
"parcels_total_price": 9,
"additional_parameters_total_price": 0,
"price": 0,
"total_price": 9,
"parcel_summary": {
"SAME": {
"small": {
"code": "small",
"note": "iPhone case",
"icon_url": "https://storage.googleapis.com/flb-misc/parcel/size/icon/small%403x.png",
"count": 1
}
}
}
}
],
"payment_type": {
"id": 1,
"code": "CREDIT_CARD",
"name": "CREDIT_CARD"
},
"min_price": 45,
"actual_total_price": 9,
"actual_total_tax": 1.17,
"actual_price_with_tax": 10.17,
"total_price": 45,
"total_tax": 5.85,
"price_with_tax": 50.85
}
}
Pick The Right Param
Please note that
price_with_taxandactual_price_with_taxin the response object represents the price of the order with and without considering minimum prices, respectively. This means that at the end of the day, any pick up below a certain mount (number of parcels) will be charged for minimum price (by default $45, 5 parcels). The minimum price and price per parcel is negotiable.
Pick-up Addresses
For the frequenty used pick-up addresses we highly recommend to save and reuse them both for getting rates and creating orders.
Create an Order
Sample Request
curl --location --request POST 'https://api-sandbox.flashbox.co/scheduled-service/api/v1/requests/sync' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"pick_up_address": {
"text": "340 Ferrier St, Markham, ON L3R 2Z5, Canada"
},
"drop_offs": [
{
"address": {
"text": "100 University Ave, Toronto, ON M5J 1V6, Canada",
"description": "Fragile - Don'\''t leave at the front door!",
"person_name": "Dr. Brown",
"person_phone": "0123456789",
"person_email": "[email protected]",
"sender_person_email": "[email protected]",
"sender_person_name": "ABC Agent",
"sender_person_phone": "1234567890",
"sender_name": "ABC Shop",
"sender_address_text": "ABC Shop Office, 1111 Albion Rd, Etobicoke, ON M9V 1A9, Canada"
},
"parcels": [
{
"unit": "g",
"values": 5000,
"custom_code": "FSC-0000000000001234"
}
]
}
]
}'
Sample Response
{
"status": "success",
"code": 201,
"message": "Successfully done.",
"object": {
"unique_id": "62f5552094930",
"created_at": "2022-08-11T19:14:40+00:00",
"shipments": [
{
"shipment_order_id": 1843,
"shipment_order_unique_id": "FBS-202208111914415981",
"pick_up_shipment": {
"scheduled_date": "2022-08-12",
"unique_id": "FBP-202208111914404116",
"id": 1839,
"pick_up_label_urls": [
{
"name": "4\"x6\" (pdf)",
"size": "4x6",
"format": "pdf",
"url": "https://labels-sandbox.flashbox.co/?pickUpShipmentUniqueId=FBP-202208111914404116&size=4x6&format=pdf&template=plt100001-4x6"
},
{
"name": "4\"x6\" (zpl)",
"size": "4x6",
"format": "zpl",
"url": "https://labels-sandbox.flashbox.co/?pickUpShipmentUniqueId=FBP-202208111914404116&size=4x6&format=zpl&template=plt100001-4x6"
}
],
"label": "https://labels-sandbox.flashbox.co/?pickUpShipmentUniqueId=FBP-202208111914404116",
"time_slot_datetime_start": "2022-08-12T17:30:00+00:00",
"time_slot_datetime_end": "2022-08-12T19:30:00+00:00"
},
"drop_off_shipment": {
"scheduled_date": "2022-08-12",
"user_ref_id": null,
"unique_id": "FBD-202208111914400172",
"id": 7424,
"pick_up_label_urls": [],
"label": "https://labels-sandbox.flashbox.co/?pickUpShipmentUniqueId=FBP-202208111914404116&dropOffShipmentUniqueId=FBD-202208111914400172",
"time_slot": {
"code": "4:00pm-10:00pm"
},
"time_slot_datetime_start": "2022-08-12T20:00:00+00:00",
"time_slot_datetime_end": "2022-08-13T02:00:00+00:00"
},
"drop_off_address": {
"text": "100 University Ave, Toronto, ON M5J 1V6, Canada",
"person_name": "Dr. Brown",
"person_phone": "0123456789",
"person_email": "[email protected]",
"sender_person_email": "[email protected]",
"sender_person_name": "ABC Agent",
"sender_person_phone": "1234567890",
"sender_name": "ABC Shop",
"sender_address_text": "ABC Shop Office, 1111 Albion Rd, Etobicoke, ON M9V 1A9, Canada",
"postal_code": "m5j 1v6",
"lat": 43.6472892,
"lng": -79.3849716,
"region": "toronto",
"google_place_id": "ChIJqyqoM9I0K4gRj0ZdiSKSGg0",
"location_service_postal_code": "m5j 1v6"
},
"parcel_count": {
"SAME": {
"small": 1
}
},
"parcels": [
{
"pick_up_index": "1",
"drop_off_index": 1,
"pick_up_code": "FBX-222225309724",
"custom_code": "FSC-0000000000001234",
"pick_up_label_urls": [
{
"name": "4\"x6\" (pdf)",
"size": "4x6",
"format": "pdf",
"url": "https://labels-sandbox.flashbox.co/?pickUpShipmentUniqueId=FBP-202208111914404116&dropOffShipmentUniqueId=FBD-202208111914400172&parcelIndex=1&size=4x6&format=pdf&template=plt100001-4x6"
},
{
"name": "4\"x6\" (zpl)",
"size": "4x6",
"format": "zpl",
"url": "https://labels-sandbox.flashbox.co/?pickUpShipmentUniqueId=FBP-202208111914404116&dropOffShipmentUniqueId=FBD-202208111914400172&parcelIndex=1&size=4x6&format=zpl&template=plt100001-4x6"
}
],
"parcel_size_code": "small",
"label": "https://labels-sandbox.flashbox.co/?pickUpShipmentUniqueId=FBP-202208111914404116&dropOffShipmentUniqueId=FBD-202208111914400172&parcelIndex=1"
}
],
"actual_total_price": 9,
"actual_total_tax": 1.17,
"actual_price_with_tax": 10.17,
"total_price": 45,
"total_tax": 5.85,
"price_with_tax": 50.85
}
]
}
}
Payload
The exact same payload as for creating orders can be used for getting rate.
Custom Code
- You can pass your custom code per parcel and print a standard barcode on your parcel containing that code. That way, you do not need to print our labels any more and can use your own.
- Your custom code should be unique, containing 16 to 20 characters including digits and letters only.
Limitations
This API route is a Synchronous one. You will be provided with tracking codes, labels (in different sizes and formats), tracking URLs, etc. in the response on your request.
For keeping our response time minimum, you are only allowed to pass only one shipment at at a time containing up to 5 parcels.
Please feel free to let us know if you need us to extend this limit for you or use our Asynchronous endpoint.
Deleting an Item Using Custom Code
Sample Request
curl --location --request DELETE 'https://api-sandbox.flashbox.co/scheduled-service/api/v1/parcels/find/by-custom-code/FSC-0000000000001234' \
--header 'Content-Type: application/json' \
--header 'X-Requested-With: XMLHttpRequest' \
--header 'Authorization: Bearer <TOKEN>'
Sample Response
{
"status": "success",
"code": 200,
"message": "Successfully done.",
"object": {}
}
For deleting item(s) without custom code, take a look at the corresponding documentation.
Webhooks
Setting up
The most convenient way for setting up webhooks is to log into your online dashboard and then from the webhooks page set as many webhooks as you want. You can select some or all events to trigger your desired endpoints.
You can set authentication header for your webhook requests.
It is recommended to use only Shipment webhooks, since the Parcel webhooks are going to be deprecated by the end of 2022.
Sample Payload
{
"event": "same.parcel.created",
"data": {
"parcel_size": "Medium",
"parcel_code": "medium",
"pickup_code": "FBX-221702057887",
"trigger_datetime": "2022-06-20T21:12:54+00:00",
"custom_code": "FSC-0000000000001234",
"tracking_code": "FBD-202206202112534047",
"request_date": "2022-06-20T21:12:53+00:00",
"pick_up": {
"date": "2022-06-27",
"picked_at": null,
"time_slot": "10:00 AM - 2:00 PM",
"address": "4000 Victoria Park Ave, Toronto, ON M2H 3P4, Canada"
},
"drop_off": {
"date": "2022-06-27",
"dropped_at": null,
"time_slot": "4:00 PM - 10:00 PM",
"receiver_name": "JOHN DOE",
"receiver_phone": "1234567890",
"receiver_address": "147 Danforth Ave, Toronto, ON M4K 1N2, Canada",
"proof_of_delivery": []
},
"extra_data": [
"need_signature": true
]
}
}
Shipment Events
same.shipment.scheduled: When an order is placed for deliverysame.shipment.to_pick_up: When an order is ready to be picked up and a FlashBox delivery agent is going to be assignedsame.shipment.picked_up: When an order is picked up and on its way to the sorting facilitysame.shipment.processing: When an order arrives at the FlashBox sorting facility and is being prepared for delivery agentsame.shipment.in_transit: When an order is ready to be delivered to the customersame.shipment.failed: When an order is unable to be deliveredsame.shipment.to_attempt: When an order failed to be delivered and is set to be retriedsame.shipment.delivered: When an order is delivered to a customersame.shipment.return_scheduled: When an order is set to be returned to yousame.shipment.returned: When an order is returned to yousame.shipment.cancelled: When an order is unable to be delivered after several attempts and unable to be returned to yousame.shipment.deleted: When an order is deleted by you or is not ready to hand over to the FlashBox driver from you
Updated over 1 year ago