Skip to Content
Ranlanka CRM documentation — pre-release, subject to change.
API Reference

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) or https://api.ranlankacrm.com/api/v1 (production).
  • Authentication: JWT delivered via Cookie: jwt=... (HTTP-only).
  • CSRF Protection: Mutating requests (POST, PUT, PATCH, DELETE) require X-XSRF-TOKEN matching the XSRF-TOKEN cookie.
  • 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_VIEW authority.
  • Response: ApiResponse<List<GuiderResponseDTO>>

GET /api/v1/fleet/guiders/{id}

  • Description: Get guider profile details by ID.
  • Authorization: Requires FLEET_VIEW authority.
  • Response: ApiResponse<GuiderResponseDTO>

POST /api/v1/fleet/guiders

  • Description: Create a new driver-guider.
  • Authorization: Requires FLEET_MANAGE authority.
  • 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_MANAGE authority.
  • 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_MANAGE authority.
  • Request Body: { "availabilityStatus": "OFF_DUTY" }
  • Response: ApiResponse<GuiderResponseDTO>

DELETE /api/v1/fleet/guiders/{id}

  • Description: Delete a guider record.
  • Authorization: Requires FLEET_MANAGE authority.
  • Response: ApiResponse<Void>

GET /api/v1/fleet/guiders/{id}/trip-history

  • Description: Retrieve past completed tour trips assigned to this guider.
  • Authorization: Requires FLEET_VIEW authority.
  • 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_VIEW authority.
  • 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_VIEW authority.
  • Response: ApiResponse<List<VehicleResponseDTO>>

POST /api/v1/fleet/vehicles

  • Description: Register a new vehicle and link it to a guider.
  • Authorization: Requires FLEET_MANAGE authority.
  • 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_MANAGE authority.
  • 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_MANAGE authority.
  • Request Body: { "availabilityStatus": "IN_MAINTENANCE" }
  • Response: ApiResponse<VehicleResponseDTO>

DELETE /api/v1/fleet/vehicles/{id}

  • Description: Remove a vehicle record.
  • Authorization: Requires FLEET_MANAGE authority.
  • 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_MANAGE authority (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, OTHER
    • description (Optional): Staff description or notes
    • annotatedFileName (Optional): Override filename
    • subCategory (Optional): ISSUED_VISA, SUPPORTING_DOC, ISSUED_TICKET, BOOKING_DOC
    • visaRequestId (Optional): Link to specific visa application
    • flightRequestId (Optional): Link to specific flight booking
    • linkedGroupId (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_VIEW authority.
  • 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: attachment header preserving the annotated filename.
  • Authorization: Requires CUSTOMER_VIEW authority.
  • 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_CREATE authority.
  • 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_MANAGE authority.
  • 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_VIEW authority.
  • 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_VIEW authority.
  • 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_MANAGE authority.
  • 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_MANAGE authority.
  • 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 as PAID.
  • Authorization: Requires INVOICE_MANAGE authority.
  • 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_OWNER or ROLE_MANAGER authority.
  • Request Body: { "reason": "Cancellation reason" }
  • Response: ApiResponse<InvoiceResponseDTO>

GET /api/v1/invoices/due

  • Description: Retrieve server-side paginated list of outstanding invoices (unpaid and partial status).
  • Authorization: Requires INVOICE_READ authority.
  • Query Parameters:
    • page (optional, default 0): Page index.
    • size (optional, default 15): Page size.
    • sort (optional, default createdAt,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_READ authority.
  • 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_OWNER or ROLE_MANAGER authority and INVOICE_EDIT permission.
  • 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 FETCH optimization on invoices to prevent N+1 queries.
  • Authorization: Requires ACCOUNTING_VIEW authority.
  • 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/Colombo to protect closed accounting periods. Supports setting past or future payment dates.
  • Authorization: Requires EXPENSE_MANAGE authority.
  • 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_MANAGE authority.
  • 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_VIEW authority.
  • 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_VIEW authority.
  • 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_VIEW authority.
  • 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_VIEW authority.
  • Query Parameters:
    • startDate (required): ISO date (YYYY-MM-DD).
    • endDate (required): ISO date (YYYY-MM-DD).
  • Response: ApiResponse<List<FlightProfitDetailDTO>>
Last updated on