Patient Services API Reference

GET /billing/patient_facilities/:patient_facility_id/services

curl -X GET "https://api.example.com/billing/patient_facilities/550e8400-e29b-41d4-a716-446655440000/services?page=1&per_page=10&status=pending" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

{
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "service_number": "PSV-2024-000001",
      "service_name": "General Consultation",
      "service_type": "consultation",
      "status": "pending",
      "service_datetime": "2024-01-15T10:00:00Z",
      "quantity": 1.0,
      "unit_price": 1000.0,
      "total_amount": 1000.0,
      "is_billed": false,
      "is_paid": false,
      "billing_status": "unbilled",
      "payment_status": "unpaid",
      "patient": {
        "id": "770e8400-e29b-41d4-a716-446655440001",
        "name": "John Doe",
        "phone": "+919876543210"
      },
      "practitioner": {
        "id": "880e8400-e29b-41d4-a716-446655440001",
        "name": "Dr. Jane Smith"
      }
    }
  ],
  "meta": {
    "request_id": "uuid-here",
    "pagination": {
      "total_entries": 25,
      "total_pages": 3,
      "current_page": 1,
      "per_page": 10
    }
  }
}

POST /billing/patient_facilities/:patient_facility_id/services

curl -X POST "https://api.example.com/billing/patient_facilities/550e8400-e29b-41d4-a716-446655440000/services" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_service": {
      "service_name": "General Consultation",
      "service_type": "consultation",
      "service_datetime": "2024-01-15T10:00:00Z",
      "quantity": 1,
      "unit_price": 1000.00,
      "practitioner_id": "880e8400-e29b-41d4-a716-446655440001",
      "encounter_id": "990e8400-e29b-41d4-a716-446655440001",
      "facility_service_id": "aa0e8400-e29b-41d4-a716-446655440001",
      "description": "Follow-up consultation"
    }
  }'

curl -X POST "https://api.example.com/billing/patient_facilities/550e8400-e29b-41d4-a716-446655440000/services" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "service_name": "General Consultation",
    "service_type": "consultation",
    "service_date": "2024-01-15T10:00:00Z",
    "quantity": 1,
    "price": 1000.00,
    "doctor_id": "880e8400-e29b-41d4-a716-446655440001",
    "appointment_id": "990e8400-e29b-41d4-a716-446655440001",
    "clinic_service_id": "aa0e8400-e29b-41d4-a716-446655440001"
  }'

{
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "service_number": "PSV-2024-000001",
    "service_name": "General Consultation",
    "service_type": "consultation",
    "status": "pending",
    "service_datetime": "2024-01-15T10:00:00Z",
    "quantity": 1.0,
    "unit_price": 1000.0,
    "total_amount": 1000.0,
    "is_billed": false,
    "is_paid": false,
    "billing_status": "unbilled",
    "payment_status": "unpaid",
    "patient": {
      "id": "770e8400-e29b-41d4-a716-446655440001",
      "name": "John Doe",
      "phone": "+919876543210"
    },
    "practitioner": {
      "id": "880e8400-e29b-41d4-a716-446655440001",
      "name": "Dr. Jane Smith"
    }
  },
  "meta": {
    "request_id": "uuid-here"
  }
}

GET /billing/patient_services/:id

curl -X GET "https://api.example.com/billing/patient_services/660e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

{
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "service_number": "PSV-2024-000001",
    "service_name": "General Consultation",
    "service_type": "consultation",
    "status": "pending",
    "service_datetime": "2024-01-15T10:00:00Z",
    "quantity": 1.0,
    "unit_price": 1000.0,
    "total_amount": 1000.0,
    "is_billed": false,
    "is_paid": false,
    "billing_status": "unbilled",
    "payment_status": "unpaid",
    "description": "Follow-up consultation",
    "discount_percent": 0.0,
    "discount_amount": 0.0,
    "patient": {
      "id": "770e8400-e29b-41d4-a716-446655440001",
      "name": "John Doe",
      "phone": "+919876543210"
    },
    "practitioner": {
      "id": "880e8400-e29b-41d4-a716-446655440001",
      "name": "Dr. Jane Smith"
    },
    "facility": {
      "id": "bb0e8400-e29b-41d4-a716-446655440001",
      "name": "Main Clinic"
    },
    "encounter": {
      "id": "990e8400-e29b-41d4-a716-446655440001",
      "status": "in_progress"
    },
    "facility_service": {
      "id": "aa0e8400-e29b-41d4-a716-446655440001",
      "name": "Consultation Service"
    },
    "created_at": "2024-01-15T09:00:00Z",
    "updated_at": "2024-01-15T09:00:00Z"
  },
  "meta": {
    "request_id": "uuid-here"
  }
}

