FishServe - FishServe API Technical Info

FishServe API Technical Info

Below is the technical information required for setting up the following APIs;

Authentication: See our Getting Started page for technical information
Public Client Info
Vessel Information
ACE Transfer
ACE Transfer History
ACE Transfer History Lines

This documentation is also available in pdf format: FishServe API Documentation.pdf

Available Test URL

https://register.demo.kupe.fishserve.co.nz/

Production URL

https://fishserve.co.nz/

FishServe Api Documentation

Public Client Info

Returns public information about a FishServe client.

Request

Request Url Parameters

Parameter	Required	Data type	Description
ClientNumber	Mandatory	String	The client

Request Url

GET https://api.demo.kupe.fishserve.co.nz/client/{clientNumber}/public-client-info

Example:

GET https://api.demo.kupe.fishserve.co.nz/client/12345678/public-client-info

Request Header

Content-Type: application/json
Authorization: Bearer YOUR_USER_TOKEN

Response

Response Parameters

Parameter	Data type	Description
ClientNumber	String	The client number
LegalName	String	The legal name of the client
TradingName	String	The trading name of the client
ClientStatus	String	The status of the client. Possible statuses: "Approved", "Cancelled"
PermitStatus	String	The status of the client's permit. Possible statuses: "Current", "Suspended", "No Current Permit", "Future Issued"
PermitStartDate	Date	The date the client is authorised to take fish from
PermitExpiryDate	Date	The date the authorisation finishes
PermitSuspensionStartDate	Date	The date the permit was suspended

Response Body

{
  "clientNumber": "{ClientNumber}",
  "legalName": "{LegalName}",
  "tradingName": "{TradingName}",
  "clientStatus": "{ClientStatus}",
  "permitStatus": "{PermitStatus}",
  "permitStartDate": "{PermitStartDate}",
  "permitExpiryDate": "{PermitExpiryDate}",
  "permitSuspensionStartDate": "{PermitSuspensionStartDate}"
}

Example:

{
  "clientNumber": "12345678",
  "legalName": "My Company limited",
  "tradingName": "My Company",
  "clientStatus": "Approved",
  "permitStatus": "Suspended",
  "permitStartDate": "2016-01-01T00:00:00",
  "permitExpiryDate": "2020-12-31T23:59:59",
  "permitSuspensionStartDate": "2016-05-01T00:00:00"
}

Vessel Information

Returns information about a vessel.

Request

Request Url Parameters

Parameter	Required	Data type	Description
VesselNumber	Mandatory	String	The registered vessel number

Request Url

GET https://licence.demo.kupe.fishserve.co.nz/api/vessels/get/{vesselNumber}

Example:

GET https://licence.demo.kupe.fishserve.co.nz/api/vessels/get/12345

Request Header

Content-Type: application/json

Response

Response Parameters

Parameter	Data type	Description
Vessel Name	String	The name of the vessel
Call sign	String	The call sign of the vessel
Valid From Date Time	String	The start date from when the vessel has been continuously registered to the Operator Client. Date 24hr + UTC offset
Valid To Date Time	String	The latest end date for the continuous vessel registration period for the Operator Client. This may be a future date. Date 24hr + UTC offset
Status	String	The status of the vessel registration. Possible statuses: "Current", "Expired", "Cancelled", "Issued".
Operator Client Number	String	The client number for the registered operator of the vessel

Response Body

{
    "VesselName": "{VesselName}",
    "CallSign": "{CallSign}",
    "ValidFromDateTime": "{ValidFromDateTime}",,
    "ValidToDateTime": "{ValidToDateTime}",
    "Status": "{Status}",
    "OperatorClientNumber": "{OperatorClientNumber}",
}

Example:

{
    "VesselName": "Princess",
    "CallSign": "ZMA1234",
    "ValidFromDateTime": "2004-10-01T00:00:00+12:00",
    "ValidToDateTime": "2018-03-31T23:59:59+13:00",
    "Status": "Current",
    "OperatorClientNumber": "7654321"
}

ACE Transfer

Performs an ACE transfer

Note: Transferor must be set up for invoice payments

Request

Request Url Parameters

Parameter	Required	Data type	Description
ClientNumber	Mandatory	String	Transferor for the ACE transfer

