4U Real Estate - Housekeeping API Documentation

Sommaire

Authentification
Cycle de vie d'une tâche
Lister les tâches
Statistiques
Problèmes signalés
Notes de maintenance
Détail d'une tâche
Créer une tâche
Modifier une tâche
Changer le statut
Checklist (ajout/maj)
Ajouter une note
Note rapide par lot
Article manquant
Supprimer une tâche
Équipes & superviseurs
Champs d'une tâche
Codes d'erreur

🔐 Authentification

Clé API requise

Toutes les requêtes nécessitent une clé API valide envoyée via le header x-api-key.

curl -H "x-api-key: YOUR_API_KEY" https://listings.4u-realestate.org/tasks

🔄 Cycle de vie d'une tâche

pending → checked_out → supervisor_check_in → cleaning → cleaning_done → windows_cleaned → supervisor_check_out → completed

À tout moment : issue_reported cancelled

Statuts disponibles

pending

En attente

checked_out

Client parti

supervisor_check_in

Inspection avant

cleaning

Nettoyage en cours

cleaning_done

Nettoyage terminé

windows_cleaned

Vitres nettoyées

supervisor_check_out

Inspection finale

completed

Terminé

issue_reported

Problème signalé

cancelled

Annulé

currentStep : cleaning, inventory, maintenance, building, cleaning_intermediate. priority : low, medium, high.

📡 Endpoints tâches

GET /tasks Lister les tâches (filtres + pagination)

Retourne les tâches de planning. Les tâches "standalone" (issues/maintenance hors planning) sont exclues par défaut.

QUERY PARAMS

Param	Type	Description
date	YYYY-MM-DD	Tâches d'un jour précis
startDate	YYYY-MM-DD	Début de plage
endDate	YYYY-MM-DD	Fin de plage
lotId	ObjectId	Filtrer par lot
status	string	Un ou plusieurs (séparés par virgule)
priority	string	low / medium / high
currentStep	string	cleaning, inventory, maintenance...
includeStandalone	boolean	true pour inclure les standalone
light	boolean	true (défaut) exclut photos/videos
page	number	Page (défaut 1)
limit	number	Par page (défaut 100, max 500)

Exemple

curl -H "x-api-key: YOUR_KEY" \
  "https://listings.4u-realestate.org/tasks?date=2026-06-20&status=pending,cleaning"

GET /tasks/stats Statistiques par statut

Compte total, completed, pending, inProgress et détail par statut. Accepte date / startDate / endDate.

Exemple

curl -H "x-api-key: YOUR_KEY" \
  "https://listings.4u-realestate.org/tasks/stats?date=2026-06-20"

GET /tasks/issues Tâches avec problème

Tâches en issue_reported ou avec un item de checklist en issue. Filtre optionnel lotId.

GET /tasks/maintenance-notes Toutes les notes de maintenance

Agrège les notes de maintenance de toutes les tâches. Filtres : lotId, status (pending / in_progress / resolved).

GET /tasks/:id Détail complet (avec photos/videos)

Retourne la tâche complète avec lot, équipe de ménage et superviseur peuplés.

Exemple

curl -H "x-api-key: YOUR_KEY" \
  "https://listings.4u-realestate.org/tasks/665f1a2b3c4d5e6f7a8b9c0d"

POST /tasks Créer une tâche de planning

BODY

Champ	Type	Description
lotIdrequis	ObjectId	Lot concerné
scheduledDaterequis	Date	Date prévue
scheduledTime	string	Heure (défaut 10:00)
priority	string	low / medium / high
cleaningTeam	ObjectId	Équipe assignée
assignedSupervisorId	ObjectId	Superviseur
notes	string	Notes libres

Exemple

curl -X POST -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"lotId":"665f...","scheduledDate":"2026-06-21","priority":"high"}' \
  "https://listings.4u-realestate.org/tasks"

PUT /tasks/:id Modifier une tâche (champs partiels)

Met à jour n'importe quel champ (scheduledDate, priority, cleaningTeam, assignedSupervisorId, notes...).

PATCH /tasks/:id/status Changer le statut

BODY

