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

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:

Request Header:

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

Request Body Parameters:

Event Header Properties:

Landings Parameters Array:

Holding Receptacle Location Parameters:

Geolocation Parameters:

Landing Products Parameters Array:

Stocks Parameters Array:

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:

Response Parameters:

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

Errors Parameters:

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:

Request Header:

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

Response

Response Status:

Response Body Parameters:

Landings Parameters Array:

Holding Receptacle Location Parameters:

Geolocation Parameters:

Landing Products Parameters Array:

Stocks Parameters Array:

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:

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.

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:

Response Parameters:

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

Errors Parameters:

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