This information is for developers who wish to use the Optimo API so that data can imported from another application into Pathfinder.
What information Optimo needs from API users
Logo image in ‘png’ format 32x32. This will appear on the iFrame
FQDN to whitelist
What information API users need from OPTIMO
Other than those instructions API users will need the following information from us
Key - usually some random GUID
ClientId - usually short name of the API user company name
URIs to Optimo end-points
https://sandboxauth.optimopathfinder.com.au/ for authorisation (OptimoSSO)
https://apisandbox.optimopathfinder.com.au/ for pushing a case (OptimoAPI)
https://sandbox.optimopathfinder.com.au/ for checking how the case was pushed, buying cases, logging out (Optimo Pathfinder)
https://auth.optimopathfinder.com.au/ for authorisation (OptimoSSO)
https://api.optimopathfinder.com.au/ for pushing a case (OptimoAPI)
https://app.optimopathfinder.com.au/ for checking how the case was pushed, buying cases, logging out (Optimo Pathfinder)
- Create a user profile in Optimo Pathfinder Sandbox
- You will be given one case originally to start with - so you can push your data to this case immediately
- You will need many more cases for testing so you can 'buy' more cases using the eWay sandbox
- The eWay sandbox is connected to our sandbox system, e.g. when you try to add a case from Optimo Pathfinder but there is none left it will direct you to <Optimo Pathfinder>/products/casebundles (https://sandbox.optimopathfinder.com.au/products/casebundles) and then further to Eway (once bundle is selected)
- To buy a case on Eway sandbox use the following info
- credit card number 4444 3333 2222 1111
- Other details - any
Pushing a case to Optimo
- Information about the case being pushed should be a json string in the format specified by this yaml file.
- To read and/or edit this file one should use swagger, which is available online at https://editor.swagger.io/
- A case can be pushed using Optimo IFrame. Please follow the instructions below
- Please download an example app in node.js.
- The sources can be open e.g. in Visual studio 2019
- The app can be run using node.js server
- Open cmd
- go to the BPartnerExample folder
- open your browser and type
Example usage: pushing a case using Optimo IFrame
User on <business partner> portal clicks button intending to upload a case to Optimo Pathfinder account
If user is not logged on to OptimoSSO in the same browser window, he is presented with “iframe” to login to OptimoSSO where he is required to enter his credentials
First time user will be required to consent to allow<business partner> portal access to their Optimo account through OptimoAPI
Once user is authenticated at OptimoSSO, API call is made from <business partner> portal to OptimoAPI end point to push the case to Optimo Pathfinder account
Developers info: pushing a case using Optimo IFrame
How to get OTP
First OTP needs to be retrieved. This is a short lived token (20 min max) that can be safely exposed on client side
Getting OTP requires sending <business partner> key to OptimoSSO.
Getting OTP must be done by the <business partner> portal back-end to avoid exposing <business partner> key to the client side.
E.g. client side of the <business partner> portal client side makes a call to the <business partner> portal back end. Then <business partner> portal back end makes a call to OptimoSSO to get OTP.
To get OTP from OptimoSSO please construct the following request
Request URL: OptimoSSO/otp (e.g. https://sandboxauth.optimopathfinder.com.au/otp for sandbox access)
Set Authorization header to ‘Authorization: Basic <Token>’, see below how <Token> is constructed from <business partner> ClientId and Key
OTP is returned in the body of the response as JSON encoded simple object
To construct a <Token>, concatenate your <business partner> ClientId with your <business partner> Key through ‘:', i.e. Id + ':’ + Key, then convert it to bytes and then to base64 encoded string. See the following block of code that does this in C#
How to get Bearer token
APIs are required to be called with a bearer token. Bearer token becomes available when <business partner> portal client is logged in to Optimo Pathfinder in the same browser window
This script has Optimo.Authenticate function which fetches bearer token. If login to Optimo Pathfinder is required, Optimo login IFrame will be displayed first.
Business partner clientID
OTP simple object received in the ‘How to get OTP’ step (if it was successful). IMPORTANT: if OTP has already expired by this time no bearer token can be retrieved.
Empty string. This parameter is reserved for future.
Function to execute when bearer token is retrieved.
IMPORTANT: This function is called with one parameter, which is the bearer token string
Bearer token string is composed of the word ‘Bearer’ space and then the token itself.
Function to call in case an error occur
This function is called with the error parameter.
Background color for <business partner> LOGO, e.g. "rgba(0, 30, 100, 0.85)"
An iframe element or nothing
if iframe element is passed then it will be used to display Optimo login
Otherwise a new iframe element will be created
How to upload a case
Once a bearer token has been retrieved a call to OptimoAPI end point can be made. Currently there is only one supported method - to push a new case.
To construct an API request
Request URL: OptimoAPI/v1.0/Case (https://apisandbox.optimopathfinder.com.au/v1.0/Case for sandbox access)
Set authorisation header to ‘Authorization: Bearer <token>’ where <token> is the bearer token
Body: a JSON string in the attached yaml format
If a client has NO cases on Pathfinder side then 403 error will be issued indicating that this client needs to login to Pathfinder and buy more cases. Status 200 will indicate a successful upload.
Case flow at Optimo will automatically determine and select empty/new case (if any) to upload data to.
Expected results are either of
Success/OK (200): Gives caseId in response for the newly created case
Unauthorized (401): Needs a bearer token (or current token is expired) – Authentication dialog would appear only if user signs off from another tab of same browser.
Forbidden (403): A redirect may be necessary to complete the forbidden request. E.g. user has no “cases” left in our system to upload new case data to. Purchase is required. A link would be present in “redirectTo” in the response.
Bad request (400): Case upload request contains invalid data (or contains invalid format). Expected is an application/json format. This may occur with stray characters in the data.