Book Registers - Developer Documentation

Introduction

Book Registers manage physical banking instruments issued to deposit account holders, including:

• Cheque Books - for making payments
• Deposit Slips - for cash/cheque deposits
• Withdrawal Slips - for cash withdrawals

Each book register tracks serial number ranges, issuance dates, status, and usage for audit and security purposes.

Migration from V1 Cheque Registrations

If you're migrating from V1 Cheque Registration commands (Commands/Deposits/ChequeRegistration/*), Book Registers provide all the same functionality plus significant enhancements:

What's New:

• ✅ Multi-type support: Manage cheque books, deposit slips, AND withdrawal slips in one unified system
• ✅ Enhanced security: New BlockBookRegisterCommand for fraud prevention (BLOCKED state)
• ✅ Modern architecture: BPMCore V2 implementation with Redis caching and better performance
• ✅ Richer data model: Book references, number of leaves, issued dates, remarks

Command Migration:

V1 Command	V2 Replacement	Notes
CreateChequeRegistrationCommand	CreateBookRegisterCommand	Use bookType=1 for cheque books
UpdateChequeRegistrationCommand	UpdateBookRegisterCommand	Enhanced with more fields
ActivateChequeRegistrationCommand	ActivateBookRegisterCommand	Same functionality
DeactivateChequeRegistrationCommand	DeactivateBookRegisterCommand	Same functionality
GetChequeRegistrationListQuery	RetrieveBookRegistersListQuery	Filter by bookType=1 for cheques
(N/A - NEW)	BlockBookRegisterCommand	New - Block for fraud/security

Key Difference: Use the bookType enum field to specify what kind of book register you're creating:

• bookType=1 for Cheque Books (replaces old Cheque Registrations)
• bookType=2 for Deposit Slips
• bookType=3 for Withdrawal Slips

Available Operations

Query Operations

Command	Purpose	Endpoint
RetrieveBookRegistersListQuery	Get paginated list of book registers with filters	POST /api/bpm/cmd
RetrieveBookRegisterByIdQuery	Get specific book register details	POST /api/bpm/cmd

Management Operations

Command	Purpose	Endpoint
CreateBookRegisterCommand	Issue new book register to account	POST /api/bpm/cmd
UpdateBookRegisterCommand	Update book register details	POST /api/bpm/cmd
ActivateBookRegisterCommand	Activate a book register	POST /api/bpm/cmd
DeactivateBookRegisterCommand	Deactivate a book register	POST /api/bpm/cmd
BlockBookRegisterCommand	Block a book register (fraud/security)	POST /api/bpm/cmd

Book Types

Book registers can be one of three types:

Value	Type	Description
1	Cheque	Cheque book for making payments
2	DepositSlip	Deposit slip book for cash/cheque deposits
3	WithdrawalSlip	Withdrawal slip book for cash withdrawals

Status Management

Book registers have three possible statuses:

Value	Status	Description
1	ACTIVE	Book is active and can be used
2	INACTIVE	Book is deactivated (cannot be used)
3	BLOCKED	Book is blocked due to security/fraud concerns

Status Transitions

       CREATE
         ↓
      ACTIVE ←→ INACTIVE
         ↓
      BLOCKED (irreversible)

• Books are created in ACTIVE status by default
• ACTIVE ↔ INACTIVE: Reversible via Activate/Deactivate commands
• BLOCKED: Permanent status for security reasons (cannot be reversed)

Key Features

Serial Number Management

• Each book register has a start and end serial number range
• System validates that serial numbers don't overlap
• Number of leaves is automatically calculated from the range

Multi-Account Support

• Books are linked to specific deposit accounts
• One account can have multiple book registers
• Each book type can have multiple active books per account

Branch Integration

• Books are issued by specific branches
• Branch information is tracked for audit purposes
• Multi-branch banks can manage book inventory separately

Security & Audit

• All book operations are logged with timestamp and user
• Blocking is permanent to prevent fraudulent use
• Remarks field captures reason for state changes

Search & Filtering

Books can be filtered by:

• Deposit account
• Book type (Cheque/Deposit/Withdrawal)
• Status (Active/Inactive/Blocked)
• Date range
• Serial numbers
• Account number

Export Capabilities

• List queries support Excel export
• Useful for inventory management
• Audit trail reporting

Common Use Cases

1. Issue Cheque Book

{
  "cmd": "CreateBookRegisterCommand",
  "data": {
    "depositAccountId": 12345,
    "bookType": 1,
    "startSerialNumber": "0001001",
    "endSerialNumber": "0001050",
    "numberOfLeaves": 50,
    "issuedDate": "2024-12-01",
    "remarks": "Initial cheque book issuance"
  }
}

2. Block Lost Cheque Book

{
  "cmd": "BlockBookRegisterCommand",
  "data": {
    "id": 789,
    "remarks": "Customer reported book as lost/stolen"
  }
}

3. Find All Active Books for Account

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

Best Practices

Issuance

1. Verify Account Status: Ensure deposit account is active before issuing
2. Check Existing Books: Avoid issuing too many active books simultaneously
3. Serial Number Validation: Ensure no overlapping serial number ranges
4. Document Issuance: Always include meaningful remarks

Security

1. Prompt Blocking: Block books immediately when reported lost/stolen
2. Regular Audits: Review active books periodically
3. Deactivate Unused: Deactivate books that are no longer needed
4. Track Usage: Monitor serial number usage patterns

Data Management

1. Pagination: Use appropriate page sizes for large result sets
2. Filtering: Apply filters to narrow down search results
3. Export: Use export feature for inventory reports
4. Caching: Leverage system caching for frequently accessed data

Error Handling

Common error scenarios:

Error	Cause	Resolution
Book register not found	Invalid ID	Verify book register exists
Account not found	Invalid deposit account ID	Check account number
Overlapping serial numbers	Range conflicts with existing book	Use different serial number range
Invalid book type	Type not in enum (1-3)	Use valid book type value
Cannot activate blocked book	Book is permanently blocked	Issue new book instead
Missing required fields	Incomplete request	Provide all mandatory fields

Performance Considerations

• Caching: Book register lists are cached for improved performance
• Indexing: Queries on account ID, status, and book type are optimized
• Pagination: Use pagination for large datasets
• Export: Excel exports handle large volumes efficiently

Related Documentation

• Deposit Accounts - Parent account management
• Deposit Transactions - Using books for transactions
• Branch Management - Branch operations

API Response Format

All book register commands return responses in this format:

{
  "isSuccessful": true,
  "message": "Operation completed successfully",
  "statusCode": "00",
  "data": { /* response data */ }
}

Error responses:

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