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:
To develop a new integration for a courier company not in our system, look at generic franchisor integrations. But if the company you partner with is in our list, you just need to set it up.
Go to the Routing main menu, Franchisors menu, add a new franchisor and give it a name. Then scroll down to the section "Software integration". First thing to look for is the Code field, where you will look for the name of your partner company. "CourierManager" is the generic name for any company using our software, and "API" is the generic name for any company integrated using an external bridge (generic franchisor integration). The rest are documented below. Any fields not mentioned can be left blank or with the default value.
Courier should be a courier created for this franchisor, to which all their shipments will be automatically allocated. It is very useful for CoD settlements.
Series start/Series end should be filled in only for the franchisors that allocate a certain range of numbers in advance.
API url/user/password/key/client id will be provided by the franchisor company. It's likely that not all of them will be needed.
Service type is the service type sent to the franchisor company. Currently just one value is supported.
Use the franchisor number in print will print the label using the franchisor number. This is recommended, since the franchisor will also need to scan the packages. For some integrations the franchisor label is printed by default, in which case this field does nothing.
Hide COD receipt will suppress printing the CoD receipt for the shipments sent through this franchisor, most likely because they will print their own receipt.
Send SMS through franchiser - if the integration allows it, it tells the franchisor to send sms delivery notifications.
Automatic status update enabled - will take delivery statuses from the franchisor. Recommended.
Automatic franchisor number activated - will automatically send the info to the franchisor and receive shipment number. In some cases this may be deactivated, which will allow you to manually send shipments to the franchisor (in the shipments page, "Allocate franchisor numbers").
Send original number - will send to the franchisor the internal number used in CourierManager.
Add price to CoD - If a shippment is set to be paid by the recipient and has CoD, it will add the transport cost to the CoD amount sent to the franchisor.
Price multiplier - If not empty, will send the field "custom_price" to the franchisor, with the value of the transport price multiplied by the field value. Useful in situations when both parties trust each other, and have a deal of "my price minus X%". (for "my price minus 10%", the price multiplier should be set to 0.9)
Print format - page size to use when requesting pdf from the franchisor
Custom fields are used to setup extra info which may depend on particular franchisor integrations.
In order to match the city names used by the franchisor you have two choices. You can use the same city names yourself, optionally with the same extra distance values (import them in the menu Cities, and check "Use city list" in Settings). Or you can use your own list, and use Aliases defined for a particular franchisor - in the view page of that franchiser you have options to import/export a list of aliases.
Specific company tips
If you work with a franchisor that uses Courier Manager, you should fill in the following fields:
API URL - the Base URL sent by email from the franchisor. For many companies it will be https://app.couriermanager.eu/cscourier/Main?, but it may vary if they have a custom setup.
Api key - the Api Key sent by the franchiser
Service type - your most used service type (such as regular or express)
Check all of: Use the franchisor number in print, Activated automatic status updates, Activated automatic franchisor number, and optionally Send original number (see below).
When you are a franchisor yourself, to prepare the integration you should create a client for the partner company. For that client create a API key, then click "email" and send it to the partner company. It will contain the Api Key and the Base URL necessary for them to set up things at their end.
Using same number for both companies
For greater ease of integration, we recommend that you each use a different prefix for your main shipment number series. Say one has numbers "A000123" and the other "B000123" - this way there can never be any confusion between those numbers. In this case, you can opt for an integration which keeps the same shipment number, greatly simplifying the operational side. To do so:
- the franchisor company, when creating the client, should allocate to it a Shipment series for import that is identical to the one used by the partner (say prefix "B" and numbers from 0 to 10000000)
- the source company when creating the franchisor should check the option Send original number
Suffix label printing is should be "_gls2018"
Zpad field should be "11".
GLS is one of the few companies where you manage your own series, i.e. the software picks the next available number from your allocated series, and only after that will send the information to the GLS servers. For most other companies you contact them when finalizing the shipment, and in the same step you send the shipment data and receive the number. Start series and end series should have the series given by GLS.
URL tracking should be: http://online.gls-romania.ro/tt_page.php?tt_value=
Send SMS through the franchisor may be checked, if you wish that delivery SMS be sent by GLS.
Automatic status update and Automatic franchisor number should be active.
Print suffix: should be "_sameday"
URL API: should be "https://api.sameday.ro"
User API and Password API should be filled in in the info received from Sameday.
Custom field1: the "pickupPoint" value received from Sameday
Custom field2: the "contactPerson" value received from Sameday
For each individual client, you may customize the pickupPoint and contactPerson by using the Franchisor ID field, and entering both values in that field separated by a comma. For example if for a certain client Sameday allocates the pickupPoint 1234 and contactPerson 5678, you will enter in that client's Franchisor ID the value 1234,5678
You now can easily get the 2 IDs from Sameday without having to ask them for each client. After you create a Franchiser named Sameday and you fill in all your account information there, in the the franchiser view page, you can see a button called "Download pickup points" ("Descarcati puntele de ridicare" in romana)
You will see at the bottom of the page a table with various information regarding your clinets, including the 2 ID numbers you need to fill in in the FranchiserID field.
The service value sent to Sameday is hardcoded as "7".
URL API: https://api.dpd.ro/v1
User API, Password API: as received from DPD.
API Client ID: the value for thirdPartyClientId, as received from DPD
Custom field1: The dropoffOfficeId value as received from DPD
Custom field2: The serviceId value as received from DPD (or 2505 if none is supplied)
The country field in the address is hardcoded to Romania (642). Please contact us if you want it customized.
API URL: http://franchisors.couriermanager.eu/franchisers/TCS
API user/password/key/client id: credentials from TCS
Custom1: "costCenterCode" from TCS
API user, password and api key, as received from Cargus
The following should also be requested from Cargus:
Local address: senderLocationId (the pickup address; can also be customized per client using the client field Franchiser location ID)
Custom 1: PriceTableId
Custom 2: TertiaryClientId (note: if this field is not empty, will automatically send to Cargus the fields: ShipmentPayer=1 and HasTertReimbursement=true)
Custom 3: ServiceId