Ce document décrit les spécificités d'intégration pour les partenaires réalisant des prestations d'hygiène et de 3D (Dératisation, Désinsectisation, Désinfection). Il complète et s'appuie sur Interventions .
1. Identité du raccordement
Périmètre métier : 3D (Dératisation, Désinsectisation, Désinfection des parties communes et privatives).
Niveau de rattachement patrimoine :
Par défaut : Rattachement au Bâtiment ou à la Partie Commune (ex: Local Vide-ordures, Cave, Parking).
Par exception : Rattachement au Logement/Local privatif si la campagne ou le traitement correctif cible un appartement spécifique.
2. Scénarios & Règles Métier
Règle de l'unicité du ticket (Multi-passages)
Les prestations 3D (qu'elles soient préventives ou correctives) imposent très souvent plusieurs passages physiques sur site pour être validées (relevés de boîtes d'appâtage, rupture du cycle de reproduction des insectes, etc.).
Règle d'or : Tous les passages nécessaires à la réalisation d'une même prestation doivent être regroupés au sein d'un unique objet intervention. Vous ne devez pas créer un nouveau ticket (nouvelle référence) pour chaque passage technique.
Pourquoi cette règle est-elle cruciale ? Cette approche permet d'assurer le meilleur suivi possible du début à la fin de l'exécution de la prestation. Lorsqu'un client (le gestionnaire) vous demande d'intervenir pour une dératisation, il a besoin de retrouver l'intégralité des passages, des actions menées et des éléments de preuve directement rattachés à sa demande initiale. Centraliser ces données sur un seul ticket évite d'éparpiller l'information sur plusieurs tickets d'interventions distincts et garantit une traçabilité parfaite.
Cas du Préventif (Interventions récurrentes vs passages multiples)
La distinction entre le nombre d'interventions préventives contractuelles et le nombre de passages nécessaires à la réalisation d'une seule et même prestation est essentielle :
Interventions préventives distinctes : Si votre contrat-cadre prévoit la réalisation de 2 interventions préventives par an pour la dératisation (ex: une campagne au printemps et une à l'automne), vous devez créer 2 interventions distinctes (2 tickets séparés) sur intentPlatform.
Passages multiples pour une prestation préventive : Si pour une prestation préventive (ex: une campagne semestrielle de dératisation), le protocole technique exige 3 passages physiques pour réaliser l'intégralité de la prestation :
Vous devez créer une intervention sur intentPlatform qui contiendra les 3 passages.
Vous indiquez chacun des 3 passages successifs avec un cycle Début/Fin de visite : PENDING / start puis PENDING / end.
Chaque fin de visite intermédiaire est matérialisée par un statut HOLD / postponed (facultatif), et l'annonce de la future date de passage par un statut PENDING / replanned.
Ce n'est qu'une fois la prestation entièrement réalisée (à l'issue du dernier passage) que vous passez le ticket au statut final CLOSED / done.
Cas du Correctif (Traitement curatif)
Pour un traitement curatif (ex: éradication de blattes ou de punaises de lit), le protocole technique peut imposer 2 à 3 passages pour briser le cycle de ponte. Le cycle de vie du ticket sur intentPlatform doit respecter scrupuleusement l'enchaînement suivant :
Passage 1 (Traitement d'attaque) :
Début/Fin de visite PENDING / start puis PENDING / end.
Enregistrement de l'interruption HOLD / postponed avec une description précisant l'application du produit d'attaque et la nécessité d'un second passage.
Passage 2 (10 à 15 jours plus tard - Rupture du cycle d'éclosion) :
Replanification/Annonce du passage PENDING / replanned.
Début/Fin de visite PENDING / start puis PENDING / end.
Si un contrôle final est requis HOLD / postponed de nouveau. Sinon CLOSED / done.
Passage 3 (Optionnel - Contrôle de sécurité et validation d'extinction) :
Replanification/Annonce du passage PENDING / replanned.
Même cinématique que le passage 2, suivi de la clôture définitive CLOSED / done avec rapport factuel en description.
3. Dictionnaire des Données "Métier"
Standardisation du serviceCode
Afin de permettre aux gestionnaires de suivre efficacement le respect de leurs contrats-cadres, vous devez standardiser vos codes de services en respectant les structures ci-dessous.
4. Exemple de Payload JSON (Fin du 1er passage correctif)
Cet exemple montre l'envoi du log à l'issue de l'acte technique du Passage 1 (Traitement d'attaque) pour des cafards (désinsectisation curative). Ce log acte la fin de la présence du technicien sur site lors de cette première étape (PENDING / end).
POST operations/v2/interventions/logs
{
"reference":"INTER-3D-2026-0089",
"contractReference":"CONTRAT-3D-NORD",
"status":"pending",
"event":"end",
"eventDate":"2026-07-07T14:30:00",
"logDate":"2026-07-07T14:32:00",
"serviceCode":"depannage-desinsectisation",
"location":{
"assetReference":"LOCAL_VO_BAT_B"
},
"workType":"corrective",
"criticalLevel":3,
"description":"Passage 1 effectué : traitement d'attaque par gel rémanent (cafards) dans les gaines techniques du local VO et de la cage d'escalier B. Fortes traces d'infestation. Étape terminée. Un second passage sera planifié sous 12 jours pour briser le cycle d'éclosion.",
"tags":{
"TypeNuisible":"Rampants"
}
}
5. Critères de validation
Use case
Résultat attendu
Unicité de l'intervention préventive avec plusieurs passages
Pour une prestation de prévention programmée (ex: campagne de dératisation semestrielle) exigeant plusieurs passages physiques pour être totalement exécutée, une seule et unique référence d'intervention doit être transmise sur intentPlatform.
Unicité de l'intervention corrective avec plusieurs passages
Pour un traitement d'attaque ou curatif (ex: éradication de nuisibles sur signalement) imposant un protocole technique de 2 à 3 visites successives, l'intégralité des étapes terrain doit être consolidée sous une seule et unique référence d'intervention sur intentPlatform.
Ordonnancement des passages
Les cycles de visite doivent s'enchaîner chronologiquement de manière rigoureuse dans l'API :
- Chaque visite terrain doit être ouverte par un log de début PENDING / start et fermée par un log de fin PENDING / end.
- L'annonce ou la replanification de l'étape suivante doit impérativement utiliser le statut intermédiaire PENDING / replanned (succédant si nécessaire à un log de pause HOLD / postponed).
Clôture de la prestation
Une fois la prestation technique complètement achevée (dernier passage réalisé avec succès), l'intervention est basculée sur son statut final de fin de cycle CLOSED / done. Le champ description associé à ce log doit obligatoirement contenir un résumé factuel et explicite des opérations réalisées.
Document quitus d'intervention à la fin de la prestation
Lors de l'envoi du log de clôture final, un document justificatif (rapport ou quitus d'intervention au format PDF) doit être lié à l'intervention via l'API Documents. Ce fichier doit porter les tags de classification obligatoires : intent_documentType et intent_documentFamily
Annulation d'une intervention
En cas de suppression ou d'annulation de la prestation / intervention le connecteur doit envoyer un log de statut final DENIED / canceled.