PATCH /billing/patient_services/:id

curl -X PATCH "https://api.example.com/billing/patient_services/660e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_service": {
      "quantity": 2,
      "unit_price": 900.00,
      "discount_percent": 10
    }
  }'

{
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "service_number": "PSV-2024-000001",
    "service_name": "General Consultation",
    "service_type": "consultation",
    "status": "pending",
    "service_datetime": "2024-01-15T10:00:00Z",
    "quantity": 2.0,
    "unit_price": 900.0,
    "total_amount": 1620.0,
    "is_billed": false,
    "is_paid": false,
    "billing_status": "unbilled",
    "payment_status": "unpaid",
    "description": "Follow-up consultation",
    "discount_percent": 10.0,
    "discount_amount": 0.0,
    "patient": {
      "id": "770e8400-e29b-41d4-a716-446655440001",
      "name": "John Doe",
      "phone": "+919876543210"
    },
    "practitioner": {
      "id": "880e8400-e29b-41d4-a716-446655440001",
      "name": "Dr. Jane Smith"
    },
    "facility": {
      "id": "bb0e8400-e29b-41d4-a716-446655440001",
      "name": "Main Clinic"
    },
    "encounter": {
      "id": "990e8400-e29b-41d4-a716-446655440001",
      "status": "in_progress"
    },
    "facility_service": {
      "id": "aa0e8400-e29b-41d4-a716-446655440001",
      "name": "Consultation Service"
    },
    "created_at": "2024-01-15T09:00:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "uuid-here"
  }
}

DELETE /billing/patient_services/:id

curl -X DELETE "https://api.example.com/billing/patient_services/660e8400-e29b-41d4-a716-446655440001?reason=Patient%20cancelled" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

{
  "errors": [
    {
      "field": "service_name",
      "message": "can't be blank"
    },
    {
      "field": "unit_price",
      "message": "must be greater than or equal to 0"
    }
  ],
  "meta": {
    "request_id": "uuid-here"
  }
}

{
  "errors": [
    {
      "field": "base",
      "message": "PatientService not found"
    }
  ],
  "meta": {
    "request_id": "uuid-here"
  }
}

{
  "errors": [
    {
      "field": "base",
      "message": "You are not authorized to perform this action"
    }
  ],
  "meta": {
    "request_id": "uuid-here"
  }
}

// Service Types
type ServiceType = 'consultation' | 'procedure' | 'laboratory' | 'pharmacy' | 'diagnostic' | 'therapy' | 'other';
type ServiceStatus = 'pending' | 'completed' | 'cancelled';

// Service Response
interface PatientService {
  id: string;
  service_number: string;
  service_name: string;
  service_type: ServiceType;
  status: ServiceStatus;
  service_datetime: string;
  quantity: number;
  unit_price: number;
  total_amount: number;
  is_billed: boolean;
  is_paid: boolean;
  billing_status: 'billed' | 'unbilled';
  payment_status: 'paid' | 'unpaid';
  description?: string;
  discount_percent?: number;
  discount_amount?: number;
  patient: {
    id: string;
    name: string;
    phone: string;
  } | null;
  practitioner: {
    id: string;
    name: string;
  } | null;
  facility?: {
    id: string;
    name: string;
  };
  encounter?: {
    id: string;
    status: string;
  };
  facility_service?: {
    id: string;
    name: string;
  };
  created_at?: string;
  updated_at?: string;
}

