The sections below describe the information necessary to create, get and update a Landing event.

Change history
Date Change Schema Schema Valid From Schema Valid To
21/12/2018

Released to production

08/11/2018

Made Trip ID optional 

Changed Container Count from integer to decimal to 2dp.

v1 01/10/2017
18/05/2017 Initial publication v1 01/10/2017

Create

Request URL:

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

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/landing/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.
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:

ParameterRequiredData TypeValidation and Additional Notes
Event Header Mandatory Event Header Set See Event Header Properties below.
Landing Date Time Mandatory String Date 24hr + UTC offset.
Landings Mandatory Array of landings Must have at least one landing record.

Can have many landings associated with the event.

Product details are also recorded against each landing.

See Landings Parameters below.

Event Header Properties:

ParameterRequiredData TypeValidation and Additional Notes
Event ID Mandatory String Must be unique for the event.

Log book generated unique identifier.

Trip ID Optional String Must be provided unless the landing is not associaied with a trip.
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.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not.
Vessel Number Conditional String Mandatory if 'Is Vessel Used' = True.

Must be a valid Vessel number.

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

Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Mandatory String

Date 24hr + UTC offset.

Must be provided for Create.

Must be null for Update. ERS will not accept the event if provided for update.

The date and time when the event data was completed in the Logbook. That is, when the status was set to “Complete”.

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

Landings Parameters Array:

ParameterRequiredData TypeValidation and Additional Notes
Landing Code Mandatory String

Must be a valid ERS landing code.

Validated against Landing Codes master data.

LFR Details Received Date Time Optional String

Date 24hr + UTC offset.

LFR Client Number Conditional String

Must be a valid Client number.

Must be provided if 'Landing Codes' master data property 'require_LFR_number = true' & 'LFR Details Received Date Time' has been provided.

Must not be provided for other landing codes.

Holding Receptable Location Conditional< Basic GeoLocation Set

Must be provided if 'Landing Codes' master data property 'require_holding_location = true'.

At least one group of system or manual location parameters must be provided if 'Address' is not provided.

Must not be provided for other landing codes.

See Holding Receptacle Location Parameters below.

Holding Receptacle Address Conditional String

Must be provided if one group of system or manual location parameters are not provided.

Maximum of 500 characters allowed.

Tranship Vessel Number Conditional String

Must be provided if 'Landing Codes' master data property 'require_vessel_number = true'.

Must not be provided for other landing codes.

Customary Fishing Document Reference Conditional String

Must be provided if 'Landing Codes' master data property 'require_customary_reference = true'.

Must not be provided for other landing codes.

Is Offal Mealed Optional Boolean Indicates if the offal has been processed as fish meal.
Oil Litres Optional Number

Must be a whole number.

Must be greater than 0.

Landing Products Mandatory Array of landing products Must have at least one product record.

See Landing Products Parameters below.

Holding Receptacle Location Parameters:

ParameterRequiredData TypeValidation and Additional Notes
System Location Conditional Geolocation

At least one group of system or manual location parameters must be provided.

See Geolocation parameters below.

Manual Location Conditional Geolocation

Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees

System Location: Minimum of 4dp required.

Manual Location: Minimum of 3dp required.

Longitude Mandatory decimal degrees 

System Location: Minimum of 4dp required.

Manual Location: Minimum of 3dp required.

Landing Products Parameters Array:

ParameterRequiredData TypeValidation and Additional Notes
Product State Code Mandatory String

Must be a valid ERS product state code.

Validated against Product States master data.

Container Type Code Mandatory String

Must be a valid ERS container type code.

Validated against Containers master data.

Estimated Container Weight Mandatory Number

Decimal to 2dp.

Must be greater than 0.

Container Count Mandatory Number

Must be a whole number.

Decimal to 2dp.

Must be greater than 0.

Total number of containers associated with the container type code.

Purchase Order Number Conditional String

Must be provided if 'Landing Codes' master data property 'require_purchase_order = true' and 'LFR Details Received Date Time' is provided.

Must not be provided for other landing codes.

Maximum of 50 characters allowed.

Stocks Conditional Array of stocks

Must have at least one stock record.

Multiple stocks allowed if 'Product States' master data property 'allow_multiple_fish_codes' = true.

>See Stocks Parameters Array below.

Stocks Parameters Array:

ParameterRequiredData TypeValidation and Additional Notes
Stock Code Conditional String

Must be a valid ERS stock code.

Validated against Fish Stock master data.

Green Weight Kg Conditional Number

Decimal to 2dp.

Must be provided and greater than '0' if 'Product States' master data property 'require_greenweight' = true, except when landing code is L, LP, LR, Q, T, EOY and 'LFR Details Received Date Time' is not provided.

Must not be provided if 'Product States' master data property 'require_greenweight' is not true.

Optional if 'Product States' master data property 'require_greenweight' = true, Landing code is L, LP, LR, Q, T, EOY and 'LFR Details Received Date Time' is not provided.

Shark Fins Weight Kg Conditional Number

Decimal to 2dp.

Must be provided and greater than 0 if 'Product States' master data property 'require_shark_fin_weight' = true, except when landing code is L, LP, LR, Q, T, EOY and 'LFR Details Received Date Time' is not provided.

Must not be provided if 'Product States' master data property 'require_shark_fin_weight' is not true.

