FishServe - ERS Event APIs in Production

ERS Event APIs in Production

Below is the technical information required for submitting ERS Event APIs in our production environment.

Our production URL is: https://ers.kupe.fishserve.co.nz/

All of these APIs are available for testing and developing against in our UAT environment. Do not use the production environment for testing your applications.

Our UAT URL is: https://ers.uat.kupe.fishserve.co.nz/

Red text in the information below indicates changes that are in an upcoming new schema only and have yet to take effect in production. These changes are available in UAT.

Technical information on APIs still in the development phase are available on our ERS Event APIs in Development page here.

Available APIs in Production

Fishing Event APIs

Trawl Last updated: 01/09/2021
Potting Last updated: 04/07/2018
Netting Last updated: 01/09/2021
Lining Last updated: 01/09/2021
Tuna Lining Last updated: 01/09/2021
Other Lining Last updated: 04/07/2018
Hand Gathering Last updated: 04/07/2018
Diving Last updated: 01/09/2021
Seining Last updated: 11/06/2018
Jigging Last updated: 11/06/2018
Dredging Last updated: 11/06/2018

Non-Fishing Event APIs

Trip Start Last updated: 01/09/2021
Trip End Last updated: 10/12/2018
Non-Fish or Protected Species (NFPS) Last updated: 01/09/2021
Processing Last updated: 08/11/2018
Disposal Last updated: 11/06/2018
Landing Last updated: 08/11/2018
Status Check Last updated: 11/06/2018

Shared vs Restricted event API's

Get restricted events Last updated: 21/12/2018
Amending restricted events Last updated: 21/12/2018

Managing Event APIs

Find Events Last updated: 07/02/2020
Delete Events Last updated: 18/05/2017
Event Schema Editions Last updated: 02/07/2018
Event Error Id's Last updated: 02/07/2018

ERS Master Data APIs in Production

ERS Master Data APIs in Production

Shared vs Restricted event API's

Restricting applies to the location (latitude and longitude) on catch reports and NFPS reports, (e.g. Start Location, Finish Location, End Of Set Location, Start Of Haul Location, and Diver-specific Start and Finish locations).
It applies equally to the system and manual latitudes/longitudes.
It does not apply to the location (latitude, longitude) on Trip Start, Trip End, Disposal or Landing reports.

Get restricted events

The section below describes the difference between a Get response for shared or restricted location sharing.

If a user who is not the original completer is viewing a report with a restricted location, the longitude and latitude will display with one decimal place (rounded).

Share - Trawl Get Request Location Body Example:

     "startLocation": {
      "systemDateTime": "2017-05-24T08:01:00+13:00",
      "systemLocation": {
        "longitude": -175.5432,
        "latitude": -45.7878
      },
      "manualDateTime": "2017-05-24T09:15:00+13:00",
      "manualLocation": {
        "longitude": -176.543,
        "latitude": -46.787
      }
    },
    "finishLocation": {
      "systemDateTime": "2017-05-24T12:30:00+13:00",
      "systemLocation": {
        "longitude": -174.5432,
        "latitude": -44.8878
      },
      "manualDateTime": null,
      "manualLocation": null
      },

Restrict - Trawl Get Request Location Body Example:

    "startLocation": {
      "systemDateTime": "2017-05-24T08:01:00+13:00",
      "systemLocation": {
        "longitude": -175.5,
        "latitude": -45.8
      },
      "manualDateTime": "2017-05-24T09:15:00+13:00",
      "manualLocation": {
        "longitude": -176.5,
        "latitude": -46.8
      }
    },
    "finishLocation": {
      "systemDateTime": "2017-05-24T12:30:00+13:00",
      "systemLocation": {
        "longitude": -174.5,
        "latitude": -44.9
      },
      "manualDateTime": null,
      "manualLocation": null
      },

Amending restricted events

The section below describes amending a restricted location event.

If an ER Reporter has restricted their fishing location for a permit holder, other users besides the ER Reporter (original completer) will not be able to amend the fishing location or net/line lost of the reports for that permit holder.

Trawl Update Request for a Restricted event Body Example:

Note: The system/manual locations & isNetLost are set to null

