API documentation

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

  • Name

  • 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

Sandbox

Production

Getting started

  • 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
  • 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
      • run 'node server.js'
      • open your browser and type http://localhost:50000

Example usage: pushing a case using Optimo IFrame

User on <business partner> portal clicks button intending to upload a case to Optimo Pathfinder account

  1. 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

  2. First time user will be required to consent to allow<business partner> portal access to their Optimo account through OptimoAPI

  3. 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

  1. Getting OTP requires sending <business partner> key to OptimoSSO.

  2. Getting OTP must be done by the <business partner> portal back-end to avoid exposing <business partner> key to the client side.

  3. 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.

  4. To get OTP from OptimoSSO please construct the following request

    1. Request URL: OptimoSSO/otp (e.g. https://sandboxauth.optimopathfinder.com.au/otp for sandbox access)

    2. Method: POST

    3. Empty body

    4. Content-Type: application/json

    5. Set Authorization header to ‘Authorization: Basic <Token>’, see below how <Token> is constructed from <business partner> ClientId and Key

    6. OTP is returned in the body of the response as JSON encoded simple object

    7. 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#

Token construction in C#
var HttpClient client;
#client needs to be inisialised here ... 
var clientId_Colon_Secret = $"{clientId}:{clientSecret}"; 
var base64ClientCredentials = Convert.ToBase64String(Encoding.ASCII.GetBytes(clientId_Colon_Secret)); 
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", $"{base64ClientCredentials}");

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

  1. Include JavaScript “https://sandboxauth.optimopathfinder.com.au/ds/bpartner” on pages requiring OptimoAPI access

  2. This script has Optimo.Authenticate function which fetches bearer token. If login to Optimo Pathfinder is required, Optimo login IFrame will be displayed first.

  3. Make a call to Optimo.Authenticate javascript with the following parameters

    1. Business partner clientID

    2. 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.

    3. Empty string. This parameter is reserved for future.

    4. Function to execute when bearer token is retrieved.

      1. IMPORTANT: This function is called with one parameter, which is the bearer token string

      2. Bearer token string is composed of the word ‘Bearer’ space and then the token itself.

    5. Function to call in case an error occur

      1. This function is called with the error parameter.

    6. Background color for <business partner> LOGO, e.g. "rgba(0, 30, 100, 0.85)"

    7. An iframe element or nothing

      1. if iframe element is passed then it will be used to display Optimo login

      2. 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.

  1. To construct an API request

    1. Request URL: OptimoAPI/v1.0/Case (https://apisandbox.optimopathfinder.com.au/v1.0/Case for sandbox access)

    2. Set authorisation header to ‘Authorization: Bearer <token>’ where <token> is the bearer token

    3. Method: POST

    4. Body: a JSON string in the attached yaml format

  2. 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.

  3. Case flow at Optimo will automatically determine and select empty/new case (if any) to upload data to.

  4. Expected results are either of

    1. Success/OK (200): Gives caseId in response for the newly created case

    2. 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.

    3. 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.

    4. 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.