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

  • AuthenticationTo authenticate each user, and can also return user details and authorisations. Used for FishServe APIs, and for registering an ERS logbook.
  • Registering ERS logbooks: To register a logbook device or request the expiry date of an existing registration.

Authentication

This API returns an authenticated user token that must be used for FishServe APIs and for registering an ERS logbook. The user token should be specified in the authorisation header for these APIs. 

This API can also return user details, such as names, email addresses and the clients and roles the user is authorised for.  Include ?requireUserDetail=true in the request url to return the user details. 

The API request requires;

      • Username
      • Password

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 response provides;

      • An authenticated user token for use in the request header of other APIs
      • User details including authorisations (if the ?requireUserDetail=true flag is provided in the URL)

Authentication Technical Information

Request

Request Url - for token response only
POST https://api.uat.kupe.fishserve.co.nz/authenticate
Request Url - for additional user details including authorisations
POST https://api.uat.kupe.fishserve.co.nz/authenticate?requireUserDetail=true

Request Header

Content-Type: application/json
Request Body Parameters
ParameterRequiredData typeDescription
Username Mandatory String The user name
Password Mandatory String The password
Request Body Example:
{
  "username": "Test",
  "password": "Test123"
}

Response

Response Parameters - for token response only
ParameterData typeDescription
User Token String The user access token
Response Parameters - for additional user details including authorisations
ParameterData typeDescription
User Token String The user access token
User Info User Info Set see User Info Set Parameters below.
Clients Array of Clients see Client Array Parameters below.
User Info Set Parameters
ParameterData typeDescription
Title String The title of the user. For example 'Mr', 'Mrs', 'Dr'.
First Name String The first name of the user.
Surname String The last name of the user.
Preferred Name String The preferred name of the user. Can be Null.
Middle Name String The middle name of the user. Can be Null.
Email Addresses Array of Strings The email address(es) of the user.
Client Array Parameters
ParameterData typeDescription
Client Number Number The client number of the client associated with the user. 
Legal Name String The legal name of the client associated with the user.
Trading Name String The trading name of the client associated with the user. Can be Null.
Authorisations Array of Strings The authorised roles the user can perform for the client. 

Response Body Example - for token response only
{
  "userToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjY2di0xZUp0OEZlazhxNmh"
}
Response Body Example - for additional user details including authorisations
{
 "userToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjY2d",
 "user_info": {
  "title": "Mr",
  "firstName": "Michael",
  "surname": "Anderson",
  "preferredName": null,
  "middleName": "Andrew",
  "emailAddresses": [
  "michael.anderson@testuser.co.nz"
  ]
  },
 "clients": [
  {
  "clientNumber": "9876543",
  "legalName": "A Fishing Company Limited",
  "tradingName": null,
  "authorisations": [
   "CCSBT Manager",
   "Client Manager"
   ]
  },
 {
 "clientNumber": "9871234",
 "legalName": "West Fishing Company Limited",
 "tradingName": null,
 "authorisations": [
  "CCSBT Manager",
  "Client Manager"
  ]
 }
 ]
} 

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.

All 3rd party software must use digital signature algorithms to meet the authentication requirements for submitting ERS event reports. The algorithm chosen is ECDSA (ANSI X9.62) NIST P-256 elliptic curve known as prime256v1 or secp256r1.

If you need help testing your logbook digital signatures, visit our digital signature test information here.

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.

The authorisation for this API is the same as other FishServe APIs - see the Authentication information above. 

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}"
}
Example:
{
    "2018-03-01T00:00:00+13:00"
}

Back to top