{
  "eventHeader": {
    "tripId": "Trawltripid1",
    "eventId": "5ba04c30-c81a-4618-898e-e832da93cf9290",
    "eventVersion": "2",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "Fishing conditions were poor",
    "completedDateTime": null,
    "amendmentReason": "Wrong species code used",
    "softwareVendor": "ERS-FishServe",
    "softwareVersion": "1.1.2",
    "softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
    "clientNumber": "1234567",
    "completerUserId": "1234" 
  },
  "FishingUnderHSP": "True",
  "fishingMethodCode": "BT",
  "targetSpeciesCode": "SNA",
  "mitigationDeviceCodes": ["BIB"],
  "startLocation": {
    "systemDateTime": "2017-05-24T08:01:00+13:00",
       "systemLocation": {
           "longitude": null,
           "latitude": null
                                },
    "manualDateTime": "2017-05-24T09:15:00+13:00",
        "manualLocation": {
            "longitude": null,
             "latitude": null
                                }
  },
  "IsNonFishOrProtectedSpeciesCatchPresent": "True",  
  "numberOfNets": 3,
  "vesselPairNumber": null,
  "wingSpreadMetres": 12,
  "headlineHeightMetres": 25.5,
  "codendMeshSizeMm": 5,
  "groundRopeDepthMetres": 11,
  "bottomDepthMetres": 150,
  "speedKnots": 7.5,
  "finishLocation": {
    "systemDateTime": "2017-05-24T12:30:00+13:00",
        "systemLocation": {
            "longitude": null,
            "latitude": null
                                }
  },
  "isNetLost": null,
  "estimatedCatchKg": 90,
  "catches": [
    {
      "speciesCode": "SNA",
      "greenWeightEstimateKg": 50.25
    },
    {
      "speciesCode": "GSH",
      "greenWeightEstimateKg": 23.75
    }
  ]
}

Find Events

The section below describes how to retrieve details of submitted events.

Please note:

Only accepted events will be returned.
No rejected events will be returned.
Only the latest version of each event is returned.

Get

**Change history**
Date	Change	Schema	Schema Valid From	Schema Valid To
07/02/2020	Corrected documentation to include messageStatusCode and actionTypeCode in response	v1	01/10/2017
18/05/2017	Initial publication	v1	01/10/2017

Request URL:

GET https://ers.kupe.fishserve.co.nz/api/event/v1/event-find?ReceivedDateTimeFromDateRange=&ReceivedDateTimeToDateRange=&EventDateTimeFromDateRange=&EventDateTimeToDateRange=&VesselId=&TripId=&EventType=&clientNumber=&PageSize=&PageNumber=

Example:

GET https://ers.kupe.fishserve.co.nz/api/event/v1/event-find?ReceivedDateTimeFromDateRange=&ReceivedDateTimeToDateRange=&EventDateTimeFromDateRange=&EventDateTimeToDateRange=&VesselId=&TripId=&EventType=&clientNumber=7654321&PageSize=&PageNumber=

Get URL Parameters:

Parameter	Required	Data type	Validation and Additional Notes
Received Date Time From Date Range	Optional	String	The beginning datetime to search from for the received date of an event. Searching by date can be done by providing either a From or To date parameter. It is not required to provide both a start and end date.
Received Date Time To Date Range	Optional	String	The end datetime to search up to for the received date of an event. Searching by date can be done by providing either a From or To date parameter. It is not required to provide both a start and end date.
Event Date Time From Date Range	Optional	String	The beginning datetime to search from for the date of an event. This is the date as entered on the event. For example, processed datetime, landing datetime, or start of haul datetime. Searching by date can be done by providing either a From or To date parameter. It is not required to provide both a start and end date.
Event Date Time To Date Range	Optional	String	The end datetime to search up to for the date of an event. This is the date as entered on the event. For example, processed datetime, landing datetime, or start of haul datetime. Searching by date can be done by providing either a From or To date parameter. It is not required to provide both a start and end date.
Vessel Id	Optional	String	The vessel number.
Trip Id	Optional	String	The trip id for a set of events.
Event Type	Optional	String	The event name.
Client Number	Optional	String	The permit holder client number that the event is submitted against.
Page Size	Optional	Number	The number of records returned on the page. For example, if you want 20 records per page to be returned, then set this parameter to 20. Default size limit is 1000.
Page Number	Optional	Number	The page number returned. For example, if you want to view page 3 out of 4, then set this parameter to 3. Default page number is 1.

Request Header:

Content-Type: application/json
Authorisation: Bearer YOUR_USER_TOKEN

Response

Response Status:

Status	Description
200 Ok	Status when event has been retrieved successfully.
404 Not Found	Status when event cannot be found.
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	Validation and Additional Notes
Data See Data Parameters below.	Array of Data records
Total Number of Records	Number	The total number of events retrieved.
Page Number	Number	The page number of the page returned.
Page Size	Number	The total number of records per page.

Data Parameters:

Parameter	Data Type	Validation and Additional Notes
Event ID	String	Unique ID provided for each event.
Trip ID	String	Unique ID provided for each set of events which make up a single trip.
Vessel ID	String	The vessel number.
Event Date	String	The date of the event. This is the date as entered on the event. For example, processed datetime, landing datetime, or start of haul datetime.
Received Date	String	The date the event was submitted.
Version	Number	The event version number.
Event Type	String	The name of the event. For example; Trawl, Disposal, Processing.
Get URL	String	The URL to retrieve details of the particular event. Omitted if the actionTypeCode is "Delete".
Client Number	String	The permit holder client number that the event is submitted against.
messageStatusCode	String	Status of the event, can be "Accepted" or "Rejected" or "Received".
actionTypeCode	String	Action requested for the event, can be "Create" or "Update" or Delete".

Find Events Get Request Body Example:

{
	"data": [
	{
	"eventId": "ee1b41cc-8dbd-18d1-7100-c25e0c093431",
	"tripId": "t122",
	"vesselId": "44453",
	"eventDate": "2017-07-01T08:00:00+13:00",
	"receivedDate": "2017-07-06T13:03:18+12:00",
	"version": 1,
	"schemaEdition": 1,
	"eventType": "TripEnd",
	"getUrl": "https://ers.uat.kupe.fishserve.co.nz/clients/7654321/event-detail/10323",
	"clientNumber": "7654321"
	"messageStatusCode": "Accepted",
	"actionTypeCode": "Create"
	},
	{
	"eventId": "c77d9922-0039-c0c2-8c90-7eb928526303",
	"tripId": "TS1",
	"vesselId": "2066",
	"eventDate": "2017-07-01T08:00:00+13:00",
	"receivedDate": "2017-07-06T13:02:37+12:00",
	"version": 2,
	"schemaEdition": 1,
	"eventType": "NonFishOrProtectedSpecies",
	"getUrl": "https://ers.uat.kupe.fishserve.co.nz/clients/7654321/event-detail/10320",
	"clientNumber": "7654321"
	"messageStatusCode": "Accepted",
	"actionTypeCode": "Amend"
	},
	{
	"eventId": "254da76e-b7e6-be4e-6b81-42554adbe3de",
	"tripId": "jiggingtripId1",
	"vesselId": "15527",
	"eventDate": "2017-05-10T09:15:00+11:00",
	"receivedDate": "2017-07-04T10:38:50+12:00",
	"version": 1,
	"schemaEdition": 1,
	"eventType": "Jigging",
	"clientNumber": "7654321"
	"messageStatusCode": "Accepted",
	"actionTypeCode": "Delete"
	},
	{
	"eventId": "835825ea-0689-315d-3d66-2593f1edeb1b",
	"tripId": "Trawltripid1",
	"vesselId": "15950",
	"eventDate": "2017-07-24T09:15:00+13:00",
	"receivedDate": "2017-06-30T16:45:26+12:00",
	"version": 1,
	"schemaEdition": 1,
	"eventType": "Trawl",
	"getUrl": "https://ers.uat.kupe.fishserve.co.nz/clients/7654321/event-detail/10042",
	"clientNumber": "7654321"
	"messageStatusCode": "Accepted",
	"actionTypeCode": "Create"
	},
	{
	"eventId": "26ef9c3e-5512-e2b0-4ce0-a8ac446507ed",
	"tripId": "15950",
	"vesselId": "1",
	"eventDate": "2017-03-28T09:15:00+11:00",
	"receivedDate": "2017-06-30T15:42:47+12:00",
	"version": 1,
	"schemaEdition": 1,
	"eventType": "Disposal",
	"getUrl": "https://ers.uat.kupe.fishserve.co.nz/clients/7654321/event-detail/10007",
	"clientNumber": "7654321"
	"messageStatusCode": "Accepted",
	"actionTypeCode": "Create"
	},
	{
	"eventId": "NET99",
	"tripId": "567",
	"vesselId": "1",
	"eventDate": "2017-04-01T08:00:00+13:00",
	"receivedDate": "2017-06-15T15:52:46+12:00",
	"version": 1,
	"schemaEdition": 1,
	"eventType": "Netting",
	"getUrl": "https://ers.uat.kupe.fishserve.co.nz/clients/7654321/event-detail/7062",
	"clientNumber": "7654321"
	"messageStatusCode": "Accepted",
	"actionTypeCode": "Create"
	}
	],
	"totalNumberOfRecords": 6,
	"pageNumber": 1,
	"pageSize": 1000
	}

Delete Events

The section below describes how to delete an event.

Please note:

Events can only be deleted if transmitted unintentionally and no event actually occurred, or where a single event is reported twice.
Events should never be deleted where incorrect details can be corrected using an amendment.
Only events that have been accepted by the FishServe APIs can be deleted. Rejected events cannot be deleted.
Once deleted, an event cannot be amended or retrieved using the GET or UPDATE APIs.
Delete information will be transmitted to MPI.

