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
Users for a Client
User Information
Vessel Information
ACE Transfer
ACE Transfer History
ACE Transfer History Lines

Available Test URL

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

Production URL

https://fishserve.co.nz/

FishServe Api Documentation

Public Client Info

Returns public information about a FishServe client.

Authentication required: None

Request

Request Url Parameters

Parameter	Required	Data type	Description
Client Number	Mandatory	String	The client

Request Url

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

Example:

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

Request Header

Content-Type: application/json

Response

Response Parameters

Parameter	Data type	Description
Client Number	String	The client number
Legal Name	String	The legal name of the client
Trading Name	String	The trading name of the client
Client Status	String	The status of the client. Possible statuses: "Approved", "Cancelled"
Permit Status	String	The status of the client's permit. Possible statuses: "Current", "Suspended", "No Current Permit", "Future Issued"
Permit Start Date	Date	The date the client is authorised to take fish from
Permit Expiry Date	Date	The date the authorisation finishes
Permit Suspension Start Date	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"
}

Users for a Client

Returns a list of users for a client for a particular area such as ACE or ERS.

Authentication required: Bearer token

Request

Request Url Parameters

Parameter	Required	Data type	Description
Client Number	Mandatory	String	The client
Area	Mandatory	String	The area for which the user is approved. Options are; ACE, Client, ERS, Finance, LFR Licence, Permit, Quota, Returns, Vessels.

Request Url

GET https://client.uat.kupe.fishserve.co.nz/api/clients/{clientNumber}/usersForBusinessArea/{area}

Example:

GET https://client.uat.kupe.fishserve.co.nz/api/clients/1234567/usersForBusinessArea/ers

Request Header

Content-Type: application/json
Authorization: Bearer YOUR_USER_TOKEN

Response

Response Parameters

Parameter	Data type	Description
User Id	String	The unique ID number of the user.
First Name	String	The first name of the user.
Prefered Name	String	The prefered name of the user.
Surname	String	The surname of the user.
Email Address	String	The email address of the user.
Authorisation Role	String	The role the user is approved to perform for the client. For example; Manager, Viewer, or Reporter.

Response Body

    {
        "UserId": "{UserId}",
        "FirstName": "{FirstName}",
        "PreferedName": "{PreferedName}",
        "Surname": "{Surname}",
        "EmailAddress": "{EmailAddress}",
        "AuthorisationRole": "{AuthorisationRole}"
    }

Example:

[
    {
        "UserId": 23,
        "FirstName": "Peter",
        "PreferedName": null,
        "Surname": "One",
        "EmailAddress": "peter.one@fishserve.co.nz",
        "AuthorisationRole": "Manager"
    },
    {
        "UserId": 25,
        "FirstName": "Douglas",
        "PreferedName": "Doug",
        "Surname": "Two",
        "EmailAddress": "doug.two@fishserve.co.nz",
        "AuthorisationRole": "Reporter"
    },
    {
        "UserId": 5383,
        "FirstName": "Mary",
        "PreferedName": null,
        "Surname": "Three",
        "EmailAddress": "mary.three@fishserve.co.nz",
        "AuthorisationRole": "Viewer"
    }
]

User Information

Returns a list of clients that a user has authorisations to.

Authentication required: Bearer token

Request

Request Url

GET https://api.uat.kupe.fishserve.co.nz/user

Request Header

Content-Type: application/json
Authorization: Bearer YOUR_USER_TOKEN

Response

Response Parameters

Parameter	Data type	Description
Title	String	The title of the user.
First Name	String	The first name of the user.
Surname	String	The surname of the user.
Preferred Name	String	The prefered name of the user.
Middle Name	String	The middle name of the user.
Email Address	String	The email address of the user.
Client Number	String	The client number.
Legal Name	String	The legal name of the client.
Trading Name	String	The trading name of the client.
Authorisations	String	List all the authorisations the user has for the client e.g. ACE Manager, ERS Reporter.

Response Body

