Retrieve Book Register List

Overview

The RetrieveBookRegistersListQuery retrieves a paginated list of book registers (cheque books, deposit slips, withdrawal slips) with comprehensive filtering options.

API Endpoint

POST /api/bpm/cmd

Headers

Content-Type: application/json
Authorization: Bearer {access_token}
X-Tenant-ID: {tenant_id}

Request Structure

{
  "cmd": "RetrieveBookRegistersListQuery",
  "data": {
    "depositAccountId": 12345,
    "bookType": 1,
    "status": 1,
    "searchText": "string",
    "pageNumber": 1,
    "pageSize": 20,
    "startDate": "2024-01-01",
    "endDate": "2024-12-31",
    "isExport": false
  }
}

Request Fields

Field	Type	Required	Description	Default
depositAccountId	long	No	Filter by specific deposit account ID	-
bookType	integer	No	Filter by book type (1=Cheque, 2=DepositSlip, 3=WithdrawalSlip)	-
status	integer	No	Filter by status (1=ACTIVE, 2=INACTIVE, 3=BLOCKED)	-
searchText	string	No	Search in account number, book reference, serial numbers	-
pageNumber	integer	No	Page number to retrieve	1
pageSize	integer	No	Number of records per page	20
startDate	string	No	Filter by issued date start (YYYY-MM-DD)	-
endDate	string	No	Filter by issued date end (YYYY-MM-DD)	-
isExport	boolean	No	Export to Excel (ignores pagination)	false

Book Type Values

• 1 - Cheque (for making payments)
• 2 - DepositSlip (for cash/cheque deposits)
• 3 - WithdrawalSlip (for cash withdrawals)

Status Values

• 1 - ACTIVE (book is currently usable)
• 2 - INACTIVE (book is deactivated)
• 3 - BLOCKED (book is blocked for security reasons)

Sample Request

{
  "cmd": "RetrieveBookRegistersListQuery",
  "data": {
    "depositAccountId": 12345,
    "bookType": 1,
    "status": 1,
    "pageNumber": 1,
    "pageSize": 20
  }
}

Response Structure

Success Response

{
  "isSuccessful": true,
  "message": "20/45 book registers retrieved successfully.",
  "statusCode": "00",
  "data": {
    "items": [
      {
        "id": 789,
        "bookType": 1,
        "bookTypeDescription": "Cheque",
        "bookReference": "CHQ-2024-001",
        "depositAccountId": 12345,
        "accountNumber": "1234567890",
        "clientId": 67890,
        "clientName": "John Doe",
        "issuingBranchId": 5,
        "branchName": "Main Branch",
        "branchKey": "MB001",
        "currencyCode": "NGN",
        "currencyName": "Nigerian Naira",
        "startSerialNumber": "0001001",
        "endSerialNumber": "0001050",
        "numberOfLeaves": 50,
        "issuedDate": "2024-12-01T00:00:00Z",
        "status": 1,
        "statusDescription": "ACTIVE",
        "isActive": true,
        "remarks": "Initial cheque book issuance",
        "createdAt": "2024-12-01T10:30:00Z",
        "createdBy": "admin@bank.com",
        "updatedAt": "2024-12-01T10:30:00Z",
        "updatedBy": "admin@bank.com"
      }
    ],
    "pageNumber": 1,
    "pageSize": 20,
    "totalPages": 3,
    "totalRecords": 45
  },
  "size": 20,
  "count": 45,
  "pages": 3,
  "hasNext": true,
  "hasPrevious": false
}

Error Response

{
  "isSuccessful": false,
  "message": "Error description",
  "statusCode": "99",
  "data": null
}

Use Cases

1. Get All Active Cheque Books for Account

{
  "cmd": "RetrieveBookRegistersListQuery",
  "data": {
    "depositAccountId": 12345,
    "bookType": 1,
    "status": 1
  }
}

2. Search by Serial Number

{
  "cmd": "RetrieveBookRegistersListQuery",
  "data": {
    "searchText": "0001050"
  }
}

3. Get Books Issued in Date Range

{
  "cmd": "RetrieveBookRegistersListQuery",
  "data": {
    "startDate": "2024-01-01",
    "endDate": "2024-12-31",
    "pageSize": 50
  }
}

4. Export All Blocked Books

{
  "cmd": "RetrieveBookRegistersListQuery",
  "data": {
    "status": 3,
    "isExport": true
  }
}

5. Get Withdrawal Slips for Branch

{
  "cmd": "RetrieveBookRegistersListQuery",
  "data": {
    "bookType": 3,
    "searchText": "MB001"
  }
}

Notes

• When isExport is set to true, pagination is ignored and all matching records are returned in Excel format
• Date filters apply to the IssuedDate field
• The startDate filter includes books from the beginning of that day (00:00:00)
• The endDate filter includes books up to the end of that day (23:59:59)
• Search text filters across account number, book reference, start serial number, and end serial number
• Results are cached for improved performance (configurable timeout)
• Client names are automatically resolved based on client classification (individual/group)
• Results include full deposit account, client, branch, and currency details

Response Fields

Field	Description
id	Unique identifier of the book register
bookType	Numeric book type (1=Cheque, 2=DepositSlip, 3=WithdrawalSlip)
bookTypeDescription	Human-readable book type
bookReference	Optional reference number for the book
depositAccountId	ID of the deposit account
accountNumber	Account number
clientId	ID of the account holder
clientName	Full name of the account holder
issuingBranchId	ID of the branch that issued the book
branchName	Name of the issuing branch
branchKey	Branch code/key
currencyCode	ISO currency code (e.g., NGN, USD)
currencyName	Full currency name
startSerialNumber	First serial number in the book
endSerialNumber	Last serial number in the book
numberOfLeaves	Total number of leaves/pages
issuedDate	Date the book was issued
status	Numeric status (1=ACTIVE, 2=INACTIVE, 3=BLOCKED)
statusDescription	Human-readable status
isActive	Boolean indicating if status is ACTIVE
remarks	Notes about the book register
createdAt	Timestamp when record was created
createdBy	User who created the record
updatedAt	Timestamp of last update
updatedBy	User who last updated the record

Related Commands

• Retrieve Book Register By ID - Get specific book register details
• Create Book Register - Issue new book register
• Block Book Register - Block a book register