FishServe - Processing Event

Processing Event

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

**Change history**
Date	Change	Schema	Schema Valid From	Schema Valid To
21/12/2018	Released to production
08/11/2018	Changed Container Count from integer to decimal to 2dp	v2	01/07/2018
11/06/2018	Removed Oil Litres	v2	01/07/2018
18/05/2017	Initial publication	v1	01/10/2017	30/09/2018

For UAT schema valid dates click here.

Create

Request URL:

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

Example:

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

Create URL Parameters:

Parameter	Required	Data type	Validation and Additional Notes
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:

Parameter	Required	Data Type	Validation and Additional Notes
Event Header	Mandatory	Event Header Set	See Event Header Properties below.
Processing Date Time	Mandatory	String	Date 24hr + UTC offset.
Products	Mandatory	Array of Products	Must have at least one product record. Can have many products associated with a processing event. Species details are also recorded against each product. See Products Parameters below.

Parameter

Required

Data Type

Validation and Additional Notes

Event Header

Mandatory

Event Header Set

See Event Header Properties below.

Processing Date Time

Mandatory

String

Date 24hr + UTC offset.

Products

Mandatory

Array of Products

Must have at least one product record.

Can have many products associated with a processing event.

Species details are also recorded against each product.

See Products Parameters 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.
Trip ID	Mandatory	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.
Is Vessel Used	Mandatory	Boolean	Identifies if the fishing took place on a vessel or not.
Vessel Number	Mandatory	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.
Notes	Optional	String	The Fisher may record additional information relating to the event.
Completed Date Time	Conditional	String	Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update. Date 24hr + UTC offset.
Amendment Reason	Conditional	String	Must be provided for Update. Must be null for Create. ERS will not accept the event if provided for create.

Products Parameters Array:

Parameter	Required	Data Type	Validation and Additional Notes
Product State Code	Mandatory	String	Must be a valid ERS product state code. Validated against product-states master data. Must have at least one Product State for a Processing event.
Species	Conditional	Array of species	If Product States master data property 'allow_multiple_fish_codes' = 'True' then one or more species codes may be supplied within the species array. Else, only one species code may be supplied within the species array. See Species Parameters Array below.
Container Type Code	Mandatory	String	Must be a valid ERS container type code. Validated against containers master data.
Estimated Container Weight Kg	Mandatory	Number	Decimal to 2dp. Must be greater than 0. Per container.
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.
Conversion Factor	Conditional	Number	Decimal to 2dp. Must be provided if 'Product States' master data property 'require_conversion_factor' = 'True' and must equal (in hierarchical order) one of the following: Species-specific CF; else, Species Category-specific CF NOTE: If a Species/Product State combination supplied has a NULL CF in the Species-specific CF table, then combination of Species and Product State is an invalid one.
Oil Litres	Optional	Number	Must be a whole number. Must be greater than 0.

Species Parameters Array:

Parameter	Required	Data Type	Validation and Additional Notes
Species Code	Conditional	String	Must be a valid ERS species code. Validated against Fish Species 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'. Otherwise, must not be provided.

Parameter

Required

Data Type

Validation and Additional Notes

Species Code

Conditional

String

Must be a valid ERS species code.

Validated against Fish Species 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'.

Otherwise, must not be provided.

Processing Create Request Body Example:

{
  "eventHeader": {
    "eventId": "256",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes" : "Some notes",  
    "completedDateTime": "2017-05-17T15:34:12+13:00",
    "tripId": "123",
    "softwareVendor": "ERS-FishServe",
    "softwareVersion": "1.1.2",
    "softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
    "clientNumber": "1234567",
    "completerUserId": "1234"
  },
  "processingDateTime": "2017-05-17T15:34:12+13:00",
  "products": [
    {
                "productStateCode": "DRE",
                "species": [ {"speciesCode":"KIN",
                "greenWeightKg":25.5}
               
                                ],
                "containerTypeCode": "BAG",
                "containerCount": 2,
                "estimatedContainerWeightKg": 12.3,
                "conversionFactor": 1.6
    },
    {
                "productStateCode": "FIT",
                                "species": [ 
                                  {
                                "speciesCode": "KIN",
                                "greenWeightKg": null
                  }
                                ],
                "containerTypeCode": "SAC",
                "containerCount": 14,
                "estimatedContainerWeightKg": 99.9,
                "conversionFactor": null
    }

  ]
}

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

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

