FishServe - Status Check Event

Status Check Event

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:

Parameter	Required	Data type	Description
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:

Parameter	Required	Data Type	Validation 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 an integer
Completed Date Time	Mandatory	String	Must be provided for Create. Date 24hr + UTC offset

Geolocation Set Parameters:

Parameter	Required	Data Type	Validation 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:

Parameter	Required	Data Type	Validation 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:

Status	Description
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.

Parameter	Data 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:

Parameter	Data Type
Status Check Location See Geolocation Parameters below	Geolocation
Status Check Date Time	String

Geolocation Parameters:

Parameter	Data Type
Latitude	decimal degrees
Longitude	decimal degrees

Errors Parameters:

Parameter	Data Type	Validation 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."
    }
  ]
}