Cas d'usage
CRM & prospection
Synchronisez clients et prospects (HubSpot, Pipedrive…), soyez prévenu quand un prospect devient client.
Comptabilité & paiements
Récupérez les factures et leur statut (payée, en retard) pour votre logiciel comptable.
Paie & pointage
Exportez le planning réalisé par agent et par site vers la paie ou un outil RH.
Tableaux de bord
Alimentez Looker Studio, Power BI ou un tableur avec devis, factures et interventions.
Réservation en ligne
Proposez les vrais créneaux libres et créez client, site et intervention en un appel.
Assistants IA
Laissez Claude, ChatGPT ou vos agents consulter et agir via MCP ou OpenAPI.
Démarrage rapide en 5 minutes
- Créez une clé : un administrateur ouvre Paramètres → Développeurs & API, clique « Nouvelle clé » et copie la valeur
cp_live_…(affichée une seule fois). - Stockez-la côté serveur dans une variable d'environnement
CLEANPLUS_KEY. - Testez l'appel ci-dessous : il renvoie votre organisation et les droits de la clé. Chaque appel apparaît en direct dans le journal du même écran.
- Déclarez un webhook https dans le même écran et cliquez « Tester » pour valider la réception.
curl https://cleanplus.app/api/public/v1/me -H "Authorization: Bearer $CLEANPLUS_KEY"Exemple, parcours type d'un tunnel de réservation :
1. GET /availability → afficher les créneaux libres pour la durée estimée
2. POST /bookings → à la validation : client + site + intervention créés
3. Webhooks → booking.rescheduled / cancelled / intervention.completed
4. PATCH ou /cancel → modification ou annulation demandée par le clientAuthentification & droits
Chaque requête porte la clé dans l'en-tête Authorization. Les clés sont propres à une organisation : toutes les données lues ou créées appartiennent à cette organisation. Elles sont stockées chiffrées (empreinte SHA-256) et révocables à tout moment. N'exposez jamais une clé dans le navigateur ou une application mobile : appelez l'API depuis votre serveur.
Authorization: Bearer cp_live_xxxxxxxxxxxxxxxxxxxxxxxx| Droit | Autorise |
|---|---|
| availability:read | Lire les créneaux libres et le catalogue des prestations |
| bookings:write | Créer, modifier, reprogrammer et annuler des réservations |
| bookings:read | Consulter une réservation |
| clients:read | Lister et lire les clients et prospects |
| clients:write | Créer et modifier des clients |
| sites:read | Lister et lire les sites |
| sites:write | Créer et modifier des sites |
| interventions:read | Lire tout le planning (interventions de l'app et de l'API) |
| agents:read | Lister les agents actifs |
| quotes:read | Lister et lire les devis |
| quotes:write | Importer un devis en brouillon avec ses lignes de chiffrage |
| invoices:read | Lister et lire les factures |
| stock:read | Lire le stock (quantités, seuils), l'historique des mouvements et le catalogue produits |
| stock:write | Enregistrer une entrée ou une sortie de stock (jamais de modification directe de la quantité) |
| interventions:write_instructions | Ajouter, remplacer ou retirer une ligne de consignes identifiée par une clé (PUT/DELETE /interventions/{id}/instructions/lines/{key}), sans toucher aux consignes saisies dans l'application |
Bonnes pratiques : une clé par intégration, droits minimum nécessaires, rotation en cas de départ d'un prestataire.
Conventions
- URL de base :
https://cleanplus.app/api/public/v1, HTTPS uniquement. - Format : JSON UTF-8, en-tête
Content-Type: application/jsonpour POST et PATCH. - Fuseau horaire : dates
AAAA-MM-JJet heuresHH:MMexprimées à l'heure de Paris (Europe/Paris) ; horodatages techniques en ISO 8601 UTC. - Idempotence :
POST /bookingsexigeIdempotency-Key(ex. l'id de votre commande). Rejouer la même clé renvoie la même réservation, sans doublon, idéal après un timeout réseau. - Limite de débit : 120 requêtes par minute et par clé ; en-têtes
X-RateLimit-Limit/X-RateLimit-Remaining; au-delà, réponse 429 avecRetry-After. - Pagination : les listes renvoient
{ object: "list", data, has_more, next_cursor }; passezcursor=next_cursorpour la page suivante,limit≤ 100.updated_since(ISO 8601) permet une synchronisation incrémentale. - Traçabilité : chaque réponse porte
X-Request-Id(vous pouvez envoyer le vôtre) etCleanPlus-Version. Tous les appels sont visibles en direct dans Paramètres → Développeurs & API. - IA & agents : la spécification OpenAPI 3.1 est directement exploitable par les assistants IA ; un serveur MCP (
https://cleanplus.app/mcp, connexion OAuth) permet à Claude, ChatGPT ou Cursor d'agir sur votre compte. - CORS : autorisé, mais l'usage serveur est recommandé pour protéger la clé.
- Compatibilité : des champs peuvent être ajoutés aux réponses sans changer de version ; ignorez les champs inconnus.
Vue d'ensemble des endpoints
/metoute cléGET/clientsclients:readGET/clients/{id}clients:readPOST/clientsclients:writePATCH/clients/{id}clients:writeGET/sitessites:readGET/sites/{id}sites:readPOST/sitessites:writePATCH/sites/{id}sites:writeGET/interventionsinterventions:readGET/interventions/{id}interventions:readPUT/interventions/{id}/instructions/lines/{key}interventions:write_instructionsDELETE/interventions/{id}/instructions/lines/{key}interventions:write_instructionsGET/agentsagents:readGET/quotesquotes:readGET/quotes/{id}quotes:readPOST/quotesquotes:writeGET/invoicesinvoices:readGET/invoices/{id}invoices:readGET/stockstock:readGET/stock/{id}stock:readGET/stock/movementsstock:readPOST/stock/movementsstock:writeGET/productsstock:readGET/availabilityavailability:readGET/servicesavailability:readPOST/bookingsbookings:writeGET/bookings/{id}bookings:readPATCH/bookings/{id}bookings:writePOST/bookings/{id}/cancelbookings:writeInformations sur la clé
Organisation, droits et limite de débit
/meRépond pour toute clé valide : utile pour vérifier une installation ou laisser un agent IA découvrir ce qu'il peut faire.
{ "object": "api_key", "organization": { "id": "…", "name": "Propreté Lyon" },
"scopes": ["clients:read", "invoices:read"], "api_version": "2026-10-01",
"rate_limit": { "limit": 120, "window_seconds": 60, "remaining": 118 } }Clients & prospects
Fiches clients et prospects de l'organisation. La création refuse un e-mail ou un SIRET déjà connu (409 already_exists, avec l'id existant) : aucune fiche n'est jamais écrasée.
Lister
/clientsscope : clients:readParamètres de requête
| Champ | Type | Description |
|---|---|---|
| limit | integer | 1 à 100 (défaut 25). |
| cursor | string | Valeur next_cursor de la page précédente. |
| updated_since | datetime | Ne renvoie que ce qui a changé depuis (ISO 8601), synchronisation incrémentale. |
| search | string | Recherche sur le nom. |
| type | enum | particulier ou professionnel. |
| est_prospect | boolean | true = prospects uniquement. |
curl "https://cleanplus.app/api/public/v1/clients?est_prospect=true&limit=50" -H "Authorization: Bearer $CLEANPLUS_KEY"Champs renvoyés (dans data[])
| Champ | Type | Description |
|---|---|---|
| id | uuid | Identifiant. |
| type | enum | particulier | professionnel. |
| name / first_name / company_name | string | Identité. |
| email / phone / siret | string | null | Coordonnées. |
| address / postal_code / city | string | null | Adresse. |
| is_prospect | boolean | Prospect ou client. |
| status / notes | string | null | Statut, notes internes. |
| created_at / updated_at | datetime | Horodatages. |
Lire un client
/clients/{id}scope : clients:readRenvoie l'objet seul, ou 404 not_found s'il n'existe pas ou appartient à une autre organisation.
Créer un client
/clientsscope : clients:writeCorps JSON
| Champ | Type | Description |
|---|---|---|
| namerequis | string ≤200 | Nom ou raison sociale. |
| type | enum | professionnel (défaut) ou particulier. |
| first_name / company_name | string | Prénom, société. |
| Sert au contrôle des doublons. | ||
| phone | string ≤30 | Téléphone. |
| siret | 14 chiffres | Contrôle des doublons. |
| address / postal_code / city | string | Adresse. |
| is_prospect | boolean | false par défaut. |
| notes | string ≤5000 | Notes. |
curl -X POST https://cleanplus.app/api/public/v1/clients -H "Authorization: Bearer $CLEANPLUS_KEY" \
-H "Content-Type: application/json" -d '{ "name": "Résidence Les Tilleuls", "email": "syndic@tilleuls.fr", "phone": "0478000000", "is_prospect": true }'Réponse 201 avec l'objet créé. Déclenche le webhook client.created.
Modifier un client
/clients/{id}scope : clients:writeMise à jour partielle : seuls les champs envoyés sont modifiés (mêmes champs que la création, sauf type).
Sites
Lieux d'intervention, toujours rattachés à un client de l'organisation (404 si le client n'existe pas).
Lister
/sitesscope : sites:readParamètres de requête
| Champ | Type | Description |
|---|---|---|
| limit | integer | 1 à 100 (défaut 25). |
| cursor | string | Valeur next_cursor de la page précédente. |
| updated_since | datetime | Ne renvoie que ce qui a changé depuis (ISO 8601), synchronisation incrémentale. |
| search | string | Recherche sur le nom. |
| client_id | uuid | Sites d'un client. |
curl "https://cleanplus.app/api/public/v1/sites?client_id=<uuid>" -H "Authorization: Bearer $CLEANPLUS_KEY"Champs renvoyés (dans data[])
| Champ | Type | Description |
|---|---|---|
| id / client_id | uuid | Identifiants. |
| name / address | string | Nom, adresse. |
| latitude / longitude | number | null | GPS (pointage géolocalisé). |
| surface / premises_type | string | null | Surface, type de locaux. |
| access_instructions | string | null | Consignes d'accès. |
| contact | object | { name, phone, email } du contact sur place. |
Lire un site
/sites/{id}scope : sites:readRenvoie l'objet seul, ou 404 not_found s'il n'existe pas ou appartient à une autre organisation.
Créer un site
/sitesscope : sites:writeCorps JSON
| Champ | Type | Description |
|---|---|---|
| client_idrequis | uuid | Client propriétaire. |
| namerequis | string ≤200 | Nom du site. |
| addressrequis | string 3–300 | Adresse. |
| latitude / longitude | number | GPS. |
| access_instructions / access_codes | string | Accès, digicode. |
| surface / premises_type | string | Surface, type. |
| contact_name / contact_phone / contact_email | string | Contact sur place. |
| notes | string | Notes. |
curl -X POST https://cleanplus.app/api/public/v1/sites -H "Authorization: Bearer $CLEANPLUS_KEY" \
-H "Content-Type: application/json" -d '{ "client_id": "<uuid>", "name": "Hall A", "address": "12 rue des Lilas, 69003 Lyon", "access_codes": "B1234" }'Réponse 201 avec l'objet créé. Déclenche le webhook site.created.
Modifier un site
/sites/{id}scope : sites:writeMise à jour partielle : seuls les champs envoyés sont modifiés (mêmes champs que la création, sauf client_id).
Planning & interventions
Toutes les interventions du planning, qu'elles viennent de l'application, des récurrences automatiques ou de l'API. Idéal pour la paie, le reporting ou un portail client.
Lister
/interventionsscope : interventions:readParamètres de requête
| Champ | Type | Description |
|---|---|---|
| limit | integer | 1 à 100 (défaut 25). |
| cursor | string | Valeur next_cursor de la page précédente. |
| updated_since | datetime | Ne renvoie que ce qui a changé depuis (ISO 8601), synchronisation incrémentale. |
| date_from / date_to | date | Période (AAAA-MM-JJ). |
| site_id / agent_id | uuid | Filtrer par site ou agent principal. |
| status | enum | planifie, en_cours, termine, annule. |
| source | enum | app ou api. |
curl "https://cleanplus.app/api/public/v1/interventions?date_from=2026-10-01&date_to=2026-10-31&status=termine&limit=100" \
-H "Authorization: Bearer $CLEANPLUS_KEY"Champs renvoyés (dans data[])
| Champ | Type | Description |
|---|---|---|
| id / site_id / agent_id | uuid | Identifiants. |
| date / start_time / end_time | date, HH:MM | Heure de Paris. |
| status | enum | planifie | en_cours | termine | annule. |
| service / instructions | string | null | Prestation, consignes saisies dans l'application (notes : alias historique). |
| instruction_lines | array | Lignes de consignes écrites par vos logiciels : [{ key, text }]. |
| source / external_ref | string | Origine et votre référence. |
Lire une intervention
/interventions/{id}scope : interventions:readRenvoie l'objet seul, ou 404 not_found s'il n'existe pas ou appartient à une autre organisation.
Ajouter ou remplacer une ligne de consignes
/interventions/{id}/instructions/lines/{key}scope : interventions:write_instructionsÉcrit une seule ligne identifiée par key (ex. vehicule), affichée aux agents avec les consignes de l'intervention. Les consignes saisies à la main ne sont jamais modifiées. Rejouer la même requête ne crée pas de doublon.
Corps JSON
| Champ | Type | Description |
|---|---|---|
| textrequis | string ≤500, une ligne | Texte affiché à l'agent. |
curl -X PUT https://cleanplus.app/api/public/v1/interventions/<uuid>/instructions/lines/vehicule -H "Authorization: Bearer $CLEANPLUS_KEY" \
-H "Content-Type: application/json" -d '{ "text": "Véhicule : AB-123-CD (Kangoo blanc)" }'Retirer une ligne de consignes
/interventions/{id}/instructions/lines/{key}scope : interventions:write_instructionsRetire la ligne (ex. désaffectation du véhicule). Réponse 200 avec l'intervention à jour. Clé : minuscules, chiffres, - ou _, 40 caractères maximum ; 20 lignes maximum par intervention.
Agents
Agents actifs (internes et sous-traitants, non archivés). Les données RH sensibles (sécurité sociale, taux horaire) ne sont jamais exposées.
Lister
/agentsscope : agents:readParamètres de requête
| Champ | Type | Description |
|---|---|---|
| limit | integer | 1 à 100 (défaut 25). |
| cursor | string | Valeur next_cursor de la page précédente. |
| updated_since | datetime | Ne renvoie que ce qui a changé depuis (ISO 8601), synchronisation incrémentale. |
| search | string | Recherche sur le nom. |
| type_agent | enum | interne ou sous_traitant. |
| status | string | Statut. |
curl "https://cleanplus.app/api/public/v1/agents" -H "Authorization: Bearer $CLEANPLUS_KEY"Champs renvoyés (dans data[])
| Champ | Type | Description |
|---|---|---|
| id | uuid | Identifiant. |
| first_name / last_name / job_title | string | Identité, poste. |
| email / phone | string | null | Coordonnées. |
| kind | enum | interne | sous_traitant. |
| qualifications[] | string[] | Habilitations. |
Devis
Devis avec statut, montants et lignes de chiffrage (coût de revient compris). La création importe un devis en brouillon : la référence est attribuée par CleanPlus, rien n'est envoyé au client, vous le relisez et l'envoyez depuis l'application. Combinez avec les webhooks quote.sent / quote.accepted pour vos relances ou votre CRM.
Lister
/quotesscope : quotes:readParamètres de requête
| Champ | Type | Description |
|---|---|---|
| limit | integer | 1 à 100 (défaut 25). |
| cursor | string | Valeur next_cursor de la page précédente. |
| updated_since | datetime | Ne renvoie que ce qui a changé depuis (ISO 8601), synchronisation incrémentale. |
| search | string | Recherche sur la référence. |
| client_id / site_id | uuid | Filtres. |
| status | enum | brouillon, envoye, accepte, refuse. |
curl "https://cleanplus.app/api/public/v1/quotes?status=accepte" -H "Authorization: Bearer $CLEANPLUS_KEY"Champs renvoyés (dans data[])
| Champ | Type | Description |
|---|---|---|
| id / reference / version | string | Identification. |
| client_id / site_id | uuid | Rattachement. |
| status | enum | brouillon | envoye | accepte | refuse. |
| subject | string | null | Objet. |
| total_ht / total_tax / total_ttc | number | Montants en euros. |
| issued_at / validity_days | date, integer | Émission, validité. |
| global_discount_pct | number | Remise globale en %. |
| lines | array | Lignes : designation, description, unit, quantity, unit_price_ht, vat_rate, discount_pct, unit_cost_ht, mission_template_id, total_ht. |
Lire un devis
/quotes/{id}scope : quotes:readRenvoie l'objet seul, ou 404 not_found s'il n'existe pas ou appartient à une autre organisation.
Créer un devis
/quotesscope : quotes:writeCorps JSON
| Champ | Type | Description |
|---|---|---|
| client_idrequis | uuid | Client de l'organisation (404 sinon). |
| site_id | uuid | Site de ce client. |
| subject | string ≤300 | Objet du devis. |
| validity_days | integer | 30 par défaut. |
| global_discount_pct | number | Remise globale en %. |
| notes | string ≤5000 | Notes. |
| lines[]requis | array (1 à 300) | designation (obligatoire), description, unit (m², heure, forfait…), quantity, unit_price_ht, vat_rate (20 par défaut), discount_pct, unit_cost_ht (coût de revient), frequency (cadence, ajoutée à la description), mission_template_id (mission du catalogue). |
curl -X POST https://cleanplus.app/api/public/v1/quotes -H "Authorization: Bearer $CLEANPLUS_KEY" \
-H "Content-Type: application/json" -d '{ "client_id": "<uuid>", "subject": "Entretien bureaux", "lines": [{ "designation": "Entretien quotidien", "unit": "m²", "quantity": 450, "unit_price_ht": 1.2, "unit_cost_ht": 0.85, "frequency": "5 passages / semaine" }] }'Réponse 201 avec l'objet créé. Déclenche le webhook quote.created.
Factures
Factures et avoirs. Utilisez updated_since et le webhook invoice.paid pour synchroniser votre comptabilité sans double saisie.
Lister
/invoicesscope : invoices:readParamètres de requête
| Champ | Type | Description |
|---|---|---|
| limit | integer | 1 à 100 (défaut 25). |
| cursor | string | Valeur next_cursor de la page précédente. |
| updated_since | datetime | Ne renvoie que ce qui a changé depuis (ISO 8601), synchronisation incrémentale. |
| search | string | Recherche sur le numéro. |
| client_id / site_id | uuid | Filtres. |
| status | enum | brouillon, finalisee, envoyee, payee, partiellement_payee, en_retard, annulee. |
curl "https://cleanplus.app/api/public/v1/invoices?status=payee&updated_since=2026-10-01T00:00:00Z" -H "Authorization: Bearer $CLEANPLUS_KEY"Champs renvoyés (dans data[])
| Champ | Type | Description |
|---|---|---|
| id / number / type | string | Identification (standard, situation, solde, avoir). |
| client_id / site_id / quote_id | uuid | null | Rattachements. |
| status | enum | Statut de paiement. |
| issued_at / due_at | date | Émission, échéance. |
| period | object | null | { start, end } pour les factures mensuelles. |
| customer | object | { name, siret, address } tels qu'imprimés sur la facture. |
| total_ht / total_tax / total_ttc | number | Montants en euros, après remise globale (négatifs pour un avoir). |
| tax_breakdown | array | Ventilation TVA : [{ rate, base_ht, tax }]. |
| amount_paid / amount_due | number | Encaissé et reste à payer TTC. |
| lines | array | Lignes : label, description, unit, quantity, unit_price_ht, discount_pct, vat_rate, total_ht. |
| reverse_charge | boolean | Autoliquidation de la TVA. |
Lire une facture
/invoices/{id}scope : invoices:readRenvoie l'objet seul, ou 404 not_found s'il n'existe pas ou appartient à une autre organisation.
Stock & matériel
Produits, consommables et matériel suivis en stock, avec quantité actuelle et seuil d'alerte. La quantité n'est jamais modifiée directement : chaque entrée ou sortie est un mouvement historisé, comme dans l'application (les alertes de stock bas restent envoyées).
Lister
/stockscope : stock:readParamètres de requête
| Champ | Type | Description |
|---|---|---|
| limit | integer | 1 à 100 (défaut 25). |
| cursor | string | Valeur next_cursor de la page précédente. |
| updated_since | datetime | Ne renvoie que ce qui a changé depuis (ISO 8601), synchronisation incrémentale. |
| search | string | Recherche sur le nom. |
| categorie | enum | produit, consommable ou materiel. |
| site_id | uuid | Articles affectés à un site. |
curl "https://cleanplus.app/api/public/v1/stock?categorie=consommable" -H "Authorization: Bearer $CLEANPLUS_KEY"Champs renvoyés (dans data[])
| Champ | Type | Description |
|---|---|---|
| id | uuid | Identifiant. |
| name / category | string | Nom, catégorie (produit | consommable | materiel). |
| quantity / alert_threshold | integer | Stock actuel et seuil d'alerte. |
| is_low | boolean | true si la quantité est au seuil ou en dessous. |
| site_id / location | uuid | string | null | Site d'affectation, emplacement. |
| notes | string | null | Notes. |
Lire un article en stock
/stock/{id}scope : stock:readRenvoie l'objet seul, ou 404 not_found s'il n'existe pas ou appartient à une autre organisation.
Historique des mouvements
/stock/movementsscope : stock:readParamètres de requête
| Champ | Type | Description |
|---|---|---|
| limit | integer | 1 à 100 (défaut 25). |
| cursor | string | Valeur next_cursor de la page précédente. |
| updated_since | datetime | Mouvements créés depuis (ISO 8601). |
| materiel_id / site_id / agent_id / intervention_id | uuid | Filtres. |
| reason | enum | utilise, casse_perdu, depose, reassort, inventaire, reception. |
| date_from / date_to | date | Période (AAAA-MM-JJ). |
| include_cancelled | boolean | true pour inclure les mouvements annulés. |
Champs renvoyés (dans data[])
| Champ | Type | Description |
|---|---|---|
| id / item_id | uuid | Mouvement, article concerné. |
| quantity | integer | Négatif = sortie, positif = entrée. |
| reason / comment | string | Motif et commentaire. |
| site_id / agent_id / intervention_id / purchase_order_id | uuid | null | Rattachements. |
| cancelled_at / created_at | datetime | null | Annulation, date. |
Enregistrer une entrée ou une sortie
/stock/movementsscope : stock:writeCorps JSON
| Champ | Type | Description |
|---|---|---|
| item_idrequis | uuid | Article de stock (GET /stock). |
| quantityrequis | integer ≠ 0 | Négatif pour une sortie, positif pour une entrée. |
| reasonrequis | enum | Sorties : utilise, casse_perdu, depose (négatif). Entrées : reassort, reception (positif). inventaire : correction dans les deux sens. |
| site_id / agent_id / intervention_id | uuid | Où, par qui, pour quelle intervention (404 s'ils n'appartiennent pas à votre organisation). |
| comment | string ≤1000 | Commentaire. |
curl -X POST https://cleanplus.app/api/public/v1/stock/movements -H "Authorization: Bearer $CLEANPLUS_KEY" \
-H "Content-Type: application/json" -H "Idempotency-Key: sortie-2026-11-16-42" \
-d '{ "item_id": "<uuid>", "quantity": -3, "reason": "utilise", "site_id": "<uuid>" }'Réponse 201 avec le mouvement et l'article à jour (item.quantity). En-tête Idempotency-Key conseillé : une même clé rejouée renvoie la première réponse sans compter le mouvement deux fois.
Produits
Catalogue des produits et articles de votre organisation (prix d'achat et de vente, TVA, fournisseur), avec le lien vers l'article suivi en stock.
Lister
/productsscope : stock:readParamètres de requête
| Champ | Type | Description |
|---|---|---|
| limit | integer | 1 à 100 (défaut 25). |
| cursor | string | Valeur next_cursor de la page précédente. |
| updated_since | datetime | Ne renvoie que ce qui a changé depuis (ISO 8601), synchronisation incrémentale. |
| search | string | Recherche sur le nom. |
| famille | string | Famille de produits. |
| materiel_id | uuid | Produits liés à un article de stock. |
| include_inactive | boolean | true pour inclure les produits désactivés. |
curl "https://cleanplus.app/api/public/v1/products?search=microfibre" -H "Authorization: Bearer $CLEANPLUS_KEY"Champs renvoyés (dans data[])
| Champ | Type | Description |
|---|---|---|
| id / reference | uuid / string | Identifiant, référence. |
| name / description / family | string | null | Désignation. |
| unit / packaging | string | null | Unité, conditionnement. |
| purchase_price_ht / price_ht / vat_rate | number | null | Prix d'achat, prix de vente HT, TVA. |
| supplier | string | null | Fournisseur. |
| stock_item_id | uuid | null | Article de stock lié (GET /stock/{id}). |
| active | boolean | Actif. |
Réservation en ligne
Module dédié aux tunnels de réservation (site vitrine, marketplace, simulateur) : créneaux réellement libres, création en un appel du client, du site et de l'intervention, puis suivi.
Créneaux libres
/availabilityscope : availability:readRenvoie les créneaux où au moins agents_count agents actifs sont libres pendant toute la durée demandée, dans les heures d'ouverture (8h–19h), en tenant compte des interventions déjà planifiées, des absences et d'un temps de trajet de 30 minutes entre deux interventions. Les créneaux passés sont exclus.
Paramètres de requête
| Champ | Type | Description |
|---|---|---|
| date_fromrequis | date | Premier jour recherché (AAAA-MM-JJ). |
| date_torequis | date | Dernier jour inclus. Plage de 31 jours maximum. |
| duration_minutesrequis | integer | Durée estimée de la prestation, de 15 à 720 minutes. |
| agents_count | integer | Nombre d'agents simultanés, de 1 à 10 (défaut 1). |
| lat / lng | number | Position du lieu d'intervention (enregistrée, non utilisée pour le tri en v1). |
curl "https://cleanplus.app/api/public/v1/availability?date_from=2026-10-12&date_to=2026-10-16&duration_minutes=120&agents_count=1" \
-H "Authorization: Bearer $CLEANPLUS_KEY"{
"timezone": "Europe/Paris",
"slots": [
{ "date": "2026-10-12", "start_time": "08:00", "end_time": "10:00", "available_agents_count": 3 },
{ "date": "2026-10-12", "start_time": "08:30", "end_time": "10:30", "available_agents_count": 3 }
]
}Catalogue des prestations
/servicesscope : availability:readListe les prestations actives de l'organisation avec leur prix unitaire HT, pour alimenter votre simulateur de tarif.
{
"services": [
{ "id": "…", "name": "Ménage complet", "description": "Toutes pièces", "category": "Particuliers",
"unit_price_ht": 32.5, "unit": "heure" }
]
}Créer une réservation
/bookingsscope : bookings:writeEn un seul appel : le client est retrouvé (par e-mail puis SIRET) ou créé, ses informations existantes ne sont jamais modifiées, le site est retrouvé par adresse ou créé, puis l'intervention est planifiée et les agents disponibles sont affectés automatiquement. Elle apparaît dans le planning avec le badge « Réservation en ligne ». Le créneau est revérifié au moment de la création.
En-têtes
| Champ | Type | Description |
|---|---|---|
| Idempotency-Keyrequis | string | Identifiant unique de la commande (≤ 200 caractères). |
Corps JSON
| Champ | Type | Description |
|---|---|---|
| external_ref | string ≤120 | Votre identifiant de commande, renvoyé dans chaque réponse et webhook. |
| customer.type | enum | particulier (défaut) ou professionnel. |
| customer.namerequis | string ≤200 | Nom de famille ou raison sociale. |
| customer.first_name | string ≤100 | Prénom. |
| customer.company_name | string ≤200 | Société (clients professionnels). |
| customer.emailrequis | email ≤255 | Sert à retrouver un client existant (jamais écrasé). |
| customer.phone | string ≤30 | Téléphone. |
| customer.siret | 14 chiffres | Rapprochement des clients professionnels. |
| site.addressrequis | string 3–300 | Adresse d'intervention. Un site existant à la même adresse est réutilisé. |
| site.name | string ≤200 | Nom du site (défaut : client + adresse). |
| site.postal_code / city | string | Code postal (≤10) et ville (≤100). |
| site.latitude / longitude | number | Coordonnées GPS. |
| site.access_instructions | string ≤2000 | Consignes d'accès visibles par les agents. |
| site.access_codes | string ≤500 | Digicode, boîte à clés… |
| site.surface | string ≤50 | Surface, ex. « 85 m² ». |
| site.premises_type | string ≤100 | Appartement, bureaux, local commercial… |
| slot.daterequis | date | Jour choisi (AAAA-MM-JJ, heure de Paris). |
| slot.start_timerequis | HH:MM | Heure de début, issue de /availability. |
| slot.duration_minutesrequis | integer | 15 à 720 minutes. Doit correspondre à la recherche de créneaux. |
| agents_count | integer | 1 à 10 (défaut 1). |
| service | string ≤200 | Prestation commandée (nom libre ou issu de /services). |
| notes | string ≤5000 | Options, précisions, résultat du simulateur. |
| attachments[] | array ≤20 | Photos/vidéos : { url (https, ≤2000), name? }. Ajoutées aux documents du site. |
curl -X POST https://cleanplus.app/api/public/v1/bookings \
-H "Authorization: Bearer $CLEANPLUS_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: CMD-1042" \
-d '{
"external_ref": "CMD-1042",
"customer": { "type": "particulier", "name": "Martin", "first_name": "Julie", "email": "julie@exemple.fr", "phone": "0601020304" },
"site": { "address": "12 rue de la Paix", "postal_code": "75002", "city": "Paris",
"access_instructions": "Digicode au portail, 3e étage", "surface": "85 m²" },
"slot": { "date": "2026-10-12", "start_time": "08:00", "duration_minutes": 120 },
"service": "Ménage complet",
"notes": "Options : vitres, four",
"attachments": [{ "url": "https://votre-stockage.fr/photo-salon.jpg", "name": "Salon" }]
}'{
"id": "5d0c6e0a-2c41-4a3e-9f1b-7f3b2d1e9a10",
"external_ref": "CMD-1042",
"source": "api",
"status": "planifie",
"date": "2026-10-12",
"start_time": "08:00",
"end_time": "10:00",
"service": "Ménage complet",
"notes": "Options : vitres, four",
"site": { "id": "…", "name": "Martin — 12 rue de la Paix", "address": "12 rue de la Paix, 75002 Paris",
"access_instructions": "Digicode au portail, 3e étage" },
"customer": { "id": "…", "name": "Martin", "first_name": "Julie",
"email": "julie@exemple.fr", "phone": "0601020304" },
"agents": [ { "id": "…", "role": "principal", "name": "Sofia Benali" } ],
"created_at": "2026-10-01T14:02:11.000Z",
"updated_at": "2026-10-01T14:02:11.000Z"
}Réponses possibles : 201 créée (aussi renvoyé à l'identique en cas de rejeu idempotent), 400, 401, 403, 409 slot_unavailable, 429.
Lire une réservation
/bookings/{id}scope : bookings:readRenvoie l'objet Booking à jour (statut, horaires, agents affectés).
curl https://cleanplus.app/api/public/v1/bookings/5d0c6e0a-2c41-4a3e-9f1b-7f3b2d1e9a10 -H "Authorization: Bearer $CLEANPLUS_KEY"Modifier ou reprogrammer
/bookings/{id}scope : bookings:writeTous les champs sont facultatifs ; seuls ceux envoyés sont modifiés. Impossible sur une réservation réalisée ou annulée (409 booking_locked).
Corps JSON
| Champ | Type | Description |
|---|---|---|
| slot | object | { date, start_time, duration_minutes }, reprogramme et réattribue les agents (409 si indisponible). |
| service | string ≤200 | Nouvelle prestation. |
| notes | string ≤5000 | Remplace les notes. |
| access_instructions | string ≤2000 | Met à jour les consignes du site. |
| access_codes | string ≤500 | Met à jour les codes d'accès. |
curl -X PATCH https://cleanplus.app/api/public/v1/bookings/{id} \
-H "Authorization: Bearer $CLEANPLUS_KEY" -H "Content-Type: application/json" \
-d '{ "slot": { "date": "2026-10-13", "start_time": "14:00", "duration_minutes": 120 } }'Annuler une réservation
/bookings/{id}/cancelscope : bookings:writePasse l'intervention au statut annule et libère les agents. Le motif est conservé dans les notes.
Corps JSON
| Champ | Type | Description |
|---|---|---|
| reason | string ≤1000 | Motif d'annulation. |
curl -X POST https://cleanplus.app/api/public/v1/bookings/{id}/cancel \
-H "Authorization: Bearer $CLEANPLUS_KEY" -H "Content-Type: application/json" \
-d '{ "reason": "Annulé par le client" }'Objet réservation
Booking
| Champ | Type | Description |
|---|---|---|
| idrequis | uuid | Identifiant CleanPlus de la réservation. |
| external_refrequis | string | null | Votre référence. |
| sourcerequis | api | app | Origine de la réservation. |
| statusrequis | enum | planifie, en_cours, termine ou annule. |
| daterequis | date | Jour d'intervention. |
| start_time / end_timerequis | HH:MM | Horaires, heure de Paris. |
| service / notesrequis | string | null | Prestation et notes. |
| siterequis | object | { id, name, address, access_instructions }. |
| customerrequis | object | { id, name, first_name, email, phone }. |
| agents[]requis | array | { id, role, name } des agents affectés. |
| created_at / updated_atrequis | datetime | Horodatages ISO 8601 (UTC). |
Slot
| Champ | Type | Description |
|---|---|---|
| daterequis | date | Jour. |
| start_time / end_timerequis | HH:MM | Début et fin, heure de Paris. |
| available_agents_countrequis | integer | Agents libres sur toute la durée. |
Service
| Champ | Type | Description |
|---|---|---|
| idrequis | uuid | Identifiant. |
| namerequis | string | Nom. |
| description / categoryrequis | string | null | Détails. |
| unit_price_htrequis | number | null | Prix unitaire HT en euros. |
| unitrequis | string | null | heure, mission, forfait… |
Error
{ "error": { "code": "validation_error", "message": "Données invalides",
"details": { "slot.start_time": ["Format HH:MM attendu"] } } }Webhooks
Les événements couvrent toute l'application : réservations en ligne, interventions du planning (créés depuis l'app ou la génération automatique), clients, sites, devis et factures. Choisissez les événements utiles pour chaque adresse.
Déclarez une ou plusieurs adresses https dans Paramètres → Développeurs & API et choisissez les événements. Ils sont émis pour les réservations en ligne, que le changement vienne de l'API ou du planning CleanPlus.
| Événement | Déclencheur |
|---|---|
| booking.created | Réservation créée (via l'API) |
| booking.updated | Consignes, prestation ou notes modifiées |
| booking.rescheduled | Date ou horaire déplacé (API ou planning CleanPlus) |
| booking.cancelled | Réservation annulée (API ou planning) |
| intervention.created | Intervention créée dans le planning CleanPlus |
| intervention.updated | Intervention déplacée ou modifiée dans l'app |
| intervention.completed | Intervention marquée réalisée par l'équipe |
| intervention.cancelled | Intervention annulée dans l'app |
| client.created | Nouveau client ou prospect |
| client.updated | Fiche client modifiée |
| client.converted | Prospect devenu client |
| site.created | Nouveau site |
| site.updated | Site modifié |
| quote.created | Devis créé |
| quote.sent | Devis envoyé au client |
| quote.accepted | Devis accepté / signé |
| quote.refused | Devis refusé |
| invoice.created | Facture créée |
| invoice.finalized | Facture finalisée |
| invoice.sent | Facture envoyée |
| invoice.paid | Facture payée |
| invoice.overdue | Facture en retard |
| invoice.cancelled | Facture annulée |
Requête envoyée
POST https://votre-site.fr/webhooks/cleanplus
Content-Type: application/json
User-Agent: CleanPlus-Webhooks/1.0
X-CleanPlus-Event: booking.rescheduled
X-CleanPlus-Delivery: 8f1c… ← identifiant unique, à utiliser pour dédoublonner
X-CleanPlus-Signature: t=1791712320,v1=5f2b…
{ "id": "8f1c…", "type": "booking.rescheduled", "created_at": "2026-10-10T09:12:00Z",
"data": { …objet Booking… } }Vérifier la signature
HMAC-SHA256 de `${t}.${corps brut}` avec le secret du webhook. Refusez les messages de plus de 5 minutes.
import crypto from "node:crypto";
export function verify(rawBody, header, secret) {
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return expected.length === v1.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}Relances et fiabilité
- Répondez par un code 2xx en moins de 10 secondes ; traitez ensuite de façon asynchrone.
- En cas d'échec : 5 nouvelles tentatives (1 min, 5 min, 30 min, 2 h, 6 h).
- Après 20 échecs consécutifs, l'adresse est désactivée et un administrateur est prévenu.
- Un même événement peut arriver deux fois : dédoublonnez avec
X-CleanPlus-Delivery. - L'ordre n'est pas garanti : comparez
data.updated_atavant d'écraser vos données.
IA, agents et MCP
CleanPlus est pensée pour être pilotée par des assistants IA. Deux façons de faire :
- Serveur MCP : ajoutez
https://cleanplus.app/mcpcomme connecteur dans Claude, ChatGPT, Cursor ou tout client MCP. L'utilisateur se connecte avec son compte CleanPlus (OAuth) ; l'assistant agit avec ses droits, limité à son organisation. Outils : lister clients, sites, agents, interventions, devis et factures ; trouver des créneaux libres ; créer un client ou un site ; changer le statut d'une intervention. - OpenAPI : donnez openapi.json à votre agent (GPT Actions, LangChain, n8n AI…) avec une clé limitée aux droits nécessaires. Les réponses utilisent des noms de champs anglais stables, un champ
objectet des erreurs typées faciles à interpréter. - Résumé pour les modèles : llms.txt.
Codes d'erreur
| HTTP | Code | Cause | Action |
|---|---|---|---|
| 400 | validation_error | Un champ est absent ou invalide (détail dans error.details) | Corrigez la requête, ne pas rejouer telle quelle |
| 400 | invalid_json | Le corps n'est pas un JSON valide | Vérifiez Content-Type et sérialisation |
| 400 | idempotency_key_required | En-tête Idempotency-Key absent sur POST /bookings | Ajoutez un identifiant unique de commande |
| 401 | invalid_api_key | Clé absente, erronée ou révoquée | Vérifiez la clé dans Paramètres → Développeurs & API |
| 403 | insufficient_scope | La clé n'a pas le droit requis | Générez une clé avec le bon droit |
| 404 | not_found | Réservation inexistante ou d'une autre organisation | Vérifiez l'identifiant |
| 409 | slot_unavailable | Le créneau a été pris entre-temps | Rechargez /availability et proposez un autre créneau |
| 409 | booking_locked | Réservation déjà réalisée ou annulée | Aucune modification possible |
| 429 | rate_limited | Plus de 120 requêtes par minute | Attendez puis réessayez avec un délai croissant |
| 500 | internal_error | Erreur inattendue côté CleanPlus | Réessayez ; contactez le support si cela persiste |
FAQ intégrateurs
Comment tester sans polluer le planning ?
Créez une réservation à une date lointaine avec un external_ref du type TEST-…, vérifiez les webhooks, puis annulez-la via /cancel. Vous pouvez aussi révoquer la clé de test ensuite.
Que faire en cas de 409 slot_unavailable ?
Le créneau a été pris entre l'affichage et la validation. Rechargez /availability et proposez immédiatement les créneaux voisins à votre client.
Le client existe déjà dans CleanPlus : est-il dupliqué ?
Non. Il est retrouvé par e-mail puis par SIRET, et ses informations ne sont jamais modifiées par l'API.
Comment transmettre photos et vidéos ?
Hébergez-les chez vous (URL https accessible) et passez-les dans attachments : elles sont rattachées aux documents du site, visibles par l'équipe.
Le prix est-il calculé par l'API ?
Non en v1 : votre simulateur calcule le prix (à partir de /services si besoin) et vous pouvez l'indiquer dans notes. Le paiement en ligne reste géré par votre tunnel.
Puis-je appeler l'API depuis le navigateur ?
Techniquement oui (CORS ouvert), mais la clé serait exposée. Passez par votre serveur ou une fonction serverless.
Versions
- v1.1 — 5 octobre 2026 : ressources clients, sites, interventions, agents, devis et factures ; pagination par curseur et synchronisation incrémentale ; 23 événements webhook métier ;
/me; X-Request-Id, en-têtes de débit ; journal des appels en direct ; outils MCP d'écriture. - v1.0, octobre 2026 : créneaux libres, prestations, réservations (création, lecture, modification, annulation), webhooks signés, OpenAPI 3.1.
- Toute évolution incompatible fera l'objet d'une nouvelle version (
/v2) ; la v1 restera disponible.
Une question technique ? Écrivez à contact@cleanplus.app.