{
        "user_info": {
        "title": "{Title}",
        "firstName": "{FirstName}",
        "surname": "{Surname}",
        "preferedName": "{PreferedName}",
        "middleName": "{MiddleName}",
        "emailAddress": [ 
                "{EmailAddress}"
         ]
      },
      "clients": [
        {
        "clientNumber": "{ClientNumber}",
        "legalName": "{LegalName}",
        "tradingName": "{TradingName}",
        "authorisations": [
                "{ClientAuthorisations}"
        }
      ]
}

Example:

{  
        "user_info": {
        "title": "Mr",
        "firstName": "Max",
        "surname": "Fisher",
        "preferedName": null,
        "middleName": null,
        "emailAddress": [ 
           "max.fisher@quotamanagers.co.nz",
        ]
     },
     "clients": [
        {
            "clientNumber": "7700001"
            "legalName": "Acme Fishing Company",
            "tradingName": null,         
            "authorisations": [
               "ACE Manager",
               "Catch Effort Manager",
               "Client Manager",
               "Finance Manager",
               "LFR Manager",
               "Permit Manager",
               "Quota Manager",
               "Returns Manager",
               "Vessel Manager"
               ]
        },
        {
            "clientNumber": "6600001",
            "legalName": "A Fishing Company",
            "tradingName": null
            "authorisations": [
               "ACE Manager",
               "Catch Effort Manager",
               "Client Manager",
               "ERS Viewer",
               "Finance Manager",
               "LFR Manager",
               "Permit Manager",
               "Quota Manager",
               "Returns Manager",
               "Vessel Manager"
               ]
         }
     ]
}

Vessel Information

Returns information about a vessel.

Authentication required: None

Request

Request Url Parameters

Parameter	Required	Data type	Description
Vessel Number	Mandatory	String	The registered vessel number

Request Url

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

Example:

GET https://licence.uat.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

Authentication required: Bearer token

Request

Request Url Parameters

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

Request Url

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

Example:

GET https://api.uat.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
Transferor Client Number	Mandatory	String	Transferor for the ACE transfer
Transferor Legal Name	Mandatory	String	Legal name of the transferor
Transferee Client Number	Mandatory	String	Transferee for the ACE transfer
Transferee Legal Name	Mandatory	String	Legal name of the transferee
Fishing Year	Mandatory	Date	Fishing year of the ACE transfer. Must be an open, or future fishing year
Stock Code	Mandatory	String	Stock code of ACE to transfer
Ace Type	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
Document Number	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)

Authentication required: Bearer token

Request

Request Url Parameters

Parameter	Required	Data type	Description
Client Number	Mandatory	String	The client involved in the ACE Transaction
From Date	Optional	Date	Filters transactions registered before this date
To Date	Optional	Date	Filters transactions registered after this date

Request Url

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

Example:

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

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

GET https://api.uat.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
Transferor Client Number	String	Transferor of the ACE transfer
Transferor Legal Name	String	Legal name of the transferor
Transferor Trading Name	String	Trading name of the transferor
Transferee Client Number	String	Transferee of the ACE transfer
Transferee Legal Name	String	Legal name of the transferee
Transferee Trading Name	String	Trading name of the transferee
Status	String	The status of the transfer
Fishing Year	Date	Fishing year the ACE transfer is for
Registered Date	Date	Date the ACE transfer was registered
Document Number	String	Document number of the ACE transfer
Transfer Type	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

Authentication required: Bearer token

Request

Request Url Parameters

Parameter	Required	Data type	Description
Client Number	Mandatory	String	The client involved in the ACE Transaction
Document Number	Mandatory	String	The ACE Transaction document number

Request Url

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

Example:

GET https://api.uat.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
Transferor Client Number	String	Transferor of the ACE transfer
Transferor Legal Name	String	Legal name of the transferor
Transferor Trading Name	String	Trading name of the transferor
Transferee Client Number	String	Transferee of the ACE transfer
Transferee Legal Name	String	Legal name of the transferee
Transferee Trading Name	String	Trading name of the transferee
Status	String	The status of the transfer
Fishing Year	Date	Fishing year the ACE transfer is for
Registered Date	Date	Date the ACE transfer was registered
Document Number	String	Document number of the ACE transfer
Transfer Type	String	Type of ACE transfer
Stock Code	String	Stock code of ACE transfered
Ace Type	String	Type of ACE transfered. Possible options: "Regular ACE", "TAC ACE"
Quantity	Number	Amount of ACE transfered
Total Price	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"
}