Delete

Request URL:

DEL https://ers.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/{eventtype}/{eventID}

Example:

DEL https://ers.kupe.fishserve.co.nz/api/8765432/event/v1/trawl/abc123456789-01

Delete URL Parameters:

Parameter	Required	Data type	Validation and Additional Notes
Event Type	Mandatory	String	The event name.
Client Number	Mandatory	String	The permit holder client number that the event is submitted against.
Event ID	Mandatory	Number	Unique logbook generated ID for an event.

Request Header:

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

Request Body Parameters:

Parameter	Required	Data Type	Validation and Additional Notes
Event Header	Mandatory	Event Header Set	See Event Header Properties below.

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.
Notes	Mandatory	String	Reason for deletion of event.
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.
Client Number	Mandatory	String	Must be a valid client number. Must be the same client number as specified in the URL.
Completer User Id	Mandatory	String	The user ID retrieved from registering the logbook.

Delete Events DEL Request Body Example:

{
 "eventId": "abc123456789-01",
 "Notes": "Delete of a duplicate event",
 "softwareVendor": "ERS-FishServe",
 "softwareVersion": "1.1.2",
 "softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
 "clientNumber": "8765432",
 "completerUserId": "123456"
}

Response

Response Status:

Status	Description
200 Ok	Status when event has been deleted successfully.
404 Not Found	Status when event cannot be found.
401 Unauthorised	Status when the user does not have the appropriate authorisation to perform the action.

Event Schema Editions

The section below describes how to retrieve details of event schema editions

The results are sorted alphabetically by event type

Get

Request URL:

GET https://ers.kupe.fishserve.co.nz/api/event-schema-editions

Response

Response Status:

Status	Description
200 Ok	Status when event has been retrieved successfully.
404 Not Found	Status when event cannot be found.
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	Validation and Additional Notes
Data See Data Parameters below.	Array of Data records
Event Type	String	Event schema event type
Schema Edition	Number	Event schema version number
Start Date	String	Date when schema edition begins
Finish Date	String	Date when schema edition ends
URL	String	An example of the submit URL used for that event. Note: the only change between event schema versions for an event is the version e.g. 'v1' changed to 'v2'.

Event Schema Editions Get Request Body Example:

[
 {
 "eventType": "Disposal",
 "schemaEdition": 1,
 "startDate": "2017-10-01T00:00:00",
 "finishDate": null,
 "url": "https://ers.test.kupe.fishserve.co.nz/api/[ClientNumber]/event/v1/disposal/[EventId]"
 },
 {
 "eventType": "Diving",
 "schemaEdition": 1,
 "startDate": "2018-07-01T00:00:00",
 "finishDate": null,
 "url": "https://ers.test.kupe.fishserve.co.nz/api/[ClientNumber]/event/v1/diving/[EventId]"
 },
 {
 "eventType": "Dredging",
 "schemaEdition": 1,
 "startDate": "2018-07-01T00:00:00",
 "finishDate": null,
 "url": "https://ers.test.kupe.fishserve.co.nz/api/[ClientNumber]/event/v1/dredging/[EventId]"
 },
 {
 "eventType": "Non Fish or Protected Species",
 "schemaEdition": 1,
 "startDate": "2017-10-01T00:00:00",
 "finishDate": "2018-09-30T23:59:59",
 "url": "https://ers.test.kupe.fishserve.co.nz/api/[ClientNumber]/event/v1/non-fish-or-protected-species/[EventId]"
 },
]

Event Error Id's

The section below describes how to retrieve details of the event error id's.

The results are sorted by ID descending.

Get

Request URL:

GET https://ers.kupe.fishserve.co.nz/api/event-error-ids

Response

Response Status:

Status	Description
200 Ok	Status when event has been retrieved successfully.
404 Not Found	Status when event cannot be found.
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	Validation and Additional Notes
Data See Data Parameters below.	Array of Data records
Id	Number	Event error id. This will be provided with every error message.
Description	String	Event error message, e.g. "The request body is missing or could not be bound."

Event Error IDs Get Request Body Example:

[
 {
 "id": 1,
 "description": "The request body is missing or could not be bound."
 },
 {
 "id": 2,
 "description": "Event id must be provided."
 },
 {
 "id": 3,
 "description": "Event id already exists."
 },
 {
 "id": 4,
 "description": "The event id specified in the url does not match the event id in the request body."
 },
 {
 "id": 5,
 "description": "The event id does not exist."
 }
]