Request Url

GET https://api.demo.kupe.fishserve.co.nz/client/{clientNumber}/ace/transfer

Example:

GET https://api.demo.kupe.fishserve.co.nz/client/12345678/ace/transfer

Request Header

Content-Type: application/json
Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters

Parameter	Required	Data type	Description
TransferorClientNumber	Mandatory	String	Transferor for the ACE transfer
TransferorLegalName	Mandatory	String	Legal name of the transferor
TransfereeClientNumber	Mandatory	String	Transferee for the ACE transfer
TransfereeLegalName	Mandatory	String	Legal name of the transferee
FishingYear	Mandatory	Date	Fishing year of the ACE transfer. Must be an open, or future fishing year
StockCode	Mandatory	String	Stock code of ACE to transfer
AceType	Mandatory	String	Type of ACE to transfer. Valid options: "Regular ACE", "TAC ACE"
Quantity	Mandatory	Number	Amount of ACE to transfer
Price	Mandatory	Decimal	The total price for the stock being transferred

Request Body

{
  "transferee": {
    "clientNumber": "{TransfereeClientNumber}",
    "legalName": "{TransfereeLegalName}"
  },
  "transferor": {
    "clientNumber": "{TransferorClientNumber}",
    "legalName": "{TransferorLegalName}"
  },
  "fishingYear": "{FishingYear}",
  "lines": [
    {
      "stockCode": "{StockCode}",
      "aceType": "{AceType}",
      "quantity": "{Quantity}",
      "price": "{Price}"
    }
  ]
}

Example:

{
  "transferee": {
    "clientNumber": "1234567",
    "legalName": "Client 1 Legal Name"
  },
  "transferor": {
    "clientNumber": "7654321",
    "legalName": "Client 2 Legal Name"
  },
  "fishingYear": "2015-10-01T00:00:00",
  "lines": [
    {
      "stockCode": "HOK1",
      "aceType": "Regular ACE",
      "quantity": 100,
      "price": 100.0
    }
  ]
}

Response

Response Parameters

Parameter	Data type	Description
DocumentNumber	String	The document number of the ACE transfer
Status	String	The status of the ACE transfer. Possible options: "placed", "pendingplaced"

Response Body

{
  "documentNumber": "{DocumentNumber}",
  "status": "{Status}"
}

Example:

{
  "documentNumber": "ATR1000624",
  "status": "placed"
}

ACE Transfer History

Returns a list of ACE Transactions for a client. These transactions include purchases and sales or deductions of ACE (ACE Transfers) and all Allocations (Annual, Underfishing, Preseason and TAC)

Request

Request Url Parameters

Parameter	Required	Data type	Description
ClientNumber	Mandatory	String	The client involved in the ACE Transaction
FromDate	Optional	Date	Filters transactions registered before this date
ToDate	Optional	Date	Filters transactions registered after this date

Request Url

GET https://api.demo.kupe.fishserve.co.nz/client/{clientNumber}/ace/transferhistory/?FromDate={FromDate}&ToDate={ToDate}

Example:

GET https://api.demo.kupe.fishserve.co.nz/client/12345678/ace/transferhistory

GET https://api.demo.kupe.fishserve.co.nz/client/12345678/ace/transferhistory/?FromDate=2015-10-01

GET https://api.demo.kupe.fishserve.co.nz/client/12345678/ace/transferhistory/?FromDate=2015-10-01&ToDate=2016-10-01

Request Header

Content-Type: application/json
Authorization: Bearer YOUR_USER_TOKEN

Response

Response Parameters

Parameter	Data type	Description
TransferorClientNumber	String	Transferor of the ACE transfer
TransferorLegalName	String	Legal name of the transferor
TransferorTradingName	String	Trading name of the transferor
TransfereeClientNumber	String	Transferee of the ACE transfer
TransfereeLegalName	String	Legal name of the transferee
TransfereeTradingName	String	Trading name of the transferee
Status	String	The status of the transfer
FishingYear	Date	Fishing year the ACE transfer is for
RegisteredDate	Date	Date the ACE transfer was registered
DocumentNumber	String	Document number of the ACE transfer
TransferType	String	Type of ACE transfer

Response Body

