Leases

Create a lease charge

Create a new lease charge for a lease.

Validations performed:

  • service_place / lease compatibility: The service must be attached to the same place as the lease's estate
  • Automatic resolution of the distribution key: If distribution_key_id is not provided, uses default_distribution_key_id from the service_place
  • Distribution / billing consistency: Checks that the distribution is compatible with the billing method (e.g., CONSOMMATION_MESUREE requires RELEVE_DIRECT or PROVISION)
  • Method / basis consistency: Checks that the billing method is compatible with the calculation basis
  • Lease type compatibility: Checks that the category and billing method are allowed for this lease type
  • Period validation: Checks that billing periods are within the lease boundaries and respect max_provisional_months if applicable
  • Category x basis compatibility: Checks that personnel calculation bases are only used with the EMPLOYEE category
post/leases/{lease_id}/charges

Request

  • Base URL: https://api.faireplace.com/api
  • URL: https://api.faireplace.com/api/leases/{lease_id}/charges
  • Auth: HTTP bearer

Path parameters

lease_idstring uuid required

Lease ID

Request body

service_place_idstring uuid nullable

Place service ID. If provided:

  • The service must be attached to the same place as the lease's estate
  • The service must be chargeable (is_chargeable = true)
  • The service must have a default_distribution_key_id if distribution_key_id is not provided
category_idstring uuid nullable

Category ID. If not provided, it will be resolved from service_place.category_id if service_place_id is provided. The category must be allowed for the lease type.

calculation_method'FORFAIT' | 'PROVISION' | 'DEPENSE_REELLE' | 'RELEVE_DIRECT' required

Charge billing mode to the tenant (provision/fixed/actual expense).

Compatibility rules:

  • CONSOMMATION_MESUREE (distribution) requires RELEVE_DIRECT or PROVISION
  • FORFAIT requires FORFAIT as calculation basis
  • DEPENSE_REELLE requires DEPENSE_REELLE or a staff basis as calculation basis
  • PROVISION can be used with all calculation bases
  • The mode must be allowed for the lease type (allow_provisional, allow_fixed)
calculation_basis'DEPENSE_REELLE' | 'FORFAIT' | 'PERSONNEL_75_POURCENT' | 'PERSONNEL_40_POURCENT' | 'PERSONNEL_100_POURCENT' required

Base de calcul d'une charge récupérable (art. 23-1).

Les trois valeurs PERSONNEL_… s'écrivent avec un underscore après PERSONNEL, exactement comme en base: c'est la même orthographe partout.

amountnumber required

Charge amount

billing_period_startstring date nullable

Billing period start date. Must be:

  • = lease.start_date

  • <= billing_period_end if provided
  • <= lease.end_date if the lease has an end date
billing_period_endstring date nullable

Billing period end date. Must be:

  • = billing_period_start

  • <= lease.end_date if the lease has an end date
  • If calculation_method is PROVISION, the duration must not exceed max_provisional_months of the lease type
distribution_key_idstring uuid nullable

Distribution key ID. If not provided:

  • Will be resolved from service_place.default_distribution_key_id if service_place_id is provided
  • Otherwise, an error will be returned
notesstring nullable

Notes

Example request

{
  "calculation_method": "PROVISION",
  "calculation_basis": "FORFAIT",
  "energy_efficiency": {
    "baseline_consumption": 15000,
    "target_savings_percentage": 25,
    "monthly_contribution_amount": 50,
    "duration_months": 36,
    "work_description": "Attic thermal insulation and boiler replacement",
    "work_cost": 18000,
    "energy_audit_reference": "DPE-2024-001234",
    "start_date": "2024-01-01"
  },
  "insurance": {
    "contract_number": "ASS-COL-2024-001",
    "insurance_company": "AXA Assurances",
    "annual_premium": 1200,
    "recoverable_amount": 1200,
    "coverage_details": "Civil liability, water damage, fire",
    "policy_start_date": "2024-01-01",
    "policy_end_date": "2024-12-31",
    "deductible_amount": 150,
    "coverage_limits": {
      "civil_liability": 2000000,
      "water_damage": 50000
    },
    "exclusions": "Intentional damage, undeclared natural disasters"
  }
}

Response

Charge created successfully

idstring uuid required

Unique identifier of the charge

lease_idstring uuid required

Lease ID

service_place_idstring uuid nullable

Place service ID

category_idstring uuid nullable

Charge category ID

calculation_method'FORFAIT' | 'PROVISION' | 'DEPENSE_REELLE' | 'RELEVE_DIRECT' required

Charge billing mode to the tenant (provision/fixed/actual expense).

Compatibility rules:

  • CONSOMMATION_MESUREE (distribution) requires RELEVE_DIRECT or PROVISION
  • FORFAIT requires FORFAIT as calculation basis
  • DEPENSE_REELLE requires DEPENSE_REELLE or a staff basis as calculation basis
  • PROVISION can be used with all calculation bases
  • The mode must be allowed for the lease type (allow_provisional, allow_fixed)
calculation_basis'DEPENSE_REELLE' | 'FORFAIT' | 'PERSONNEL_75_POURCENT' | 'PERSONNEL_40_POURCENT' | 'PERSONNEL_100_POURCENT' required

Base de calcul d'une charge récupérable (art. 23-1).

Les trois valeurs PERSONNEL_… s'écrivent avec un underscore après PERSONNEL, exactement comme en base: c'est la même orthographe partout.

amountnumber required

Charge amount

billing_period_startstring date nullable

Billing period start date

billing_period_endstring date nullable

Billing period end date

last_regularization_datestring date nullable

Last regularization date

distribution_key_idstring uuid nullable

Distribution key ID

notesstring nullable

Notes about the charge

created_atstring date-time required

Creation date

updated_atstring date-time required

Last modification date

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "lease_id": "550e8400-e29b-41d4-a716-446655440001",
  "calculation_method": "PROVISION",
  "calculation_basis": "FORFAIT",
  "amount": 150
}

Changes

No recorded changes to this operation across all 1 revision of this API.