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_tax and actual_price_with_tax in 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 delivery
  • same.shipment.to_pick_up: When an order is ready to be picked up and a FlashBox delivery agent is going to be assigned
  • same.shipment.picked_up: When an order is picked up and on its way to the sorting facility
  • same.shipment.processing: When an order arrives at the FlashBox sorting facility and is being prepared for delivery agent
  • same.shipment.in_transit: When an order is ready to be delivered to the customer
  • same.shipment.failed: When an order is unable to be delivered
  • same.shipment.to_attempt: When an order failed to be delivered and is set to be retried
  • same.shipment.delivered: When an order is delivered to a customer
  • same.shipment.return_scheduled: When an order is set to be returned to you
  • same.shipment.returned: When an order is returned to you
  • same.shipment.cancelled: When an order is unable to be delivered after several attempts and unable to be returned to you
  • same.shipment.deleted: When an order is deleted by you or is not ready to hand over to the FlashBox driver from you