TrisolarisPMS/AGENTS.md

# TrisolarisPMS API Usage

## 1) Booking

### Create booking

POST /properties/{propertyId}/bookings
Auth: ADMIN/MANAGER/STAFF

Body (JSON)
Required:

- expectedCheckInAt (String, ISO-8601, required)
- expectedCheckOutAt (String, ISO-8601, required)

Optional:

- source (String, default "WALKIN")
- transportMode (String enum)
- adultCount (Int)
- totalGuestCount (Int)
- notes (String)

{
  "source": "WALKIN",
  "expectedCheckInAt": "2026-01-28T12:00:00+05:30",
  "expectedCheckOutAt": "2026-01-29T10:00:00+05:30",
  "transportMode": "CAR",
  "adultCount": 2,
  "totalGuestCount": 3,
  "notes": "Late arrival"
}

Behavior
If expectedCheckInAt >= now(property timezone) -> booking becomes CHECKED_IN, and checkinAt is set, expected fields are null.

Response

{
  "id": "uuid",
  "status": "OPEN|CHECKED_IN",
  "checkInAt": "2026-01-28T12:00:00+05:30" | null,
  "expectedCheckInAt": "..." | null,
  "expectedCheckOutAt": "..." | null
}

---

### List bookings

GET /properties/{propertyId}/bookings
Optional query param:

- status (comma-separated), e.g. status=OPEN,CHECKED_IN

Behavior:
- If status is omitted, returns all bookings for the property (newest first).

Response: List of BookingListItem with id, status, guestId, source, times, counts, expectedGuestCount, notes.

---

### Check-in (creates RoomStay)

POST /properties/{propertyId}/bookings/{bookingId}/check-in
Auth: ADMIN/MANAGER/STAFF

Body
Required:

- roomIds (List<UUID>)

Optional:

- checkInAt (String)
- transportMode (String enum)
- nightlyRate (Long)
- rateSource (PRESET|NEGOTIATED|OTA)
- ratePlanCode (String)
- currency (String)
- notes (String)

{
  "roomIds": ["uuid1","uuid2"],
  "checkInAt": "2026-01-28T12:00:00+05:30",
  "nightlyRate": 2500,
  "rateSource": "NEGOTIATED",
  "ratePlanCode": "WEEKEND",
  "currency": "INR",
  "notes": "Late arrival"
}

---

### Pre-assign room stay

POST /properties/{propertyId}/bookings/{bookingId}/room-stays
Auth: ADMIN/MANAGER/STAFF

Body
Required:

- roomId (UUID)
- fromAt (String)
- toAt (String)

Optional:

- nightlyRate (Long)
- rateSource (PRESET|NEGOTIATED|OTA)
- ratePlanCode (String)
- currency (String)
- notes (String)

{
  "roomId": "uuid",
  "fromAt": "2026-01-29T12:00:00+05:30",
  "toAt": "2026-01-30T10:00:00+05:30",
  "nightlyRate": 2800,
  "rateSource": "PRESET",
  "ratePlanCode": "WEEKEND",
  "currency": "INR"
}

---

## 2) Guests

### Create guest + link to booking

POST /properties/{propertyId}/guests
Auth: property member
Body (required):

- bookingId (UUID)

Optional:

- phoneE164 (String)
- name (String)
- nationality (String)
- addressText (String)

{
  "bookingId": "uuid",
  "phoneE164": "+911111111111",
  "name": "John",
  "nationality": "IN",
  "addressText": "Varanasi"
}

Behavior:

- If phone already exists -> links existing guest to booking and returns it.
- If booking already has a guest -> 409.

Response (GuestResponse)

{
  "id": "uuid",
  "name": "John",
  "phoneE164": "+911111111111",
  "nationality": "IN",
  "addressText": "Varanasi",
  "signatureUrl": "/properties/{propertyId}/guests/{guestId}/signature/file",
  "vehicleNumbers": [],
  "averageScore": null
}

---

### Add guest vehicle + link to booking

POST /properties/{propertyId}/guests/{guestId}/vehicles
Auth: property member
Body:

{ "vehicleNumber": "UP32AB1234", "bookingId": "uuid" }

---

### Upload signature (SVG only)

POST /properties/{propertyId}/guests/{guestId}/signature
Auth: ADMIN/MANAGER
Multipart:

- file (SVG)

---

### Download signature