[
  {
    "transferor": {
      "clientNumber": "{TransferorClientNumber}",
      "legalName": "{TransferorLegalName}",
      "tradingName": "{TransferorTradingName}"
    },
    "transferee": {
      "clientNumber": "{TransfereeClientNumber}",
      "legalName": "{TransfereeLegalName}",
      "tradingName": "{TransfereeTradingName}"
    },
    "status": "{Status}",
    "fishingYear": "{FishingYear}",
    "registeredDate": "{RegisteredDate}",
    "documentNumber": "{DocumentNumber}",
    "transferType": "{TransferType}"
  }
]

Example:

[
  {
    "transferor": {
      "clientNumber": "7654321",
      "legalName": "Client 2 Legal Name",
      "tradingName": "Client 2 Trading Name"
    },
    "transferee": {
      "clientNumber": "1234567",
      "legalName": "Client 1 Legal Name",
      "tradingName": "Client 1 Trading Name"
    },
    "status": "Registered",
    "fishingYear": "2015-10-01T00:00:00",
    "registeredDate": "2016-04-15T00:00:00",
    "documentNumber": "ATR1000624",
    "transferType": "Regular Transfer FA96-s133"
  }
]

ACE Transfer History Lines

Returns all of the stocks included in the transaction

Request

Request Url Parameters

Parameter	Required	Data type	Description
ClientNumber	Mandatory	String	The client involved in the ACE Transaction
DocumentNumber	Mandatory	String	The ACE Transaction document number

Request Url

GET https://api.demo.kupe.fishserve.co.nz/client/{clientNumber}/ace/transfer/{documentNumber}

Example:

GET https://api.demo.kupe.fishserve.co.nz/client/12345678/ace/transfer/ABC123456

Request Header

Content-Type: application/json
Authorization: Bearer YOUR_USER_TOKEN

Response

Response Parameters

Parameter	Data type	Description
TransferorClientNumber	String	Transferor of the ACE transfer
TransferorLegalName	String	Legal name of the transferor
TransferorTradingName	String	Trading name of the transferor
TransfereeClientNumber	String	Transferee of the ACE transfer
TransfereeLegalName	String	Legal name of the transferee
TransfereeTradingName	String	Trading name of the transferee
Status	String	The status of the transfer
FishingYear	Date	Fishing year the ACE transfer is for
RegisteredDate	Date	Date the ACE transfer was registered
DocumentNumber	String	Document number of the ACE transfer
TransferType	String	Type of ACE transfer
StockCode	String	Stock code of ACE transfered
AceType	String	Type of ACE transfered. Possible options: "Regular ACE", "TAC ACE"
Quantity	Number	Amount of ACE transfered
TotalPrice	Decimal	The total price of the transferred stock

Response Body

{
  "lines": [
    {
      "stockCode": "{StockCode}",
      "aceType": "{AceType}",
      "quantity": "{Quantity}",
      "totalPrice": "{TotalPrice}"
    }
  ],
  "transferor": {
    "clientNumber": "{TransferorClientNumber}",
    "legalName": "{TransferorLegalName}",
    "tradingName": "{TransferorTradingName}"
  },
  "transferee": {
    "clientNumber": "{TransfereeClientNumber}",
    "legalName": "{TransfereeLegalName}",
    "tradingName": "{TransfereeTradingName}"
  },
  "status": "{Status}",
  "fishingYear": "{FishingYear}",
  "registeredDate": "{RegisteredDate}",
  "documentNumber": "{DocumentNumber}",
  "transferType": "{TransferType}"
}

Example:

{
  "lines": [
    {
      "stockCode": "HOK1",
      "aceType": "Regular ACE",
      "quantity": 100,
      "totalPrice": 100.0
    }
  ],
  "transferor": {
    "clientNumber": "7654321",
    "legalName": "Client 2 Legal Name",
    "tradingName": "Client 2 Trading Name"
  },
  "transferee": {
    "clientNumber": "1234567",
    "legalName": "Client 1 Legal Name",
    "tradingName": "Client 1 Trading Name"
  },
  "status": "Registered",
  "fishingYear": "2015-10-01T00:00:00",
  "registeredDate": "2016-04-15T00:00:00",
  "documentNumber": "ATR1000624",
  "transferType": "Regular Transfer FA96-s133"
}