Aller au contenu principal

    Documentation développeurs · v1

    API CleanPlus : connectez tous vos outils à votre logiciel de nettoyage

    Une API ouverte pour relier CleanPlus à votre CRM, votre comptabilité, votre outil de paie, vos tableaux de bord, votre site de réservation ou vos assistants IA : clients et prospects, sites, planning, agents, devis et factures, avec des webhooks signés pour être prévenu de chaque changement en temps réel. API REST JSON, clé par organisation, spécification OpenAPI 3.1 importable dans Postman, Insomnia, Make, Zapier, n8n ou un générateur de SDK.

    REST + JSON · OpenAPI
    11 droits par clé
    23 webhooks signés
    Prête pour l'IA (MCP)
    Sommaire

    Cas d'usage

    Démarrage rapide en 5 minutes

    1. 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).
    2. Stockez-la côté serveur dans une variable d'environnement CLEANPLUS_KEY.
    3. 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.
    4. Déclarez un webhook https dans le même écran et cliquez « Tester » pour valider la réception.
    bash
    curl https://cleanplus.app/api/public/v1/me -H "Authorization: Bearer $CLEANPLUS_KEY"

    Exemple, parcours type d'un tunnel de réservation :

    flux
    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 client

    Authentification & 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.

    http
    Authorization: Bearer cp_live_xxxxxxxxxxxxxxxxxxxxxxxx
    DroitAutorise
    availability:readLire les créneaux libres et le catalogue des prestations
    bookings:writeCréer, modifier, reprogrammer et annuler des réservations
    bookings:readConsulter une réservation
    clients:readLister et lire les clients et prospects
    clients:writeCréer et modifier des clients
    sites:readLister et lire les sites
    sites:writeCréer et modifier des sites
    interventions:readLire tout le planning (interventions de l'app et de l'API)
    agents:readLister les agents actifs
    quotes:readLister et lire les devis
    quotes:writeImporter un devis en brouillon avec ses lignes de chiffrage
    invoices:readLister et lire les factures
    stock:readLire le stock (quantités, seuils), l'historique des mouvements et le catalogue produits
    stock:writeEnregistrer une entrée ou une sortie de stock (jamais de modification directe de la quantité)
    interventions:write_instructionsAjouter, 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/json pour POST et PATCH.
    • Fuseau horaire : dates AAAA-MM-JJ et heures HH:MM exprimées à l'heure de Paris (Europe/Paris) ; horodatages techniques en ISO 8601 UTC.
    • Idempotence : POST /bookings exige Idempotency-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 avec Retry-After.
    • Pagination : les listes renvoient { object: "list", data, has_more, next_cursor } ; passez cursor=next_cursor pour 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) et CleanPlus-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

    Informations sur la clé

    Organisation, droits et limite de débit

    GET/me

    Répond pour toute clé valide : utile pour vérifier une installation ou laisser un agent IA découvrir ce qu'il peut faire.

    json
    { "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

    GET/clientsscope : clients:read

    Paramètres de requête

    ChampTypeDescription
    limitinteger1 à 100 (défaut 25).
    cursorstringValeur next_cursor de la page précédente.
    updated_sincedatetimeNe renvoie que ce qui a changé depuis (ISO 8601), synchronisation incrémentale.
    searchstringRecherche sur le nom.
    typeenumparticulier ou professionnel.
    est_prospectbooleantrue = prospects uniquement.
    bash
    curl "https://cleanplus.app/api/public/v1/clients?est_prospect=true&limit=50" -H "Authorization: Bearer $CLEANPLUS_KEY"

    Champs renvoyés (dans data[])

    ChampTypeDescription
    iduuidIdentifiant.
    typeenumparticulier | professionnel.
    name / first_name / company_namestringIdentité.
    email / phone / siretstring | nullCoordonnées.
    address / postal_code / citystring | nullAdresse.
    is_prospectbooleanProspect ou client.
    status / notesstring | nullStatut, notes internes.
    created_at / updated_atdatetimeHorodatages.

    Lire un client

    GET/clients/{id}scope : clients:read

    Renvoie l'objet seul, ou 404 not_found s'il n'existe pas ou appartient à une autre organisation.

    Créer un client

    POST/clientsscope : clients:write

    Corps JSON

    ChampTypeDescription
    namerequisstring ≤200Nom ou raison sociale.
    typeenumprofessionnel (défaut) ou particulier.
    first_name / company_namestringPrénom, société.
    emailemailSert au contrôle des doublons.
    phonestring ≤30Téléphone.
    siret14 chiffresContrôle des doublons.
    address / postal_code / citystringAdresse.
    is_prospectbooleanfalse par défaut.
    notesstring ≤5000Notes.
    bash
    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

    PATCH/clients/{id}scope : clients:write

    Mise à 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

    GET/sitesscope : sites:read

    Paramètres de requête

    ChampTypeDescription
    limitinteger1 à 100 (défaut 25).
    cursorstringValeur next_cursor de la page précédente.
    updated_sincedatetimeNe renvoie que ce qui a changé depuis (ISO 8601), synchronisation incrémentale.
    searchstringRecherche sur le nom.
    client_iduuidSites d'un client.
    bash
    curl "https://cleanplus.app/api/public/v1/sites?client_id=<uuid>" -H "Authorization: Bearer $CLEANPLUS_KEY"

    Champs renvoyés (dans data[])

    ChampTypeDescription
    id / client_iduuidIdentifiants.
    name / addressstringNom, adresse.
    latitude / longitudenumber | nullGPS (pointage géolocalisé).
    surface / premises_typestring | nullSurface, type de locaux.
    access_instructionsstring | nullConsignes d'accès.
    contactobject{ name, phone, email } du contact sur place.

    Lire un site

    GET/sites/{id}scope : sites:read

    Renvoie l'objet seul, ou 404 not_found s'il n'existe pas ou appartient à une autre organisation.

    Créer un site

    POST/sitesscope : sites:write

    Corps JSON

    ChampTypeDescription
    client_idrequisuuidClient propriétaire.
    namerequisstring ≤200Nom du site.
    addressrequisstring 3–300Adresse.
    latitude / longitudenumberGPS.
    access_instructions / access_codesstringAccès, digicode.
    surface / premises_typestringSurface, type.
    contact_name / contact_phone / contact_emailstringContact sur place.
    notesstringNotes.
    bash
    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

    PATCH/sites/{id}scope : sites:write

    Mise à 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

    GET/interventionsscope : interventions:read

    Paramètres de requête

    ChampTypeDescription
    limitinteger1 à 100 (défaut 25).
    cursorstringValeur next_cursor de la page précédente.
    updated_sincedatetimeNe renvoie que ce qui a changé depuis (ISO 8601), synchronisation incrémentale.
    date_from / date_todatePériode (AAAA-MM-JJ).
    site_id / agent_iduuidFiltrer par site ou agent principal.
    statusenumplanifie, en_cours, termine, annule.
    sourceenumapp ou api.
    bash
    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[])

    ChampTypeDescription
    id / site_id / agent_iduuidIdentifiants.
    date / start_time / end_timedate, HH:MMHeure de Paris.
    statusenumplanifie | en_cours | termine | annule.
    service / instructionsstring | nullPrestation, consignes saisies dans l'application (notes : alias historique).
    instruction_linesarrayLignes de consignes écrites par vos logiciels : [{ key, text }].
    source / external_refstringOrigine et votre référence.

    Lire une intervention

    GET/interventions/{id}scope : interventions:read

    Renvoie l'objet seul, ou 404 not_found s'il n'existe pas ou appartient à une autre organisation.

    Ajouter ou remplacer une ligne de consignes

    PUT/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

    ChampTypeDescription
    textrequisstring ≤500, une ligneTexte affiché à l'agent.
    bash
    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

    DELETE/interventions/{id}/instructions/lines/{key}scope : interventions:write_instructions

    Retire 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

    GET/agentsscope : agents:read

    Paramètres de requête

    ChampTypeDescription
    limitinteger1 à 100 (défaut 25).
    cursorstringValeur next_cursor de la page précédente.
    updated_sincedatetimeNe renvoie que ce qui a changé depuis (ISO 8601), synchronisation incrémentale.
    searchstringRecherche sur le nom.
    type_agentenuminterne ou sous_traitant.
    statusstringStatut.
    bash
    curl "https://cleanplus.app/api/public/v1/agents" -H "Authorization: Bearer $CLEANPLUS_KEY"

    Champs renvoyés (dans data[])

    ChampTypeDescription
    iduuidIdentifiant.
    first_name / last_name / job_titlestringIdentité, poste.
    email / phonestring | nullCoordonnées.
    kindenuminterne | 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

    GET/quotesscope : quotes:read

    Paramètres de requête

    ChampTypeDescription
    limitinteger1 à 100 (défaut 25).
    cursorstringValeur next_cursor de la page précédente.
    updated_sincedatetimeNe renvoie que ce qui a changé depuis (ISO 8601), synchronisation incrémentale.
    searchstringRecherche sur la référence.
    client_id / site_iduuidFiltres.
    statusenumbrouillon, envoye, accepte, refuse.
    bash
    curl "https://cleanplus.app/api/public/v1/quotes?status=accepte" -H "Authorization: Bearer $CLEANPLUS_KEY"

    Champs renvoyés (dans data[])

    ChampTypeDescription
    id / reference / versionstringIdentification.
    client_id / site_iduuidRattachement.
    statusenumbrouillon | envoye | accepte | refuse.
    subjectstring | nullObjet.
    total_ht / total_tax / total_ttcnumberMontants en euros.
    issued_at / validity_daysdate, integerÉmission, validité.
    global_discount_pctnumberRemise globale en %.
    linesarrayLignes : designation, description, unit, quantity, unit_price_ht, vat_rate, discount_pct, unit_cost_ht, mission_template_id, total_ht.

    Lire un devis

    GET/quotes/{id}scope : quotes:read

    Renvoie l'objet seul, ou 404 not_found s'il n'existe pas ou appartient à une autre organisation.

    Créer un devis

    POST/quotesscope : quotes:write

    Corps JSON

    ChampTypeDescription
    client_idrequisuuidClient de l'organisation (404 sinon).
    site_iduuidSite de ce client.
    subjectstring ≤300Objet du devis.
    validity_daysinteger30 par défaut.
    global_discount_pctnumberRemise globale en %.
    notesstring ≤5000Notes.
    lines[]requisarray (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).
    bash
    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

    GET/invoicesscope : invoices:read

    Paramètres de requête

    ChampTypeDescription
    limitinteger1 à 100 (défaut 25).
    cursorstringValeur next_cursor de la page précédente.
    updated_sincedatetimeNe renvoie que ce qui a changé depuis (ISO 8601), synchronisation incrémentale.
    searchstringRecherche sur le numéro.
    client_id / site_iduuidFiltres.
    statusenumbrouillon, finalisee, envoyee, payee, partiellement_payee, en_retard, annulee.
    bash
    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[])

    ChampTypeDescription
    id / number / typestringIdentification (standard, situation, solde, avoir).
    client_id / site_id / quote_iduuid | nullRattachements.
    statusenumStatut de paiement.
    issued_at / due_atdateÉmission, échéance.
    periodobject | null{ start, end } pour les factures mensuelles.
    customerobject{ name, siret, address } tels qu'imprimés sur la facture.
    total_ht / total_tax / total_ttcnumberMontants en euros, après remise globale (négatifs pour un avoir).
    tax_breakdownarrayVentilation TVA : [{ rate, base_ht, tax }].
    amount_paid / amount_duenumberEncaissé et reste à payer TTC.
    linesarrayLignes : label, description, unit, quantity, unit_price_ht, discount_pct, vat_rate, total_ht.
    reverse_chargebooleanAutoliquidation de la TVA.

    Lire une facture

    GET/invoices/{id}scope : invoices:read

    Renvoie 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

    GET/stockscope : stock:read

    Paramètres de requête

    ChampTypeDescription
    limitinteger1 à 100 (défaut 25).
    cursorstringValeur next_cursor de la page précédente.
    updated_sincedatetimeNe renvoie que ce qui a changé depuis (ISO 8601), synchronisation incrémentale.
    searchstringRecherche sur le nom.
    categorieenumproduit, consommable ou materiel.
    site_iduuidArticles affectés à un site.
    bash
    curl "https://cleanplus.app/api/public/v1/stock?categorie=consommable" -H "Authorization: Bearer $CLEANPLUS_KEY"

    Champs renvoyés (dans data[])

    ChampTypeDescription
    iduuidIdentifiant.
    name / categorystringNom, catégorie (produit | consommable | materiel).
    quantity / alert_thresholdintegerStock actuel et seuil d'alerte.
    is_lowbooleantrue si la quantité est au seuil ou en dessous.
    site_id / locationuuid | string | nullSite d'affectation, emplacement.
    notesstring | nullNotes.

    Lire un article en stock

    GET/stock/{id}scope : stock:read

    Renvoie l'objet seul, ou 404 not_found s'il n'existe pas ou appartient à une autre organisation.

    Historique des mouvements

    GET/stock/movementsscope : stock:read

    Paramètres de requête

    ChampTypeDescription
    limitinteger1 à 100 (défaut 25).
    cursorstringValeur next_cursor de la page précédente.
    updated_sincedatetimeMouvements créés depuis (ISO 8601).
    materiel_id / site_id / agent_id / intervention_iduuidFiltres.
    reasonenumutilise, casse_perdu, depose, reassort, inventaire, reception.
    date_from / date_todatePériode (AAAA-MM-JJ).
    include_cancelledbooleantrue pour inclure les mouvements annulés.

    Champs renvoyés (dans data[])

    ChampTypeDescription
    id / item_iduuidMouvement, article concerné.
    quantityintegerNégatif = sortie, positif = entrée.
    reason / commentstringMotif et commentaire.
    site_id / agent_id / intervention_id / purchase_order_iduuid | nullRattachements.
    cancelled_at / created_atdatetime | nullAnnulation, date.

    Enregistrer une entrée ou une sortie

    POST/stock/movementsscope : stock:write

    Corps JSON

    ChampTypeDescription
    item_idrequisuuidArticle de stock (GET /stock).
    quantityrequisinteger ≠ 0Négatif pour une sortie, positif pour une entrée.
    reasonrequisenumSorties : utilise, casse_perdu, depose (négatif). Entrées : reassort, reception (positif). inventaire : correction dans les deux sens.
    site_id / agent_id / intervention_iduuidOù, par qui, pour quelle intervention (404 s'ils n'appartiennent pas à votre organisation).
    commentstring ≤1000Commentaire.
    bash
    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

    GET/productsscope : stock:read

    Paramètres de requête

    ChampTypeDescription
    limitinteger1 à 100 (défaut 25).
    cursorstringValeur next_cursor de la page précédente.
    updated_sincedatetimeNe renvoie que ce qui a changé depuis (ISO 8601), synchronisation incrémentale.
    searchstringRecherche sur le nom.
    famillestringFamille de produits.
    materiel_iduuidProduits liés à un article de stock.
    include_inactivebooleantrue pour inclure les produits désactivés.
    bash
    curl "https://cleanplus.app/api/public/v1/products?search=microfibre" -H "Authorization: Bearer $CLEANPLUS_KEY"

    Champs renvoyés (dans data[])

    ChampTypeDescription
    id / referenceuuid / stringIdentifiant, référence.
    name / description / familystring | nullDésignation.
    unit / packagingstring | nullUnité, conditionnement.
    purchase_price_ht / price_ht / vat_ratenumber | nullPrix d'achat, prix de vente HT, TVA.
    supplierstring | nullFournisseur.
    stock_item_iduuid | nullArticle de stock lié (GET /stock/{id}).
    activebooleanActif.

    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

    GET/availabilityscope : availability:read

    Renvoie 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

    ChampTypeDescription
    date_fromrequisdatePremier jour recherché (AAAA-MM-JJ).
    date_torequisdateDernier jour inclus. Plage de 31 jours maximum.
    duration_minutesrequisintegerDurée estimée de la prestation, de 15 à 720 minutes.
    agents_countintegerNombre d'agents simultanés, de 1 à 10 (défaut 1).
    lat / lngnumberPosition 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"
    200 OK
    {
      "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

    GET/servicesscope : availability:read

    Liste les prestations actives de l'organisation avec leur prix unitaire HT, pour alimenter votre simulateur de tarif.

    200 OK
    {
      "services": [
        { "id": "…", "name": "Ménage complet", "description": "Toutes pièces", "category": "Particuliers",
          "unit_price_ht": 32.5, "unit": "heure" }
      ]
    }

    Créer une réservation

    POST/bookingsscope : bookings:write

    En 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

    ChampTypeDescription
    Idempotency-KeyrequisstringIdentifiant unique de la commande (≤ 200 caractères).

    Corps JSON

    ChampTypeDescription
    external_refstring ≤120Votre identifiant de commande, renvoyé dans chaque réponse et webhook.
    customer.typeenumparticulier (défaut) ou professionnel.
    customer.namerequisstring ≤200Nom de famille ou raison sociale.
    customer.first_namestring ≤100Prénom.
    customer.company_namestring ≤200Société (clients professionnels).
    customer.emailrequisemail ≤255Sert à retrouver un client existant (jamais écrasé).
    customer.phonestring ≤30Téléphone.
    customer.siret14 chiffresRapprochement des clients professionnels.
    site.addressrequisstring 3–300Adresse d'intervention. Un site existant à la même adresse est réutilisé.
    site.namestring ≤200Nom du site (défaut : client + adresse).
    site.postal_code / citystringCode postal (≤10) et ville (≤100).
    site.latitude / longitudenumberCoordonnées GPS.
    site.access_instructionsstring ≤2000Consignes d'accès visibles par les agents.
    site.access_codesstring ≤500Digicode, boîte à clés…
    site.surfacestring ≤50Surface, ex. « 85 m² ».
    site.premises_typestring ≤100Appartement, bureaux, local commercial…
    slot.daterequisdateJour choisi (AAAA-MM-JJ, heure de Paris).
    slot.start_timerequisHH:MMHeure de début, issue de /availability.
    slot.duration_minutesrequisinteger15 à 720 minutes. Doit correspondre à la recherche de créneaux.
    agents_countinteger1 à 10 (défaut 1).
    servicestring ≤200Prestation commandée (nom libre ou issu de /services).
    notesstring ≤5000Options, précisions, résultat du simulateur.
    attachments[]array ≤20Photos/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" }]
      }'
    201 Created
    {
      "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

    GET/bookings/{id}scope : bookings:read

    Renvoie l'objet Booking à jour (statut, horaires, agents affectés).

    bash
    curl https://cleanplus.app/api/public/v1/bookings/5d0c6e0a-2c41-4a3e-9f1b-7f3b2d1e9a10 -H "Authorization: Bearer $CLEANPLUS_KEY"

    Modifier ou reprogrammer

    PATCH/bookings/{id}scope : bookings:write

    Tous 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

    ChampTypeDescription
    slotobject{ date, start_time, duration_minutes }, reprogramme et réattribue les agents (409 si indisponible).
    servicestring ≤200Nouvelle prestation.
    notesstring ≤5000Remplace les notes.
    access_instructionsstring ≤2000Met à jour les consignes du site.
    access_codesstring ≤500Met à jour les codes d'accès.
    bash
    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

    POST/bookings/{id}/cancelscope : bookings:write

    Passe l'intervention au statut annule et libère les agents. Le motif est conservé dans les notes.

    Corps JSON

    ChampTypeDescription
    reasonstring ≤1000Motif d'annulation.
    bash
    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

    ChampTypeDescription
    idrequisuuidIdentifiant CleanPlus de la réservation.
    external_refrequisstring | nullVotre référence.
    sourcerequisapi | appOrigine de la réservation.
    statusrequisenumplanifie, en_cours, termine ou annule.
    daterequisdateJour d'intervention.
    start_time / end_timerequisHH:MMHoraires, heure de Paris.
    service / notesrequisstring | nullPrestation et notes.
    siterequisobject{ id, name, address, access_instructions }.
    customerrequisobject{ id, name, first_name, email, phone }.
    agents[]requisarray{ id, role, name } des agents affectés.
    created_at / updated_atrequisdatetimeHorodatages ISO 8601 (UTC).

    Slot

    ChampTypeDescription
    daterequisdateJour.
    start_time / end_timerequisHH:MMDébut et fin, heure de Paris.
    available_agents_countrequisintegerAgents libres sur toute la durée.

    Service

    ChampTypeDescription
    idrequisuuidIdentifiant.
    namerequisstringNom.
    description / categoryrequisstring | nullDétails.
    unit_price_htrequisnumber | nullPrix unitaire HT en euros.
    unitrequisstring | nullheure, mission, forfait…

    Error

    json
    { "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énementDéclencheur
    booking.createdRéservation créée (via l'API)
    booking.updatedConsignes, prestation ou notes modifiées
    booking.rescheduledDate ou horaire déplacé (API ou planning CleanPlus)
    booking.cancelledRéservation annulée (API ou planning)
    intervention.createdIntervention créée dans le planning CleanPlus
    intervention.updatedIntervention déplacée ou modifiée dans l'app
    intervention.completedIntervention marquée réalisée par l'équipe
    intervention.cancelledIntervention annulée dans l'app
    client.createdNouveau client ou prospect
    client.updatedFiche client modifiée
    client.convertedProspect devenu client
    site.createdNouveau site
    site.updatedSite modifié
    quote.createdDevis créé
    quote.sentDevis envoyé au client
    quote.acceptedDevis accepté / signé
    quote.refusedDevis refusé
    invoice.createdFacture créée
    invoice.finalizedFacture finalisée
    invoice.sentFacture envoyée
    invoice.paidFacture payée
    invoice.overdueFacture en retard
    invoice.cancelledFacture annulée

    Requête envoyée

    http
    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_at avant 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/mcp comme 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 object et des erreurs typées faciles à interpréter.
    • Résumé pour les modèles : llms.txt.

    Codes d'erreur

    HTTPCodeCauseAction
    400validation_errorUn champ est absent ou invalide (détail dans error.details)Corrigez la requête, ne pas rejouer telle quelle
    400invalid_jsonLe corps n'est pas un JSON valideVérifiez Content-Type et sérialisation
    400idempotency_key_requiredEn-tête Idempotency-Key absent sur POST /bookingsAjoutez un identifiant unique de commande
    401invalid_api_keyClé absente, erronée ou révoquéeVérifiez la clé dans Paramètres → Développeurs & API
    403insufficient_scopeLa clé n'a pas le droit requisGénérez une clé avec le bon droit
    404not_foundRéservation inexistante ou d'une autre organisationVérifiez l'identifiant
    409slot_unavailableLe créneau a été pris entre-tempsRechargez /availability et proposez un autre créneau
    409booking_lockedRéservation déjà réalisée ou annuléeAucune modification possible
    429rate_limitedPlus de 120 requêtes par minuteAttendez puis réessayez avec un délai croissant
    500internal_errorErreur inattendue côté CleanPlusRé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.

    Prêt à digitaliser votre entreprise de propreté ?

    Démo gratuite avec un expert. Mise en route en moins de 10 minutes.