Actual Cost Records API design

API for manipulating Actual Cost Records is split into two parts:

Actual Cost Fee/Fine API in mod-feesfines

1) Bill actual cost record

POST /actual-cost-fee-fine/bill

Request
{
  "actualCostRecordId": "89105c06-dbdb-4aa0-9695-d4d19c733270",
  "amount": 9.99,
  "servicePointId": "a5cea7c9-17b5-44b1-add3-ec43311451a8",
  "additionalInfoForStaff": "Additional information for staff",
  "additionalInfoForPatron": "Additional information for patron"
}

Where "servicePointId" is the ID of the service point currently selected in the UI.


In case of success mod-feesfines will:

  • create a fee/fine ("account") with requested amount
  • create corresponding "charge" fee/fine action
  • mark actual cost record as billed
  • link actual cost record to the created fee/fine ("account") by adding "accountId" to it
  • copy additional information from billing request to actual cost record
  • return updated actual cost record in response
Response 201
{
  "id": "89105c06-dbdb-4aa0-9695-d4d19c733270",
  "status": "Billed",
  "accountId": "df7f4993-8c14-4a0f-ab63-93975ab01c76",
  "additionalInfoForStaff": "Additional information for staff",
  "additionalInfoForPatron": "Additional information for patron",
  "lossType": "Declared lost",
  "lossDate": "2022-09-29T07:42:43.905+00:00",
  "expirationDate": "2022-09-29T07:42:43.905+00:00",
  "user": {
    "id": "f6df27bd-0db0-4fa1-afff-0ccd30cefb1b",
    "barcode": "test",
    "firstName": "Worm",
    "lastName": "Book",
    "middleName": "~"
  },
  "loan": {
    "id": "5cb70208-1147-4cfc-b481-31c575b8de44"
  },
  "item": {
    "id": "0149342a-e0fd-451e-8595-8fd0a0593a92",
    "barcode": "test2",
    "materialTypeId": "d9acad2f-2aac-4b48-9097-e6ab85906b25",
    "materialType": "text",
    "permanentLocationId": "53cf956f-c1df-410b-8bea-27f712cca7c0",
    "permanentLocation": "Annex",
    "effectiveLocationId": "5513cf26-a45c-482e-a25a-3ce5c32e619c",
    "effectiveLocation": "Main library",
    "loanTypeId": "2e48e713-17f3-4c13-a9f8-23845bb210a4",
    "loanType": "Reading room",
    "holdingsRecordId": "68872d8a-bf16-420b-829f-206da38f6c10",
    "effectiveCallNumberComponents": {
      "callNumber": "some-callnumber"
    }
  },
  "instance": {
    "id": "6506b79b-7702-48b2-9774-a1c538fdd34e",
    "title": "Nod",
    "identifiers": [{
        "value": "0956687695",
        "identifierType": "ISBN",
        "identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422"
      }, {
        "value": "9780956687695",
        "identifierType": "ISBN",
        "identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422"
      }
    ],
    "contributors": [{
        "name": "Schmitz, Bettina"
      }
    ]   
  },
  "feeFine": {
    "accountId": "306339a5-539b-4652-be7c-ab041a286c8c",
    "ownerId": "21b0d0f2-d258-4410-8a19-a37da35728a8",
    "owner": "owner",
    "typeId": "73785370-d3bd-4d92-942d-ae2268e02ded",
    "type": "Lost item fee (actual cost)"
  },
  "metadata": {
    "createdDate": "2022-09-29T07:42:43.980+00:00",
    "createdByUserId": "7ca9bcf4-ac58-519d-bc84-77d1da782742",
    "updatedDate": "2022-09-29T07:42:43.980+00:00",
    "updatedByUserId": "7ca9bcf4-ac58-519d-bc84-77d1da782742"
  }
}
Response 422
{
  "errors": [{
      "message": "Actual cost record 89105c06-dbdb-4aa0-9695-d4d19c733270 is already billed",
      "parameters": [{
          "key": "id",
          "value": "89105c06-dbdb-4aa0-9695-d4d19c733270"
        }, {
          "key": "status",
          "value": "Billed"
        }
      ]
    }
  ]
}
Response 500
Internal server error

2) Cancel actual cost record

POST /actual-cost-fee-fine/cancel

Request
{
  "actualCostRecordId": "89105c06-dbdb-4aa0-9695-d4d19c733270",
  "additionalInfoForStaff": "Additional information for staff"
}

In case of success mod-feesfines will:

  • mark requested actual cost record as cancelled
  • copy additional info from request to actual cost record
  • return updated actual cost record in response
Response 201
{
  "id": "89105c06-dbdb-4aa0-9695-d4d19c733270",
  "status": "Cancelled",
  "additionalInfoForStaff": "Additional information for staff",
  "lossType": "Declared lost",
  "lossDate": "2022-09-29T07:42:43.905+00:00",
  "expirationDate": "2022-09-29T07:42:43.905+00:00",
  "user": {
    "id": "f6df27bd-0db0-4fa1-afff-0ccd30cefb1b",
    "barcode": "test",
    "firstName": "Worm",
    "lastName": "Book",
    "middleName": "~"
  },
  "loan": {
    "id": "5cb70208-1147-4cfc-b481-31c575b8de44"
  },
  "item": {
    "id": "0149342a-e0fd-451e-8595-8fd0a0593a92",
    "barcode": "test2",
    "materialTypeId": "d9acad2f-2aac-4b48-9097-e6ab85906b25",
    "materialType": "text",
    "permanentLocationId": "53cf956f-c1df-410b-8bea-27f712cca7c0",
    "permanentLocation": "Annex",
    "effectiveLocationId": "5513cf26-a45c-482e-a25a-3ce5c32e619c",
    "effectiveLocation": "Main library",
    "loanTypeId": "2e48e713-17f3-4c13-a9f8-23845bb210a4",
    "loanType": "Reading room",
    "holdingsRecordId": "68872d8a-bf16-420b-829f-206da38f6c10",
    "effectiveCallNumberComponents": {
      "callNumber": "some-callnumber"
    }
  },
  "instance": {
    "id": "6506b79b-7702-48b2-9774-a1c538fdd34e",
    "title": "Nod",
    "identifiers": [{
        "value": "0956687695",
        "identifierType": "ISBN",
        "identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422"
      }, {
        "value": "9780956687695",
        "identifierType": "ISBN",
        "identifierTypeId": "8261054f-be78-422d-bd51-4ed9f33c3422"
      }
    ],
    "contributors": [{
        "name": "Schmitz, Bettina"
      }
    ]
  },
  "feeFine": {
    "ownerId": "21b0d0f2-d258-4410-8a19-a37da35728a8",
    "owner": "owner",
    "typeId": "73785370-d3bd-4d92-942d-ae2268e02ded",
    "type": "Lost item fee (actual cost)"
  },
  "metadata": {
    "createdDate": "2022-09-29T07:42:43.980+00:00",
    "createdByUserId": "7ca9bcf4-ac58-519d-bc84-77d1da782742",
    "updatedDate": "2022-09-29T07:42:43.980+00:00",
    "updatedByUserId": "7ca9bcf4-ac58-519d-bc84-77d1da782742"
  }
}
Response 422
{
  "errors": [{
      "message": "Actual cost record 89105c06-dbdb-4aa0-9695-d4d19c733270 is already cancelled",
      "parameters": [{
          "key": "id",
          "value": "89105c06-dbdb-4aa0-9695-d4d19c733270"
        }, {
          "key": "status",
          "value": "Cancelled"
        }
      ]
    }
  ]
}
Response 500
Internal server error