Lease Management

Copy page

Charges API

Manage service charges (charges locatives) for leases — utilities, maintenance, insurance, and other recurring costs billed to tenants. Track meter readings and validate charges against French regulations.

Quick Example

Code
 
curl -X POST https://api.faireplace.com/api/charges/categories \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Eau et assainissement",
    "category_type": "Utilities",
    "legal_reference": "Article L.442-3",
    "notification_threshold": 100.00,
    "notification_frequency": "monthly"
  }'

Common Workflows

Set up charges for a lease

1. POST /api/charges/categories — Create charge categories (water, heating, maintenance)
2. POST /api/charges/readings — Record meter readings
3. GET /api/charges/readings/{id}/validate — Validate against business rules

Annual charge settlement (regularisation)

1. GET /api/charges/readings — Get all readings for the period
2. Compare total readings vs. provisioned amounts
3. Calculate settlement amount (surplus or deficit)

---

Overview

The Charges API is organized into two main sub-modules:

• Categories: Manage different types of service charges
• Readings: Handle meter readings and charge calculations

Authentication

All endpoints require authentication with the following permissions:

• LeasesRead: For GET operations
• LeasesWrite: For POST and PUT operations
• LeasesDelete: For DELETE operations

Base URL

All charge endpoints are prefixed with /api/charges

---

Service Charge Categories

List Categories

GET /api/charges/categories

Retrieve all service charge categories with optional filtering.

Query Parameters:

• category_type (optional): Filter by specific charge category type

Response:

Code
 
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Eau et assainissement",
    "description": "Charges mensuelles eau et assainissement",
    "legal_reference": "Article L.442-3",
    "category_type": "Utilities",
    "maintenance_details": {
      "frequency": "monthly",
      "contractor": "Eau de Paris"
    },
    "notification_threshold": 100.00,
    "notification_frequency": "monthly",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]

Create Category

POST /api/charges/categories

Create a new service charge category.

Request Body:

Code
 
{
  "name": "Entretien chauffage",
  "description": "Entretien annuel du systeme de chauffage",
  "legal_reference": "Article L.442-4",
  "category_type": "Maintenance",
  "maintenance_details": {
    "frequency": "annual",
    "contractor": "Thermi-Services Paris"
  },
  "notification_threshold": 500.00,
  "notification_frequency": "quarterly"
}

Response: 201 Created

Code
 
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "Entretien chauffage",
  "description": "Entretien annuel du systeme de chauffage",
  "legal_reference": "Article L.442-4",
  "category_type": "Maintenance",
  "maintenance_details": {
    "frequency": "annual",
    "contractor": "Thermi-Services Paris"
  },
  "notification_threshold": 500.00,
  "notification_frequency": "quarterly",
  "created_at": "2024-01-15T11:00:00Z",
  "updated_at": "2024-01-15T11:00:00Z"
}

Get Category

GET /api/charges/categories/{id}

Retrieve a specific service charge category by ID.

Path Parameters:

• id (UUID): The category ID

Response: 200 OK

Code
 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Eau et assainissement",
  "description": "Charges mensuelles eau et assainissement",
  "legal_reference": "Article L.442-3",
  "category_type": "Utilities",
  "maintenance_details": {
    "frequency": "monthly",
    "contractor": "Eau de Paris"
  },
  "notification_threshold": 100.00,
  "notification_frequency": "monthly",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Update Category

PUT /api/charges/categories/{id}

Update an existing service charge category.

Path Parameters:

• id (UUID): The category ID

Request Body:

Code
 
{
  "name": "Eau, assainissement et dechets",
  "description": "Charges mensuelles eau, assainissement et collecte des dechets",
  "legal_reference": "Article L.442-3",
  "category_type": "Utilities",
  "maintenance_details": {
    "frequency": "monthly",
    "contractor": "Eau de Paris"
  },
  "notification_threshold": 150.00,
  "notification_frequency": "monthly"
}

Response: 200 OK Returns the updated category object.

Delete Category