Optional if 'Product States' master data property 'require_shark_fin_weight' = true, Landing code is L, LP, LR, Q, T, EOY and 'LFR Details Received Date Time' is not provided.

Landing Create Request Body Example:

 {
  "eventHeader": 
  {
    "eventId": "abcdef",
    "tripId": "TR1",
    "completedDateTime": "2017-07-27T09:15:00+11:00",
    "vesselNumber": "15527",
    "isVesselUsed": true,
    "notes": "Test notes",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "landingDateTime": "2017-10-28T09:15:00+11:00", "landings": [ { "landingCode": "Q",
"lfrDetailsReceivedDateTime": null, "lfrClientNumber": null, "holdingReceptacleAddress": null, "holdingReceptacleLocation": { "manualLocation": { "longitude": "-175.543", "latitude": "-45.987" }, "systemLocation": { "longitude": "-175.5432", "latitude": "-45.9878" } }, "transhipVesselNumber": null, "customaryFishingDocumentReference": null, "isOffalMealed": true, "oilLitres": 143, "landingProducts": [ { "productStateCode": "DSC", "containerTypeCode": "BIN", "estimatedContainerWeightKg": 22.22, "containerCount": 7, "purchaseOrderNumber": null, "stocks": [ { "stockCode" : "HOK1", "greenWeightKg" : 20.12 } ] } ] } ] }

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 Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

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

{
 "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."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/landing/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/landing/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Request Header:

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

Response

Response Status:

StatusDescription
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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String
Completed Date Time String
Landing Date Time String
Landings Array of landings
Errors Array
Amendment Reason String

Landings Parameters Array:

ParameterData Type
Landing Code String
LFR Details Received Date Time String
LFR Client Number String

Holding Receptacle Location

See Holding Receptacle Location Parameters below.

Basic GeoLocation Set
Holding Receptacle Address String
Tranship Vessel Number String
Customary Fishing Document Reference String
Is Offal Mealed Boolean
Oil Litres Number
Landing Products Array of landing products

Holding Receptacle Location Parameters:

ParameterData Type

System Location

See Geolocation Parameters below.

Geolocation

Manual Location

See Geolocation Parameters below.

Geolocation

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees


Landing Products Parameters Array:

ParameterData Type
Product State Code String
Container Type Code String
Estimated Container Weight Number
Container Count Number
Purchase Order Number String
Stocks Array of stocks

Stocks Parameters Array:

ParameterData Type
Stock Code String
Green Weight Kg Number
Shark Fins Weight Kg Number

Landing Get Request Body Example:

{
    "event": {
        "landingDateTime": "2017-10-28T09:15:00+11:00",
        "landings": [
            {
                "landingCode": "Q",
"lfrDetailsReceivedDateTime": null, "oilLitres": 143, "lfrClientNumber": null, "holdingReceptacleLocation": { "systemLocation": { "longitude": -175.5432, "latitude": -45.9878 }, "manualLocation": { "longitude": -175.543, "latitude": -45.987 } }, "holdingReceptacleAddress": null, "transhipVesselNumber": null, "landingProducts": [ { "productStateCode": "DSC", "stocks": [ { "stockCode": "HOK1", "greenWeightKg": 99.54, "sharkFinsWeightKg": null } ], "containerTypeCode": "BIN", "estimatedContainerWeightKg": 22.22, "containerCount": 7, "purchaseOrderNumber": null } ] } ], "tripId": "TR1", "vesselNumber": "15527", "isVesselUsed": true, "eventId": "abcdef", "schemaEdition": 1, "eventVersion": 2, "clientNumber": "8462926", "completedDateTime": "2017-07-27T09:15:00+11:00", "eventDateTime": "0001-01-01T00:00:00+00:00", "notes": "Test notes", "amendmentReason": null,
"completedByName": "Dirk Munroe" }, "errors": [] }

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/landing/{eventID}

Example:

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

Update URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameters.

The amended value of the fields that need to be updated will be passed in the request body.

ParameterRequiredData TypeDescription
Event Version Mandatory Number

The version of the event that the fisher is wanting to update.

Can only update the latest version of an event.

Landing Update Request Body Example:

{
  "eventHeader": 
  {
    "eventId": "abcdef",
    "tripId": "TR1",
    "eventVersion": 1,
    "completedDateTime": null,
    "vesselNumber": "15527",
    "isVesselUsed": true,
    "notes": "Test notes",
    "amendmentReason": "updating greenweight details",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "landingDateTime": "2017-10-28T09:15:00+11:00", "landings": [ { "landingCode": "Q",
"lfrDetailsReceivedDateTime": null, "lfrClientNumber": null, "holdingReceptacleAddress": null, "holdingReceptacleLocation": { "manualLocation": { "longitude": "-175.543", "latitude": "-45.987" }, "systemLocation": { "longitude": "-175.5432", "latitude": "-45.9878" } }, "transhipVesselNumber": null, "customaryFishingDocumentReference": null, "isOffalMealed": true, "oilLitres": 143, "landingProducts": [ { "productStateCode": "DSC", "containerTypeCode": "BIN", "estimatedContainerWeightKg": 22.22, "containerCount": 7, "purchaseOrderNumber": null, "stocks": [ { "stockCode" : "HOK1", "greenWeightKg" : 99.54 } ] } ] } ] }

Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeDescription
Errors Array List of errors, if any. See Errors 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.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}

Back to top