Champ	Type	Description
statusrequis	string	Nouveau statut
currentStep	string	Étape optionnelle

Quand status=completed, completedAt est rempli automatiquement.

Exemple

curl -X PATCH -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"status":"cleaning"}' \
  "https://listings.4u-realestate.org/tasks/665f.../status"

POST /tasks/:id/checklist Ajouter un item de checklist

BODY

Champ	Type	Description
labelrequis	string	Libellé
steprequis	string	cleaning / inventory / maintenance / building
description	string	Détail
category	string	Catégorie
remark	string	Remarque
photos	string[]	URLs de photos

PATCH /tasks/:id/checklist/:itemId Mettre à jour un item

Champs modifiables : label, description, category, status (pending/done/validated/issue), remark, photos, order. Si status=issue, la tâche passe en issue_reported.

POST /tasks/:id/maintenance-notes Ajouter une note de maintenance

BODY

Champ	Type	Description
descriptionrequis	string	Description du problème
priority	string	low / medium / high
category	string	plumbing, electrical, appliance, furniture, paint, cleaning, other
photos	string[]	URLs de photos

POST /tasks/maintenance Note de maintenance rapide par lot

Crée (ou réutilise) une tâche standalone pour le lot et y ajoute une note. N'apparaît pas dans le planning.

BODY

Champ	Type	Description
lotIdrequis	ObjectId	Lot concerné
descriptionrequis	string	Description
priority	string	low / medium / high
category	string	Catégorie
scheduledDate	Date	Date (défaut aujourd'hui)
photos	string[]	URLs de photos

POST /tasks/missing-item Signaler un article manquant / problème

BODY

Champ	Type	Description
lotIdrequis	ObjectId	Lot concerné
labelrequis	string	Article / problème
description	string	Détail
step	string	Défaut inventory
remark	string	Remarque
scheduledDate	Date	Date
photos	string[]	URLs de photos

DELETE /tasks/:id Supprimer une tâche

Suppression définitive de la tâche.

👥 Équipes & superviseurs

GET /housekeeping/cleaning-teams Lister les équipes de ménage

Retourne les équipes (name, members, phone, isActive) pour assignation.

GET /housekeeping/supervisors Lister les superviseurs

Retourne les superviseurs housekeeping pour assignation.

GET /lots Lister les lots (id, name, lotNo...)

Utile pour récupérer les lotId nécessaires à la création de tâches.

📋 Champs d'une tâche

Champ	Type	Description
_id	ObjectId	Identifiant unique
lotId	object	Lot peuplé (name, lotNo, lodgifyId)
bookingId	ObjectId	Réservation liée (optionnel)
scheduledDate	Date	Date prévue
scheduledTime	string	Heure prévue
status	string	Statut courant
currentStep	string	Étape en cours
priority	string	low / medium / high
cleaningTeam	object	Équipe assignée
assignedSupervisorId	object	Superviseur
checklist	array	Items {label, step, status, remark, photos}
maintenanceNotes	array	Notes {description, priority, category, status}
conditionReport	object	Rapport d'état (light: exclu)
photos / videos	array	Médias (light: exclus)
notes	string	Notes libres
completedAt	Date	Date de fin
isStandalone	boolean	Hors planning (issue/maintenance)
isManual / isAutoGenerated	boolean	Origine de la tâche

⚠️ Codes d'erreur

Code	Signification	Solution
400	Données invalides ou ID malformé	Vérifier les champs requis
401	Clé API manquante ou invalide	Ajouter un header x-api-key valide
403	Clé API désactivée	Contacter l'admin
404	Tâche ou lot non trouvé	Vérifier l'ID
429	Rate limit dépassé	Attendre et réessayer
500	Erreur serveur	Contacter contact@4u-realestate.org

4U Housekeeping API

Sommaire

🔐 Authentification

Clé API requise

🔄 Cycle de vie d'une tâche

Statuts disponibles

📡 Endpoints tâches

QUERY PARAMS

Exemple

Exemple

Exemple

BODY

Exemple

BODY

Exemple

BODY

BODY

BODY

BODY

👥 Équipes & superviseurs

📋 Champs d'une tâche

⚠️ Codes d'erreur