Parameter	Data Type	Validation and Additional Notes
Errors	Array	List of errors, if any. See Errors Parameters below.

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

{
 "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/processing/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

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

Get URL Parameters:

Parameter	Required	Data type	Validation and Additional Notes
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 URL and private key.

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
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
Processing Date Time	String
Completed Date Time	String
Errors	Array
Amendment Reason	String
Products See Products Parameters below.	Array of Products

Products Parameters Array:

Parameter	Data Type
Product State Code	String
Species See Products Parameters below.	Array of Species
Container Type Code	String
Estimated Container Weight Kg	Number
Container Count	Number
Conversion Factor	Number
Oil Litres	Number

Species Parameters Array:

Parameter	Data Type
Species Code	String
Green Weight Kg	Number

Processing Get Request Body Example:

{
  "event": {
    "processingDateTime": "2017-05-17T15:34:12+13:00",
    "products": [
      {
        "productStateCode": "DRE",
        "species": [
          {
            "speciesCode": "KIN",
            "greenWeightKg": 25.5
          }
        ],
        "containerTypeCode": "BAG",
        "estimatedContainerWeightKg": 12.3,
        "containerCount": 2,
        "conversionFactor": 1.6
      },
      {
        "productStateCode": "FIT",
        "species": [
          {
            "speciesCode": "KIN",
            "greenWeightKg": null
          }
        ],
        "containerTypeCode": "SAC",
        "estimatedContainerWeightKg": 99.9,
        "containerCount": 14,
        "conversionFactor": null
      }
    ],
    "tripId": "123",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "eventId": "256abc",
    "schemaEdition": 1,
    "eventVersion": 1,
    "clientNumber": "8462926",
    "completedDateTime": "2017-05-17T15:34:12+13:00",
    "notes": "Some notes",
    "amendmentReason": null,
    "completedByName": "Dirk Munroe"
  },
  "errors": []
}

Update

Request URL:

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

Example:

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

Update URL Parameters:

Parameter	Required	Data type	Validation and Additional Notes
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 parameter.

This parameter is a property of the Event Header Set.

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

Parameter	Required	Data Type	Validation and Additional Notes
Event Version	Mandatory	Number	The version of the event that the fisher is wanting to update.

Processing Update Request Body Example:

 
{
  "eventHeader": {
    "eventId": "256abc",
    "eventVersion": 1,
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes" : "Some notes",  
    "amendmentReason": "mistake in original",
    "tripId": "123",
    "softwareVendor": "ERS-FishServe",
    "softwareVersion": "1.1.2",
    "softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
    "clientNumber": "1234567",
    "completerUserId": "1234"
  },
  "processingDateTime": "2017-06-17T15:34:12+13:00",
  "products": [
    {
                "productStateCode": "DRE",
                "species": [ {"SpeciesCode":"KIN",
                "greenWeightKg":25.5}
               
                                ],
                "containerTypeCode": "BAG",
                "containerCount": 2,
                "unitWeightKg": 4.5,
                "estimatedContainerWeightKg": 12.3,
                "conversionFactor": 1.6
    },
    {
                "productStateCode": "FIT",
                                "species": [ 
                                  {
                                "speciesCode": "KIN",
                                "greenWeightKg": null
                  }
                                ],
                "containerTypeCode": "SAC",
                "containerCount": 14,
                "estimatedContainerWeightKg": 99.9,
                "conversionFactor": null
    }

  ]
}

Response

Response Status:

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

Parameter	Data Type	Validation and Additional Notes
Errors	Array	List of errors, if any. See Errors Parameters below.

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:

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