DELETE /api/charges/categories/{id}

Delete a service charge category.

Path Parameters:

• id (UUID): The category ID

Response: 204 No Content

---

Charge Readings

List Readings

GET /api/charges/readings

Retrieve all charge readings with optional filtering.

Response:

Code
 
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440010",
    "category_id": "550e8400-e29b-41d4-a716-446655440000",
    "lease_id": "550e8400-e29b-41d4-a716-446655440020",
    "reading_value": 1234.56,
    "reading_date": "2024-01-31T00:00:00Z",
    "meter_type": "water",
    "is_estimated": false,
    "notes": "Regular monthly reading",
    "created_at": "2024-02-01T08:00:00Z",
    "updated_at": "2024-02-01T08:00:00Z"
  }
]

Create Reading

POST /api/charges/readings

Create a new charge reading.

Request Body:

Code
 
{
  "category_id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440020",
  "reading_value": 1234.56,
  "reading_date": "2024-01-31T00:00:00Z",
  "meter_type": "water",
  "is_estimated": false,
  "notes": "Regular monthly reading"
}

Response: 201 Created Returns the created reading object.

Get Reading

GET /api/charges/readings/{id}

Retrieve a specific charge reading by ID.

Path Parameters:

• id (UUID): The reading ID

Response: 200 OK Returns the reading object.

Update Reading

PUT /api/charges/readings/{id}

Update an existing charge reading.

Path Parameters:

• id (UUID): The reading ID

Request Body:

Code
 
{
  "category_id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440020",
  "reading_value": 1245.78,
  "reading_date": "2024-01-31T00:00:00Z",
  "meter_type": "water",
  "is_estimated": false,
  "notes": "Corrected reading value"
}

Response: 200 OK Returns the updated reading object.

Delete Reading

DELETE /api/charges/readings/{id}

Delete a charge reading.

Path Parameters:

• id (UUID): The reading ID

Response: 204 No Content

Validate Reading

GET /api/charges/readings/{id}/validate

Validate a charge reading against business rules.

Path Parameters:

• id (UUID): The reading ID

Response: 200 OK

Code
 
{
  "is_valid": true,
  "validation_errors": [],
  "warnings": []
}

---

Data Types

ChargeCategoryType

Enum values:

• Utilities - Water, electricity, gas, internet
• Maintenance - Building maintenance, repairs
• Insurance - Property and liability insurance
• Administration - Management and administrative fees
• Other - Miscellaneous charges

MaintenanceDetails

Code
 
{
  "frequency": "monthly|quarterly|annual",
  "contractor": "string",
  "last_service_date": "2024-01-15T00:00:00Z",
  "next_service_date": "2024-02-15T00:00:00Z"
}

---

Error Responses

Validation Errors

400 Bad Request

Code
 
{
  "error": "ValidationError",
  "message": "Invalid input data",
  "details": [
    {
      "field": "name",
      "message": "Name is required and must be between 1 and 255 characters"
    }
  ]
}

Not Found

404 Not Found

Code
 
{
  "error": "NotFound",
  "message": "Service charge category not found"
}

Unauthorized

403 Forbidden

Code
 
{
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

---

Common Use Cases

Creating a New Utility Charge Category

1. Create category with POST /api/charges/categories
2. Set appropriate notification thresholds
3. Configure maintenance details for recurring services

Recording Monthly Meter Readings

1. Retrieve active leases
2. For each meter, create reading with POST /api/charges/readings
3. Validate readings with GET /api/charges/readings/{id}/validate
4. Generate charge calculations based on readings

Managing Seasonal Charges

1. Create seasonal categories (heating, cooling)
2. Set up appropriate notification frequencies
3. Track consumption patterns through readings

---

Notes

• All monetary values are stored as BigDecimal for precision
• Notification thresholds help identify unusual consumption patterns
• Readings can be marked as estimated for incomplete data
• The system supports various meter types (water, electricity, gas, etc.)
• Legal references ensure compliance with local regulations