The sections below describe the information necessary to create a Status Check event. 

This event completes a status check on the submitted parameters, so the user can check operational validity before processing other events.

Change history
Date Change
21/12/2018 Released to production
11/06/2018 Initial publication

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/status-check/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/status-check/5ba04c30-c81a-4618-898e-e832da93cf91

Create URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Schema Edition Mandatory Number The API schema used for the format of the submitted data. For example, v1 or v2.
Event ID Mandatory String Unique logbook generated ID for an event.

Request Header:

Content-Type: application/json
Signature: signature generated from the digital signature algorithm using the request body and private key.

Request Body Parameters:

There are no body Paramenters

Event Header Properties:

ParameterRequiredData TypeValidation and Additional Notes
Event ID Mandatory String Unique logbook generated ID for an event.

The same event ID as defined in the URL.

Trip ID Optional String
Software Vendor Mandatory String Your software vendor name. For example, e-logbook.
Software Version Mandatory String Your software version number. For example, 1.0.0.0
Software Installation Id Mandatory String

Your software installation ID. For example, a13afab2-c409-4622-b8f8-146996587809

Must be the Software Installation Id that was registered with the user and public key.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Vessel Number Optional String

Must be a valid Vessel number.

Must be provided if 'Is Vessel Used' = True.

Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.

Completed Date Time Mandatory String Must be provided for Create.

Date 24hr + UTC offset

Geolocation Set Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Status Check Date Time Mandatory String Date 24 hr + UTC Offset
Status Check Location Optional Geolocation

See geolocation parameters below.

Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees, 4dp Minimum of 4dp required.
Longitude Mandatory decimal degrees, 4dp Minimum of 4dp required.

Status Check Create Request Body Example:

{
  "eventHeader": {
    "eventId":"5ba04c30-c81a-4618-898e-e832da93cf1532",
    "vesselNumber": "1",
    "schemaEdition": 1, "completedDateTime": "2017-04-10T09:15:00+11:00", "tripId": "589",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" },
"statusCheckDateTime": "2018-05-01T08:00:00+13:00",
"statusCheckLocation": {
"longitude": 174.637652,
"latitude": -37.415996
}
}

Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Body Parameters:

Properties are returned within an Event parameter. Please see the example provided.

ParameterData Type
Trip ID String
Vessel Number String
UserId Number
Client Name String
Permit Status String
Vessel Name String
Vessel Status String
Event ID String
Schema Edition Number
Event Version Number
Client Number Number
Event Date Time String
Completed By Name String
Finish Location See Geolocation Set Parameters below. Geolocation
Completed Date Time String
Errors Array

Geolocation Set Parameters:

ParameterData Type
Status Check Location

See Geolocation Parameters below

Geolocation
Status Check Date Time String

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees

Errors Parameters:

ParameterData TypeValidation and Additional Notes
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.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
"event": {
"statusCheckDateTime": "2018-05-01T08:00:00+13:00",
"statusCheckLocation": {
"longitude": 174.637652,
"latitude": -37.415996
},
"tripId": "TS-123456789975a",
"vesselNumber": "1",
"userId": 1,
"clientName": "Test Client",
"permitStatus": "Current",
"vesselName": "Test Vessel",
"vesselStatus": "Registered",
"eventId": "217931ba-6d13-a6df-824a-b587c3e3568a",
"schemaEdition": 1,
"eventVersion": 1,
"clientNumber": "1234567",
"completedDateTime": "2018-05-02T12:00:00+13:00",
"eventDateTime": "2018-05-01T08:00:00+13:00",
"notes": null,
"amendmentReason": null,
"completedByName": "Test User"
},
"errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Back to top