CreateLoanQuoteDocumentCommand

Overview

The CreateLoanQuoteDocumentCommand allows you to upload and associate documents with loan applications (loan quotes). This is essential for capturing required documentation such as identification, financial statements, and supporting materials during the loan origination process.

Handler File: CB.Administration.Api/Commands/BPM/SelfService/DocumentManagementCommand.cs

Use Cases

• Upload customer identification documents (ID cards, passports, driver's license)
• Attach financial documents (bank statements, tax clearance)
• Store business documents (company registration, certificates)
• Upload supporting materials (utility bills, photographs)
• Maintain document trail for compliance and audit

Request Parameters

Required Parameters

Parameter	Type	Description
loanQuoteId	long	The ID of the loan quote/application to attach document to
documentName	string	Display name of the document (e.g., "National ID Card.pdf")
documentType	int	Document type enum value (see Document Types below)
documentData	string	Base64-encoded document content

Optional Parameters

Parameter	Type	Description
description	string	Additional description or notes about the document
documentNumber	string	Official document number (e.g., ID card number)
documentExpiry	DateTime	Document expiration date (for IDs, licenses)
documentIssueDate	DateTime	Date the document was issued
documentIssuer	string	Organization that issued the document

Document Types

Value	Type	Description
1	NATIONAL_ID	National ID card
2	INTERNATIONAL_PASSPORT	Passport
3	DRIVERS_LICENCE	Driver's license
4	UTILITY_BILL	Utility bill for address verification
5	BANK_STATEMENT	Bank statement
6	COMPANY_REGISTRATION	Company registration certificate
7	TAX_CLEARANCE	Tax clearance certificate
8	CERTIFICATE_OF_INCORPORATION	Certificate of incorporation
14	PHOTOGRAPH	Customer photograph
15	UNIVERSITY_CERTIFICATE	Educational certificate
16	BIRTH_CERTIFICATE	Birth certificate

Request Examples

Example 1: Identity Document (with all optional fields)

{
  "cmd": "CreateLoanQuoteDocumentCommand",
  "data": {
    "loanQuoteId": 110,
    "documentName": "National ID Card.pdf",
    "documentType": 1,
    "documentData": "JVBERi0xLjQKJeLjz9MK...",
    "description": "Customer national ID card - front and back",
    "documentNumber": "ABC123456",
    "documentExpiry": "2030-12-31T00:00:00Z",
    "documentIssueDate": "2020-01-15T00:00:00Z",
    "documentIssuer": "National Identity Management Commission"
  }
}

Example 2: Bank Statement (minimal fields only)

{
  "cmd": "CreateLoanQuoteDocumentCommand",
  "data": {
    "loanQuoteId": 110,
    "documentName": "Bank Statement - December 2025.pdf",
    "documentType": 5,
    "documentData": "JVBERi0xLjQKJeLjz9MK...",
    "description": "Last 3 months bank statement"
  }
}

Example 3: Utility Bill (no expiry/issue dates)

{
  "cmd": "CreateLoanQuoteDocumentCommand",
  "data": {
    "loanQuoteId": 110,
    "documentName": "Electricity Bill.pdf",
    "documentType": 4,
    "documentData": "JVBERi0xLjQKJeLjz9MK...",
    "description": "Proof of address"
  }
}

Response Format

Success Response

{
  "statusCode": "00",
  "statusMessage": "SUCCESS",
  "data": {
    "documentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "documentName": "National ID Card.pdf",
    "documentType": 1,
    "associationId": 45,
    "loanQuoteId": 110,
    "createdDate": "2026-01-12T10:30:00Z"
  }
}

Error Response

{
  "statusCode": "01",
  "statusMessage": "Loan quote with ID 999 not found",
  "data": null
}

JavaScript Usage Example

// Convert file to base64
const convertFileToBase64 = (file) => {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(reader.result.split(',')[1]);
    reader.onerror = reject;
    reader.readAsDataURL(file);
  });
};

