Generic franchisor API

What are franchisor integrations

Franchisor integrations allow you to send shipments through another courier company, while automatically synchronizing the two software systems. This way you (or your clients) create shipments into CourierManager, and when the software decides based on the routing zones you set up that it should be delivered by a partner company, it will automatically send it to that company.

Franchisor integrations usually do the following:

  • send shipment info to the franchisor company;
  • allow you to use both the internal CourierManager shipment number and the franchisor's shipment number, seamlessly. Both can be scanned and searched for;
  • receive a printable PDF of that company's label (optional);
  • receive status updates, including delivery notification;
  • receive reweight info (optional);



Generic franchisor

We have a number of integrations directly implemented in the software, but we also created a generic franchisor API which can be used to integrate with any courier company, without custom development from our part. Some development is necessary to match the generic API with a particular company's API, but can be done by an external third party, or by your own development team.

Your dev team will need to create a "bridge", which is a piece of software which sits on a server, receives requests from CourierManager and forwards them to the partner company's software (and the other way around).



Setup

When you create the franchisor CourierManager (Routing main menu, Franchisors menu), you need to fill in the following fields:

  • Code: "API"
  • Courier: a courier you create for this franchisor, to which will be allocated that franchisor's shipments. Will help, among other things, with CoD settlements
  • URL API: the URL of your bridge software
  • User API, Password API, API key and API Client ID: credentials used to login to the franchisor's API. How you use them depends on that specific franchisor's system.
  • Automatic status update activated: Yes



API Specifications

Your bridge should be available on the internet (preferably with SSL), on a public address we'll call $URL.


$URL/create_shipment

Should receive a POST request with a body containing the following json:

{ awb : {<map with shipment fields> },
franchisor: { <map with franchisor details, including credentials> } }

You can find more details on shipment fields in the create_awb API call.

Should return on error:

{ status : "error",
message : <error message> }

Should return on success:

{ status : "ok",
data : { "franchisor_no" : <franchisor shipment number>,
"franchisor_no_canon" : <optional alternative number>,
"franchisor_awbid" : <optional alternative id>,
"pdf_url" : <optional pdf of franchisor label> } }



$URL/track_shipments

Bridge will receive a POST request with a body containing the following JSON:

{ awbs : [ < list of franchisor numbers> ],
franchisor : { <map with franchisor details, including credentials> } }

Should return on success :

{ status : "ok",
data : [ { franchisor_no : <franchisor number>,
franchisor_status : uncollected | active | delivered | returned | exception,
events_list : [ { date: <date>,
status : uncollected | active | delivered | returned | exception,
description: <optional description>,
code: <optional code, may map to the defined franchisor codes>,
location: <optional location, such as city or hub>.
raw_event: <the original event as received from the franchisor API. mandatory } ] } ....
] }


Search support