GET /properties/{propertyId}/guests/{guestId}/signature/file
Auth: property member
Returns image/svg+xml.

---

### Search guest by phone

GET /properties/{propertyId}/guests/search?phone=+911111111111

---

## 3) Room Types (default rate + rate resolve)

### Room type create/update

Fields now include defaultRate:

RoomTypeUpsertRequest

{
  "code": "DELUX",
  "name": "Deluxe",
  "baseOccupancy": 2,
  "maxOccupancy": 3,
  "sqFeet": 150,
  "bathroomSqFeet": 30,
  "defaultRate": 2500,
  "active": true,
  "otaAliases": [],
  "amenityIds": []
}

### Resolve preset rate for date

GET /properties/{propertyId}/room-types/{roomTypeCode}/rate?date=YYYY-MM-DD&ratePlanCode=optional
Auth: public if no auth, or member

Response

{
  "roomTypeCode": "DELUX",
  "rateDate": "2026-02-01",
  "rate": 2800,
  "currency": "INR",
  "ratePlanCode": "WEEKEND"
}

---

## 4) Rate Plans + Calendar

### Create rate plan

POST /properties/{propertyId}/rate-plans
Auth: ADMIN/MANAGER

Body
Required:

- code (String)
- name (String)
- roomTypeCode (String)
- baseRate (Long)

Optional:

- currency (String, default property currency)

{ "code":"WEEKEND", "name":"Weekend", "roomTypeCode":"DELUX", "baseRate":2800, "currency":"INR" }

Response RatePlanResponse

### List plans

GET /properties/{propertyId}/rate-plans?roomTypeCode=optional
Auth: member

### Update

PUT /properties/{propertyId}/rate-plans/{ratePlanId}
Body:

{ "name":"Weekend", "baseRate":3000, "currency":"INR" }

### Delete

DELETE /properties/{propertyId}/rate-plans/{ratePlanId}

### Calendar upsert (batch)

POST /properties/{propertyId}/rate-plans/{ratePlanId}/calendar
Body: Array

[
  { "rateDate":"2026-02-01", "rate":3200 },
  { "rateDate":"2026-02-02", "rate":3500 }
]

### Calendar list

GET /properties/{propertyId}/rate-plans/{ratePlanId}/calendar?from=YYYY-MM-DD&to=YYYY-MM-DD

### Calendar delete

DELETE /properties/{propertyId}/rate-plans/{ratePlanId}/calendar/{rateDate}

---

## 5) RoomStay rate change (mid-stay renegotiation)

POST /properties/{propertyId}/room-stays/{roomStayId}/change-rate
Auth: ADMIN/MANAGER

Body
Required:

- effectiveAt (String, ISO-8601)
- nightlyRate (Long)
- rateSource (PRESET|NEGOTIATED|OTA)

Optional:

- ratePlanCode (String)
- currency (String)

{
  "effectiveAt": "2026-01-30T12:00:00+05:30",
  "nightlyRate": 2000,
  "rateSource": "NEGOTIATED",
  "currency": "INR"
}

Response

{ "oldRoomStayId":"uuid", "newRoomStayId":"uuid", "effectiveAt":"..." }

---

## 6) Payments + Balance

### Add payment

POST /properties/{propertyId}/bookings/{bookingId}/payments
Auth: ADMIN/MANAGER/STAFF

Body
Required:

- amount (Long)
- method (CASH|CARD|UPI|BANK|ONLINE)

Optional:

- currency (String, default property currency)
- reference (String)
- notes (String)
- receivedAt (String)

{
  "amount": 1200,
  "method": "CASH",
  "currency": "INR",
  "reference": "RCP-123",
  "notes": "Advance"
}

Response

{
  "id":"uuid",
  "bookingId":"uuid",
  "amount":1200,
  "currency":"INR",
  "method":"CASH",
  "reference":"RCP-123",
  "notes":"Advance",
  "receivedAt":"2026-01-28T12:00:00+05:30",
  "receivedByUserId":"uuid"
}

### List payments

GET /properties/{propertyId}/bookings/{bookingId}/payments

### Booking balance

GET /properties/{propertyId}/bookings/{bookingId}/balance

{ "expectedPay": 2745, "amountCollected": 1200, "pending": 1545 }

---

## 7) Compose Notes

- Use `androidx.compose.foundation.text.KeyboardOptions` for keyboard options imports.