API Reference
Complete reference for the Ranlanka CRM REST API (/api/v1).
Request Headers & Conventions
All endpoints adhere to uniform RESTful conventions:
- Base URL:
http://localhost:8080/api/v1(local) orhttps://api.ranlankacrm.com/api/v1(production). - Authentication: JWT delivered via
Cookie: jwt=...(HTTP-only). - CSRF Protection: Mutating requests (
POST,PUT,PATCH,DELETE) requireX-XSRF-TOKENmatching theXSRF-TOKENcookie. - Uniform Response Structure:
{ "success": true, "message": "Operation description", "data": { ... }, "error": null, "timestamp": "2026-08-08T12:00:00Z" }
Fleet & Vehicle Management Endpoints
The Fleet module manages driver-guiders, vehicle inventories, availability statuses, and trip histories.
Guider Endpoints
GET /api/v1/fleet/guiders
- Description: Fetch all guiders.
- Authorization: Requires
FLEET_VIEWauthority. - Response:
ApiResponse<List<GuiderResponseDTO>>
GET /api/v1/fleet/guiders/{id}
- Description: Get guider profile details by ID.
- Authorization: Requires
FLEET_VIEWauthority. - Response:
ApiResponse<GuiderResponseDTO>
POST /api/v1/fleet/guiders
- Description: Create a new driver-guider.
- Authorization: Requires
FLEET_MANAGEauthority. - Request Body:
GuiderDTO(name, contact, licenseNumber, primaryBranch, languages, tags) - Response:
ApiResponse<GuiderResponseDTO>(HTTP 201)
PUT /api/v1/fleet/guiders/{id}
- Description: Update an existing guider.
- Authorization: Requires
FLEET_MANAGEauthority. - Response:
ApiResponse<GuiderResponseDTO>
PATCH /api/v1/fleet/guiders/{id}/availability
- Description: Update a guider’s availability status (
ACTIVE,OFF_DUTY,ON_TOUR). - Authorization: Requires
FLEET_MANAGEauthority. - Request Body:
{ "availabilityStatus": "OFF_DUTY" } - Response:
ApiResponse<GuiderResponseDTO>
DELETE /api/v1/fleet/guiders/{id}
- Description: Delete a guider record.
- Authorization: Requires
FLEET_MANAGEauthority. - Response:
ApiResponse<Void>
GET /api/v1/fleet/guiders/{id}/trip-history
- Description: Retrieve past completed tour trips assigned to this guider.
- Authorization: Requires
FLEET_VIEWauthority. - Response:
ApiResponse<List<GuiderTripDTO>>
Vehicle Endpoints
GET /api/v1/fleet/vehicles (New Endpoint)
- Description: Retrieve all vehicles across all guiders in the system.
- Authorization: Requires
FLEET_VIEWauthority. - Response:
ApiResponse<List<VehicleResponseDTO>> - Example Response:
{ "success": true, "message": "Vehicles fetched successfully", "data": [ { "id": "b3e94a8f-1234-4567-89ab-cdef01234567", "registrationNumber": "WP CAB-1234", "vehicleType": "VAN", "passengerCapacity": 7, "luggageCapacity": 5, "amenities": ["Wi-Fi", "Child Seat", "Cooler Box"], "availabilityStatus": "ACTIVE", "branch": "Colombo", "guiderId": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "guiderName": "Kamal Perera" } ], "error": null, "timestamp": "2026-08-08T12:00:00Z" }
GET /api/v1/fleet/guiders/{guiderId}/vehicles
- Description: List all vehicles assigned to a specific guider.
- Authorization: Requires
FLEET_VIEWauthority. - Response:
ApiResponse<List<VehicleResponseDTO>>
POST /api/v1/fleet/vehicles
- Description: Register a new vehicle and link it to a guider.
- Authorization: Requires
FLEET_MANAGEauthority. - Request Body:
VehicleDTO(registrationNumber, vehicleType, passengerCapacity, luggageCapacity, amenities, guiderId, branch) - Response:
ApiResponse<VehicleResponseDTO>(HTTP 201)
PUT /api/v1/fleet/vehicles/{id}
- Description: Update vehicle details or transfer vehicle to a new guider.
- Authorization: Requires
FLEET_MANAGEauthority. - Request Body:
VehicleDTO - Response:
ApiResponse<VehicleResponseDTO>
PATCH /api/v1/fleet/vehicles/{id}/availability
- Description: Update a vehicle’s operational availability status (
ACTIVE,OFF_DUTY,IN_MAINTENANCE). - Authorization: Requires
FLEET_MANAGEauthority. - Request Body:
{ "availabilityStatus": "IN_MAINTENANCE" } - Response:
ApiResponse<VehicleResponseDTO>
DELETE /api/v1/fleet/vehicles/{id}
- Description: Remove a vehicle record.
- Authorization: Requires
FLEET_MANAGEauthority. - Response:
ApiResponse<Void>
Document Storage & File Vault Endpoints
Manages Cloudflare R2 file uploads, deterministic file annotations, and presigned download links.
POST /api/v1/customers/{id}/documents
- Description: Upload a document for a customer with automatic structured annotation or custom overrides.
- Authorization: Requires
CUSTOMER_MANAGEauthority (or assigned staff ownership). - Content-Type:
multipart/form-data - Form Parameters:
file: Binary file (PDF, PNG, JPG, DOC)documentType:PASSPORT,VISA_COPY,TICKET,BANK_STATEMENT,EMPLOYMENT_LETTER,OTHERdescription(Optional): Staff description or notesannotatedFileName(Optional): Override filenamesubCategory(Optional):ISSUED_VISA,SUPPORTING_DOC,ISSUED_TICKET,BOOKING_DOCvisaRequestId(Optional): Link to specific visa applicationflightRequestId(Optional): Link to specific flight bookinglinkedGroupId(Optional): Link to linked family/booking group
- Response:
ApiResponse<DocumentResponseDTO>(HTTP 201)
GET /api/v1/customers/{id}/documents
- Description: Retrieve all active documents belonging to a customer with active presigned download URLs.
- Authorization: Requires
CUSTOMER_VIEWauthority. - Response:
ApiResponse<List<DocumentResponseDTO>>
GET /api/v1/customers/{id}/documents/{documentId}/download
- Description: Generate an on-demand presigned S3/R2 download URL with forced
Content-Disposition: attachmentheader preserving the annotated filename. - Authorization: Requires
CUSTOMER_VIEWauthority. - Response:
ApiResponse<String>(download URL)
GET /api/v1/customers/check-duplicate
- Description: Check if an existing customer profile exists matching on NIC, Primary Phone, or Passport Number (including primary and dual passport numbers).
- Authorization: Requires
CUSTOMER_CREATEauthority. - Query Parameters:
nicPassport(optional): National Identity Card number or NIC/Passport string.phonePrimary(optional): Full primary phone number with country code.passportNumber(optional): Customer passport number.
- Response:
ApiResponse<CustomerDuplicateCheckDTO>{ "success": true, "message": "Duplicate check complete", "data": { "duplicate": true, "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "fullName": "Jane Doe", "matchedOn": "passportNumber" } }
DELETE /api/v1/customers/{id}/documents/{documentId}
- Description: Soft-delete an archived document.
- Authorization: Requires
CUSTOMER_MANAGEauthority. - Response:
ApiResponse<Void>
GET /api/v1/visas/{visaRequestId}/documents
- Description: Retrieve all visa copies and supporting documents attached to a specific visa application.
- Authorization: Requires
VISA_VIEWauthority. - Response:
ApiResponse<List<DocumentResponseDTO>>
GET /api/v1/flights/{flightRequestId}/documents
- Description: Retrieve all e-tickets and booking documents attached to a specific flight booking.
- Authorization: Requires
FLIGHT_VIEWauthority. - Response:
ApiResponse<List<DocumentResponseDTO>>
Visa Operations & Rejection Endpoints
POST /api/v1/visas/{id}/notify-rejection
- Description: Send a formal embassy decision notification email to the customer with decision remarks, assigned consultant contact details, and passport collection instructions.
- Authorization: Requires
VISA_MANAGEauthority. - Request Body:
{ "notes": "Embassy rejection remarks..." } - Response:
ApiResponse<Void>
POST /api/v1/visas/{id}/finalize
- Description: Mark passport as collected/returned and complete the operational lifecycle. For rejected applications, preserves rejection status and skips approval emails.
- Authorization: Requires
VISA_MANAGEauthority. - Response:
ApiResponse<VisaResponseDTO>
Finance & Invoicing Endpoints
POST /api/v1/invoices/{id}/settle-rejection
- Description: Settle an invoice for a rejected visa by waiving the uncollectible balance via a
"Visa Rejection Balance Waiver"discount line, setting the total to the amount paid and marking status asPAID. - Authorization: Requires
INVOICE_MANAGEauthority. - Response:
ApiResponse<InvoiceResponseDTO>
POST /api/v1/invoices/{id}/cancel
- Description: Hard-delete an invoice, all line items, tax lines, discount lines, request links, and recorded receipts from the database.
- Authorization: Requires
ROLE_OWNERorROLE_MANAGERauthority. - Request Body:
{ "reason": "Cancellation reason" } - Response:
ApiResponse<InvoiceResponseDTO>
GET /api/v1/invoices/due
- Description: Retrieve server-side paginated list of outstanding invoices (
unpaidandpartialstatus). - Authorization: Requires
INVOICE_READauthority. - Query Parameters:
page(optional, default 0): Page index.size(optional, default 15): Page size.sort(optional, defaultcreatedAt,desc): Sort field and direction.
- Response:
ApiResponse<PageResponse<InvoiceResponseDTO>>
GET /api/v1/invoices/outstanding-total
- Description: Retrieve the exact aggregate outstanding balance across all non-cancelled company invoices.
- Authorization: Requires
INVOICE_READauthority. - Response:
ApiResponse<BigDecimal>
PUT /api/v1/invoices/{id}
- Description: Update an existing invoice (line items, custom fees, taxes, discounts, notes, direct cost amount). Validates that the new total amount does not fall below the sum of already-collected receipts (
amountPaid), dynamically recalculates payment status, evicts cached invoice PDFs, and verifies task finalization. - Authorization: Requires
ROLE_OWNERorROLE_MANAGERauthority andINVOICE_EDITpermission. - Request Body:
CreateInvoiceRequestDTO - Response:
ApiResponse<InvoiceResponseDTO>
Accounting Endpoints
GET /api/v1/accounting/payments-collected/paged
- Description: Retrieve server-side paginated list of collected receipts for a given year and optional month, with
LEFT JOIN FETCHoptimization on invoices to prevent N+1 queries. - Authorization: Requires
ACCOUNTING_VIEWauthority. - Query Parameters:
year(required): 4-digit calendar year (e.g.2026).month(optional): 1-based month index (1–12). Omit for full-year feed.page(optional, default 0): Page index.size(optional, default 20): Page size.
- Response:
ApiResponse<PageResponse<CollectedPaymentDTO>>
PUT /api/v1/accounting/expenses/{expenseId}/payments/{paymentId}
- Description: Update an individual expense payment amount, paid date, reference note, or payment method. Validates that the payment belongs to the current calendar month in
Asia/Colomboto protect closed accounting periods. Supports setting past or future payment dates. - Authorization: Requires
EXPENSE_MANAGEauthority. - Request Body:
RecordPaymentDTO - Response:
ApiResponse<ExpenseEntity>
DELETE /api/v1/accounting/expenses/{expenseId}/payments/{paymentId}
- Description: Delete an expense payment record and deduct its value from the parent expense’s paid total. Restricted to payments recorded in the current calendar month.
- Authorization: Requires
EXPENSE_MANAGEauthority. - Response:
ApiResponse<ExpenseEntity>
Financial Reporting & Dashboard Endpoints
GET /api/v1/dashboard/financial-report/monthly
- Description: Retrieve comprehensive P&L financial metrics, revenue breakdown (Visa Fees, Consulting Fees, Ticket Sales, Flight Costs, Flight Profit, Tour Revenue, Other Fees), and expense totals for a specific month.
- Authorization: Requires
ACCOUNTING_VIEWauthority. - Query Parameters:
year(required): 4-digit calendar year (e.g.2026).month(required): 1-based month index (1–12).
- Response:
ApiResponse<MonthlyFinancialReportDTO>
GET /api/v1/dashboard/financial-report/yearly
- Description: Retrieve aggregate annual financial metrics and month-by-month financial summary.
- Authorization: Requires
ACCOUNTING_VIEWauthority. - Query Parameters:
year(required): 4-digit calendar year (e.g.2026).
- Response:
ApiResponse<YearlyFinancialReportDTO>
GET /api/v1/dashboard/financial-report/other-fees
- Description: Retrieve itemized list of all miscellaneous fee line items across invoices within an arbitrary date range. Strictly filters out flight tickets and tour charges.
- Authorization: Requires
ACCOUNTING_VIEWauthority. - Query Parameters:
startDate(required): ISO date (YYYY-MM-DD).endDate(required): ISO date (YYYY-MM-DD).
- Response:
ApiResponse<List<OtherFeeDetailDTO>>
GET /api/v1/dashboard/financial-report/flight-profit
- Description: Retrieve customer-by-customer flight ticket breakdown for an arbitrary date range, including passenger names, routes, airlines, PNR codes, ticket sale amounts, cost of sales, and net flight profit.
- Authorization: Requires
ACCOUNTING_VIEWauthority. - Query Parameters:
startDate(required): ISO date (YYYY-MM-DD).endDate(required): ISO date (YYYY-MM-DD).
- Response:
ApiResponse<List<FlightProfitDetailDTO>>
Last updated on