> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thecleanlife.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Flows

> Sequence diagrams for PARTNER, CLEANOS, and cancellation flows.

This section provides end-to-end sequence diagrams for the most common integration patterns.

***

## Flow 1: PARTNER Responsibility — Full Booking Lifecycle

This is the recommended flow for partners who manage their own payment collection.

```mermaid theme={null}
sequenceDiagram
    participant CustomerApp as Your Customer App
    participant PartnerServer as Your Server
    participant CleanLife as CleanLife Partner API

    CustomerApp->>PartnerServer: Customer selects service + date

    PartnerServer->>CleanLife: POST /partners/contacts\n{ phone, name, latitude, longitude, cityName, districtName, streetName }
    CleanLife-->>PartnerServer: { id, addressId, isNewContact }

    PartnerServer->>CleanLife: GET /partners/services?addressId=...
    CleanLife-->>PartnerServer: Categories with nested services

    PartnerServer->>CleanLife: GET /partners/timeslots/available?addressId=...&serviceId=...&date=...
    CleanLife-->>PartnerServer: Available timeslots

    CustomerApp->>PartnerServer: Customer confirms booking + payment

    PartnerServer->>PartnerServer: Collect payment from customer (your own gateway)

    PartnerServer->>CleanLife: POST /partners/bookings\n{ externalReference: "ORDER-001", contactId, addressId, serviceId, ... }
    CleanLife-->>PartnerServer: { bookingId, status: "in progress", paymentStatus: "PENDING" }

    PartnerServer->>CleanLife: POST /partners/bookings/{bookingId}/confirm-payment\n{ paymentReference: "TXN-123" }
    CleanLife-->>PartnerServer: { paymentStatus: "PAID" }

    Note over CleanLife,PartnerServer: Later, ops team schedules the appointment

    CustomerApp->>PartnerServer: Customer asks for tracking
    PartnerServer->>CleanLife: GET /partners/bookings/{bookingId}/status
    CleanLife-->>PartnerServer: { status: "in progress", appointment: { status: "Scheduled" } }
    PartnerServer-->>CustomerApp: Show tracking info
```

***

## Flow 2: CLEANOS Responsibility — Booking with Async Payment

For partners where CleanLife handles payment collection.

```mermaid theme={null}
sequenceDiagram
    participant CustomerApp as Your Customer App
    participant PartnerServer as Your Server
    participant CleanLife as CleanLife Partner API

    CustomerApp->>PartnerServer: Customer selects service

    PartnerServer->>CleanLife: POST /partners/contacts\n{ phone, name, latitude, longitude, ... }
    CleanLife-->>PartnerServer: { id, addressId }

    PartnerServer->>CleanLife: GET /partners/services?addressId=...
    CleanLife-->>PartnerServer: Categories with nested services

    PartnerServer->>CleanLife: POST /partners/bookings\n{ contactId, addressId, serviceId, ... }
    CleanLife-->>PartnerServer: { bookingId, status: "waiting payment" }
    Note right of CleanLife: CleanLife sends payment link to customer asynchronously

    PartnerServer->>CleanLife: GET /partners/bookings/{bookingId}/status
    CleanLife-->>PartnerServer: { status, paymentStatus }
    Note over PartnerServer: Poll status or notify customer based on payment outcome
```

***

## Flow 3: Cancellation

```mermaid theme={null}
sequenceDiagram
    participant CustomerApp as Your Customer App
    participant PartnerServer as Your Server
    participant CleanLife as CleanLife Partner API

    CustomerApp->>PartnerServer: Customer requests cancellation

    PartnerServer->>CleanLife: GET /partners/bookings/cancellation-reasons
    CleanLife-->>PartnerServer: [{ id, nameEn, nameAr }, ...]

    PartnerServer->>CleanLife: PATCH /partners/bookings/{bookingId}/cancel\n{ reasonId, notes }
    CleanLife-->>PartnerServer: { status: "canceled", paymentStatus: "CANCELLED" }

    Note over PartnerServer: For PARTNER responsibility:\nHandle refund in your own system

    PartnerServer->>PartnerServer: Update internal order status
```