// Create Request
interface CreatePatientServiceRequest {
  service_name: string;
  service_datetime: string;
  quantity: number;
  unit_price: number;
  service_type?: ServiceType;
  description?: string;
  facility_id?: string;
  practitioner_id?: string;
  encounter_id?: string;
  episode_of_care_id?: string;
  facility_service_id?: string;
  facility_procedure_id?: string;
  category_id?: string;
  discount_percent?: number;
  discount_amount?: number;
  tax_percent?: number;
  tax_amount?: number;
  care_package_service_id?: string;
  benefits_used?: number;
  metadata?: Record<string, unknown>;
}

// Update Request
interface UpdatePatientServiceRequest {
  service_name?: string;
  service_datetime?: string;
  quantity?: number;
  unit_price?: number;
  service_type?: ServiceType;
  description?: string;
  practitioner_id?: string;
  encounter_id?: string;
  facility_service_id?: string;
  facility_procedure_id?: string;
  category_id?: string;
  discount_percent?: number;
  discount_amount?: number;
  tax_percent?: number;
  tax_amount?: number;
  status?: ServiceStatus;
}

// List Query Params
interface ListServicesParams {
  facility_id?: string;
  practitioner_id?: string;
  category_id?: string;
  encounter_id?: string;
  service_type?: ServiceType;
  status?: ServiceStatus;
  is_paid?: 'true' | 'false';
  is_billed?: 'true' | 'false';
  start_date?: string;
  end_date?: string;
  search?: string;
  patient_name?: string;
  page?: number;
  per_page?: number;
  sort_by?: string;
  sort_order?: 'asc' | 'desc';
}

// API Response
interface ApiResponse<T> {
  data: T;
  meta: {
    request_id: string;
    pagination?: {
      total_entries: number;
      total_pages: number;
      current_page: number;
      per_page: number;
    };
  };
}

// Error Response
interface ApiErrorResponse {
  errors: Array<{
    field: string;
    message: string;
  }>;
  meta: {
    request_id: string;
  };
}

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { apiClient } from '@kulcare/api-client';

// List services
export function usePatientServices(patientFacilityId: string, params?: ListServicesParams) {
  return useQuery({
    queryKey: ['patient-services', patientFacilityId, params],
    queryFn: () =>
      apiClient.get<ApiResponse<PatientService[]>>(
        `/billing/patient_facilities/${patientFacilityId}/services`,
        { params }
      ),
  });
}

// Get single service
export function usePatientService(id: string) {
  return useQuery({
    queryKey: ['patient-service', id],
    queryFn: () =>
      apiClient.get<ApiResponse<PatientService>>(`/billing/patient_services/${id}`),
    enabled: !!id,
  });
}

// Create service
export function useCreatePatientService() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: ({
      patientFacilityId,
      data,
    }: {
      patientFacilityId: string;
      data: CreatePatientServiceRequest;
    }) =>
      apiClient.post<ApiResponse<PatientService>>(
        `/billing/patient_facilities/${patientFacilityId}/services`,
        { patient_service: data }
      ),
    onSuccess: (_, { patientFacilityId }) => {
      queryClient.invalidateQueries({ queryKey: ['patient-services', patientFacilityId] });
    },
  });
}

// Update service
export function useUpdatePatientService() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: ({
      id,
      data,
    }: {
      id: string;
      data: UpdatePatientServiceRequest;
    }) =>
      apiClient.patch<ApiResponse<PatientService>>(
        `/billing/patient_services/${id}`,
        { patient_service: data }
      ),
    onSuccess: (_, { id }) => {
      queryClient.invalidateQueries({ queryKey: ['patient-service', id] });
      queryClient.invalidateQueries({ queryKey: ['patient-services'] });
    },
  });
}

// Delete service
export function useDeletePatientService() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: ({
      id,
      reason,
    }: {
      id: string;
      reason: string;
    }) =>
      apiClient.delete(`/billing/patient_services/${id}`, {
        params: { reason },
      }),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['patient-services'] });
    },
  });
}