Skip to main content

BPMCore API Overview

The BPMCore API provides a unified command-based interface for executing banking operations within the BankLingo platform. Built on the MediatR pattern, BPMCore offers a consistent, extensible architecture for managing core banking entities and transactions.

Architecture​

Command-Based Pattern​

BPMCore uses a CQRS (Command Query Responsibility Segregation) pattern where:

  • Commands - Modify state (Create, Update, Delete operations)
  • Queries - Retrieve data without side effects (Read operations)

All operations are executed through a single endpoint: POST /api/core/cmd

Request Structure​

{
  "Cmd": "CommandName",
  "Data": {
    "property1": "value1",
    "property2": "value2"
  }
}

Fields:

  • Cmd (string, required) - The command or query name to execute
  • Data (object, required) - Dynamic object containing command-specific parameters

Response Structure​

{
  "IsSuccessful": true,
  "StatusCode": "00",
  "Message": "Operation completed successfully",
  "Data": {
    // Response data specific to the command
  }
}

Fields:

  • IsSuccessful (boolean) - Indicates if the operation succeeded
  • StatusCode (string) - Status code (e.g., "00" for success)
  • Message (string) - Human-readable message
  • Data (object) - Command-specific response data

Authentication​

All BPMCore APIs require authentication via JWT Bearer token:

Authorization: Bearer <your-jwt-token>

Available Modules​

1. Accounts (Journal Entries)​

Manage general ledger journal entries and accounting transactions.

Key Operations:

  • Retrieve journal entries and transactions
  • Post manual journal entries
  • Reverse journal transactions

2. Documents​

Upload, retrieve, and manage documents attached to various banking entities.

Key Operations:

  • Upload documents with entity associations
  • Retrieve documents by entity type (clients, loans, deposits, policies)
  • List and filter documents with pagination

3. Terminal Management​

Manage self-service banking terminals lifecycle and configurations.

Key Operations:

  • Create and configure terminals
  • Enable/disable terminal services
  • Terminate terminal connections
  • Query terminal status and details

4. Currency​

Lookup and manage currency configurations.

Key Operations:

  • Lookup currencies with autocomplete
  • Retrieve full currency lists

5. Activities​

Track and query user activities, system events, and audit trails.

Key Operations:

  • Get activities with entity filtering (Client, Loan, Deposit, User) ⭐ NEW
  • Get logged-in user activities for personal dashboard ⭐ NEW
  • Retrieve activities by entity (client activities, loan activities, etc.)
  • Filter activities by date range and search text
  • Comprehensive audit trail and compliance reporting

6. Comments​

Add and retrieve comments/notes for banking entities.

Key Operations:

  • Add comment to any entity (Client, Loan, Deposit, Policy) ⭐ NEW
  • Retrieve comments list with filtering and pagination
  • Get comments by entity type (client comments, loan comments, etc.)
  • Search and filter comments by date range
  • Comprehensive audit trail for entity interactions

Common Patterns​

Pagination​

Most list queries support pagination with these parameters:

{
  "pageNumber": 1,
  "pageSize": 50
}

Filtering by Date Range​

Queries that return time-series data typically support:

{
  "startDate": "2024-01-01",
  "endDate": "2024-12-31"
}

Search Text​

Many queries support free-text search:

{
  "searchText": "search term"
}

Excel Export​

List queries often support exporting results:

{
  "isExport": true
}

Error Handling​

Common Status Codes​

CodeMeaning
00Success
01Validation error
02Not found
03Duplicate record
99System error

Error Response Example​

{
  "IsSuccessful": false,
  "StatusCode": "01",
  "Message": "Validation failed: Amount is required",
  "Data": null
}

Best Practices​

1. Property Extraction​

BPMCore uses dynamic property extraction. Properties in the Data object are case-insensitive and can be extracted with defaults:

{
  "Cmd": "RetrieveJournalEntriesQuery",
  "Data": {
    "pageNumber": 1,
    "pageSize": 50,
    "currencyCode": "NGN"
  }
}

2. Mandatory vs Optional Parameters​

  • Parameters marked as required will fail validation if missing
  • Optional parameters have sensible defaults (e.g., pageSize defaults to max if not provided)

3. Command Naming Convention​

  • Queries: End with Query (e.g., RetrieveJournalEntriesQuery)
  • Commands: End with Command (e.g., PostJournalEntryCommand)

4. Testing​

Use the built-in documentation endpoint:

GET /api/core/cmd/documentation

This returns auto-generated documentation for all available commands.

Next Steps​

Explore the detailed documentation for each module:

Documentation Author: Owa Oluwasegun Tunbosun, Senior Platform Engineer