You can use our test environment to develop and test your application.

To setup access and begin using our APIs, you will need to contact us for a username and password.

Test url: https://register.demo.kupe.fishserve.co.nz/

21/08/2017:

Changes have been made to the ERS APIs and these changes are in our UAT environment only so that demo is unaffected for any current development work that may be occurring.

To access this environment you will need a UAT username and password. Please contact us for access.

The url for the UAT environment is: https://ers.uat.kupe.fishserve.co.nz/ . 

When you have completed testing, you will need to use an existing production username and password or set up new authorisations to access the live services.

Production url: https://fishserve.co.nz/

Below you will find information on;

Authentication

All requests to the API must be authenticated, the user token should be specified in the authorisation header.

The username and password must relate to a user / person / authorisations set up to use the FishServe website.  We do not authenticate the application calling the API or the FishServe client being called for. 

The API request requires;

      • Username
      • Password

The response provides;

      • An authenticated user token for use in the request header of other APIs

Authentication Technical Information

All requests to the API must be authenticated, the user token should be specified in the authorization header.

Request

Request Url
POST https://api.uat.kupe.fishserve.co.nz/authenticate
Request Header
Content-Type: application/json
Request Body Parameters
ParameterRequiredData typeDescription
Username Mandatory String The user name
Password Mandatory String The password
Request Body
{
  "username": "{Username}",
  "password": "{Password}"
}

Example:

{
  "username": "Test",
  "password": "Test123"
}

Response

Response Parameters
ParameterData typeDescription
User Token String The user access token
Response Body
{
  "userToken": "{UserToken}"
}

Example:

{
  "userToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjY2di0xZUp0OEZlazhxNmh"
}

Back to top

Logbook Registration

All users must register their logbooks to be able to submit ERS event APIs to FishServe.

This API is also used to provide FishServe with a new Public key if one is needing to be renewed or otherwise replaced.

When a logbook is submitted with a new Public Key the previous public key will enter a ‘grace period’ which will expire the following day at midnight.

The new public key will have an expiry date in 6 months’ time.

The Create API request requires;

  • Software Vendor
  • Device Name
  • Software Installation Id
  • Public Key

The response provides;

  • User ID
  • Expiry Date Time

Alternatively, the GET API can be used to return the expiry date of an existing registration.

Registering ERS Logbooks Technical Information

All users must register their logbooks to be able to submit ERS event APIs to FishServe.

Request

Request Url
POST https://ers.uat.kupe.fishserve.co.nz/api/security/log-book-registration
Request Header
Content-Type: application/json
Authorization: Bearer YOUR_USER_Token
Request Body Parameters
ParameterRequiredData typeDescription
Software Vendor Mandatory String The name of the software vendor.
Device Name Mandatory String The name of your device.
Software Installation Id Mandatory String

GUID format.

Unique Identifier of the device.

Public Key Mandatory String

The public key that is generated from the digital signature algorithm on your logbook.

Must be unique for each combination of software installation id and user.

Note: The logbook will have to store the private key that matches the public key.

Request Body
{
  "SoftwareVendor": "{SoftwareVendor}",
  "DeviceName": "{DeviceName}",
  "SoftwareInstallationId" : "{SoftwareInstallationId}",
  "PublicKey": "{PublicKey}"
}

Example:

{
  "SoftwareVendor": "LogBook Co 123",
  "DeviceName": "Vessel Computer",
  "SoftwareInstallationId" : "74be4716-cd8f-4264-83e4-5b1249082503",
  "PublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEX98JTRSsAYUnQ3HfwnlEQGNLb8sCczFhlYSukPRMpmtgDSQA4PphkDaMTYRrEwW/94moJmY8kakp0PwamSUQjg=="
}

Response

Response Parameters
ParameterData typeDescription
User Id String

The user access token.

To be used as Completer User Id on the payload.

Expiry Date Time String

Date Time in 24hr format.

The registration will expire every 6 months.

A user can have multiple registrations for different devices, but only one registration per device.

Errors Array

List of errors, if any. See Error Parameters below.

Errors Parameters:

ParameterData TypeDescription
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.
Response Body
{
    "userId": "{userId}",
    "expiryDateTime": "{expiryDateTime}",
    "errors": []
}

Example:

{
    "userId": 25,
    "expiryDateTime": "2018-03-01T00:00:00+13:00",
    "errors": []
}

Back to top

Get

Use this API to retrieve the expiry date of an existing registration.

Request Url
GET https://ers.uat.kupe.fishserve.co.nz/api/security/log-book-expiry?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}
Example
GET https://ers.uat.kupe.fishserve.co.nz/api/security/log-book-expiry?softwareInstallationId=74be4716-cd8f-4264-83e4-5b9249083802&CompleterUserId=8965
Request Header
Content-Type: application/json
Signature: signature generated from the digital signature algorithm using the request body and private key.

Response Status
StatusDescription
200 OK Status for a successful request. 
500 Internal Server Error  Status when something is wrong with the request. 
Response Parameters
ParameterData type
Expiry Date Time 

Logbook registration expiry date. 

Response Body
{
    "expiryDateTime": "{expiryDateTime}"
}
Example:
{
    "expiryDateTime": "2018-03-01T00:00:00+13:00"
}

Back to top