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>
Last updated on
SecurityOverview