Skip to main content

Create Book Register

Overview​

The CreateBookRegisterCommand issues a new book register (cheque book, deposit slip book, or withdrawal slip book) to a deposit account.

API Endpoint​

POST /api/bpm/cmd

Headers​

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

Request Structure​

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

Request Fields​

FieldTypeRequiredDescription
depositAccountIdlongYesThe ID of the deposit account receiving the book
bookTypeintegerYesType of book (1=Cheque, 2=DepositSlip, 3=WithdrawalSlip)
bookReferencestringNoOptional reference number for the book
startSerialNumberstringYesFirst serial number in the book
endSerialNumberstringYesLast serial number in the book
numberOfLeavesintegerYesTotal number of leaves/pages in the book
issuedDatestringYesDate the book is issued (YYYY-MM-DD)
remarksstringNoOptional notes about the issuance

Book Type Values​

  • 1 - Cheque - For making payments (e.g., 25 or 50 leaf cheque books)
  • 2 - DepositSlip - For cash/cheque deposits into accounts
  • 3 - WithdrawalSlip - For cash withdrawals from accounts

Validation Rules​

  • Deposit Account: Must exist and be active
  • Serial Numbers:
    • Cannot overlap with existing book serial numbers for the same account
    • Start serial must be less than end serial
    • Format should be consistent (e.g., zero-padded)
  • Number of Leaves: Must match the range between start and end serial numbers
  • Book Type: Must be 1, 2, or 3
  • Issued Date: Cannot be a future date

Sample Requests​

1. Issue Standard 50-Leaf Cheque Book​

{
  "cmd": "CreateBookRegisterCommand",
  "data": {
    "depositAccountId": 12345,
    "bookType": 1,
    "bookReference": "CHQ-2024-001",
    "startSerialNumber": "0001001",
    "endSerialNumber": "0001050",
    "numberOfLeaves": 50,
    "issuedDate": "2024-12-01",
    "remarks": "Initial cheque book for corporate account"
  }
}

2. Issue Deposit Slip Book​

{
  "cmd": "CreateBookRegisterCommand",
  "data": {
    "depositAccountId": 67890,
    "bookType": 2,
    "startSerialNumber": "DS-001001",
    "endSerialNumber": "DS-001100",
    "numberOfLeaves": 100,
    "issuedDate": "2024-12-01"
  }
}

3. Issue Withdrawal Slip Book​

{
  "cmd": "CreateBookRegisterCommand",
  "data": {
    "depositAccountId": 54321,
    "bookType": 3,
    "bookReference": "WS-2024-Q4",
    "startSerialNumber": "WS-500001",
    "endSerialNumber": "WS-500075",
    "numberOfLeaves": 75,
    "issuedDate": "2024-10-01",
    "remarks": "Quarterly withdrawal slip book"
  }
}

Response Structure​

Success Response​

{
  "isSuccessful": true,
  "message": "Book register created successfully.",
  "statusCode": "00",
  "data": {
    "id": 789,
    "bookType": 1,
    "bookTypeDescription": "Cheque",
    "bookReference": "CHQ-2024-001",
    "depositAccountId": 12345,
    "accountNumber": "1234567890",
    "startSerialNumber": "0001001",
    "endSerialNumber": "0001050",
    "numberOfLeaves": 50,
    "issuedDate": "2024-12-01T00:00:00Z",
    "status": 1,
    "statusDescription": "ACTIVE",
    "remarks": "Initial cheque book issuance",
    "createdAt": "2024-12-01T10:30:00Z",
    "createdBy": "admin@bank.com"
  }
}

Error Responses​

Validation Error​

{
  "isSuccessful": false,
  "message": "Serial number range overlaps with existing book register.",
  "statusCode": "99",
  "data": null
}

Account Not Found​

{
  "isSuccessful": false,
  "message": "Deposit account not found.",
  "statusCode": "99",
  "data": null
}

Business Rules​

  1. Serial Number Management

    • Serial numbers must be unique across all books for the account
    • The system validates that no existing book has overlapping serial numbers
    • Common formats: "0001001", "CHQ-001001", "DS-001001"

  2. Default Status

    • New books are created with status ACTIVE (1)
    • The issuing branch is set to the user's current branch

  3. Audit Trail

    • Creation is automatically logged with timestamp and user
    • The remarks field provides additional context for the audit trail

  4. Multi-Book Support

    • Accounts can have multiple active books of the same type
    • Common for corporate accounts with high transaction volumes

Best Practices​

  1. Serial Number Format

    • Use zero-padded numbers for consistent sorting (e.g., "0001001" instead of "1001")
    • Include book type prefix for easy identification (e.g., "CHQ-", "DS-", "WS-")
    • Maintain sequential numbering across books

  2. Number of Leaves

    • Standard cheque books: 25 or 50 leaves
    • Deposit/Withdrawal slips: 50, 75, or 100 leaves
    • Ensure numberOfLeaves matches serial number range

  3. Reference Numbers

    • Use meaningful references: "CHQ-2024-Q1", "CORP-CHQ-001"
    • Include year and quarter for easier tracking
    • Maintain consistent naming convention

  4. Remarks

    • Document reason for issuance
    • Note if replacing lost/stolen books
    • Reference related requests or approvals

Notes​

  • The issuing branch is automatically set from the user's context
  • Currency is inherited from the deposit account
  • Book registers cannot be deleted, only deactivated or blocked
  • Serial numbers should be validated before issuance to prevent duplicates
  • Cache is automatically invalidated after successful creation