// Upload document
const uploadDocument = async (loanQuoteId, file, documentType) => {
  try {
    const base64Data = await convertFileToBase64(file);
    
    const result = await api.query({
      cmd: "CreateLoanQuoteDocumentCommand",
      data: JSON.stringify({
        loanQuoteId: loanQuoteId,
        documentName: file.name,
        documentType: documentType,
        documentData: base64Data,
        description: `Uploaded on ${new Date().toLocaleDateString()}`
      })
    });
    
    if (result.statusCode === "00") {
      console.log("Document uploaded:", result.data.documentId);
      return result.data;
    } else {
      console.error("Upload failed:", result.statusMessage);
      return null;
    }
  } catch (error) {
    console.error("Error uploading document:", error);
    return null;
  }
};

// Example usage
const fileInput = document.getElementById('documentFile');
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  if (file) {
    await uploadDocument(110, file, 1); // Upload as NATIONAL_ID
  }
});

Validation Rules

• loanQuoteId: Must reference an existing loan quote
• documentName: Cannot be empty
• documentType: Must be valid enum value (1-23)
• documentData: Must be valid base64 string
• File Size: Consider implementing size limits (e.g., 10MB max)

Optional Fields Usage Guide

Different document types require different fields. Here's a guide:

Identity Documents (require number, expiry, issue date)

• NATIONAL_ID (1) - Provide: documentNumber, documentExpiry, documentIssueDate, documentIssuer
• INTERNATIONAL_PASSPORT (2) - Provide: documentNumber, documentExpiry, documentIssueDate, documentIssuer
• DRIVERS_LICENCE (3) - Provide: documentNumber, documentExpiry, documentIssueDate, documentIssuer
• BIRTH_CERTIFICATE (16) - Provide: documentNumber, documentIssueDate, documentIssuer

Financial Documents (usually no expiry)

• BANK_STATEMENT (5) - Optional: description only
• TAX_CLEARANCE (7) - Optional: documentNumber, documentIssueDate
• SALARY_SLIP (9) - Optional: description only

Supporting Documents (minimal metadata)

• UTILITY_BILL (4) - Optional: description only
• PHOTOGRAPH (14) - Optional: description only
• SIGNATURE (18) - Optional: description only

Business Documents (may have registration numbers)

• COMPANY_REGISTRATION (6) - Provide: documentNumber, documentIssueDate, documentIssuer
• CERTIFICATE_OF_INCORPORATION (8) - Provide: documentNumber, documentIssueDate

Tip: Only provide the optional fields that make sense for your document type. The API accepts null values for all optional fields.

Error Codes

Status Code	Description
00	Success - document created
01	Loan quote not found
01	Validation error (missing required fields)
99	General error (see statusMessage for details)

Business Rules

1. Document Association: Documents are linked to loan quotes via the SelfServiceDocumentAssociation table
2. Unique Identifier: Each document receives a unique GUID (documentId) for retrieval
3. Audit Trail: System automatically records creation timestamp and user
4. Storage: Documents stored as base64 in database (consider MinIO for large volumes)

Related Commands

• GetLoanQuoteDocumentsQuery - List all documents for a loan
• GetLoanQuoteDocumentByIdQuery - Download specific document
• CreateUserDocumentCommand - Upload documents for users

Database Tables

• SelfServiceDocument ([BPMSelfServiceDocument].[dbo].[SelfServiceDocument])
• SelfServiceDocumentAssociation ([BPMSelfServiceDocument].[dbo].[SelfServiceDocumentAssociation])

Performance Considerations

• Base64 encoding increases file size by ~33%
• Large files (greater than 5MB) may impact API response time
• Consider client-side compression before upload
• For production, consider migrating to MinIO object storage

Security Notes

• Validate file types on client and server
• Implement virus scanning for uploaded files
• Restrict access based on user permissions
• Audit all document uploads
• Consider encryption for sensitive documents

Testing Checklist

• Upload PDF document
• Upload image document (JPEG, PNG)
• Test with invalid loanQuoteId
• Test with missing documentData
• Test with invalid documentType
• Verify GUID generation
• Verify association record creation
• Test with large file (greater than 5MB)