API Operations: gestion des interventions, devis et réserves

API Operations: gestion des interventions, devis et réserves


OPERATIONS : ensemble des données liées au déroulé des interventions, des devis et des réserves.

Introduction

Définition des concepts

L'API Operations permet d'échanger sur les tâches opérationnelles d'interventions, de devis et de réserves, entre plusieurs entités distinctes telles que :
  • les gestionnaires de parc immobilier désirant synchroniser l'évolution des tickets d'intervention ou transmettre des demandes d'intervention,
  • les fournisseurs de services désirant recevoir les demandes d'intervention de leurs clients et partager l'évolution des tickets d'intervention ainsi que de transmettre des devis à leurs clients,
  • les bureau de contrôle désirant partager leurs analyses d'intervention avec le gestionnaire immobilier et émettre des réserves aux fournisseurs de services.
  • les bureaux d'études souhaitant accompagner leurs client dans la bonne gestion des contrats.
Envoi de données sur des éléments liés

En plus du simple partage de données d'interventions avec vos partenaires, IntentPlatform vous aide à contextualiser ces données d'interventions en les liant à des contrats et des éléments de patrimoine ainsi qu'à les référencer différemment selon qu'il s'agisse d'interventions, de réserves ou de devis :
1) il est possible de lier des opérations à des éléments de patrimoine et des contrats présents sur la plateforme établissant ainsi un historique complet des évènements sur un même élément
2) il est possible de lier des opérations entre elles afin de créer un historique complet des évènements sur un même élément de patrimoine
Objet
Description
interventions
L'objet intervention correspond à la synthèse d'un dossier d'intervention, mis à jour par les Logs successifs. Il prend pour origine une demande d'intervention ou un besoin client et correspond en général à un passage d'intervention : depuis la création de la demande à sa clôture.
reservation
L'objet reservation correspond à une réserve, c'est à dire à une synthèse d'état de fonctionnement d'un ou plusieurs éléments de patrimoine et annonce la nécessité d'intervention sur ces éléments.
quotation
L'objet quotation correspond à un devis. Il permet de donner un état détaillé des interventions à exécuter sur un élément de patrimoine et contient en autre une estimation fonctionnelle et de coût.
Le log d'évènement permet de mettre à jour les informations des opérations ci-dessus. Il matérialise le déroulement d'un évènement du dossier d'intervention.

Les méthodes

API Operations v2
Operations v2.0

Pour tout nouveau raccordement à intentPlaform, l'API Operations v2.0 devra être utilisée. Elle propose à minima toutes les exigences de la v1.0 tout en gérant plus de fonctionnalités et scénarios d'usages.
Action
Verbe
Route HTTP
Créer une intervention
POST
/api/operations/v2/interventions/logs
Créer un devis
POST
/api/operations/v2/quotations/logs
Créer une réserve
POST
/api/operations/v2/reservations/logs
Rechercher une opération par sa référence et son contrat
GET
/api/operations/v2/operations/{reference}
Rechercher une interventions suivant plusieurs paramètres
GET
/api/operations/v2/operations
Rechercher les opérations filles par la référence du parent et le contrat
GET
/api/operations/v2/operations/{reference}/children
Rechercher tous les évènements d'une opération et les opérations filles
GET
/api/operations/v2/operations/{reference}/events

Requêtes

Url de la requête

POST https://apisandbox.hubintent.com/api/operations/v2/interventions/logs
{
  "reference": "string",
  "description": "string",
  "contractReference": "string",
  "status": "open",
  "event": "requested",
  "eventDate": "string",
  "logDate": "string",
  "serviceCode": "string",
  "location": {
    "assetReference": "string",
    "address": {
      "way": "string",
      "city": "string",
      "zip": "string",
      "country": "string",
      "complement": "string"
    },
    "geo": {
      "longitude": 0,
      "latitude": 0
    }
  },
  "parentReference": "string",
  "workType": "preventive",
  "contacts": [
    "string"
  ],
  "technicalReason": "vandalism",
  "origin": "pm",
  "documentUrls": [
    "string"
  ],
  "tags": {
    "NouveauTagPerso":"string",
    "TagDeMonChoix":"string"
  },
  "equipmentWorkingOrder": "operational",
  "equipmentStatus": "new",
  "visitAttempt": 0,
  "replacingEquipment": "string",
  "warning": true,
  "warningComment": "string",
  "occupantSignature": "ok",
  "orderReference": "string",
  "orderDocReference": "string",
  "dischargeDocReference": "string",
  "additionalOrder": true,
  "additionalOrderComment": "string",
  "fileKey": "string",
  "criticalLevel": 0,
  "reminderLevel": 0,
  "reminderComment": "string",
  "suggestedProvisionalDate": "string",
  "suggestedTimeSlot": "string"
}

Réponse

Si le log d'intervention a correctement été créé, vous recevez une réponse 204.
Pour plus d'information

Chacune des requêtes (méthode, url, body et réponse) est détaillée dans l' API Reference . Vous y trouverez également des exemples.
Code erreur API

Si vous publiez des logs d'intervention avec une référence de contrat ou une référence d'asset non connue sur intentPlatform pour votre entité, vos données seront rejetées. Vous recevrez une erreur 400.

Description des champs & status

Description des champs des opérations

Champs
Description
Exemple
reference (required)
La référence de l'opération, pour le compte émettant la requête
chauffage-394
description
La description (commentaire) de l'évènement
Le locataire se plaint d'une panne de chauffage...
contractReference (required)
Le contrat auquel est liée l'opération...
multi_2019_FR
status (required)
L'état d'avancement de l'opération
open
event (required)
L'évènement actuel de l'opération
planned
eventDate (required)
La date de l'étape...
2016-10-14T14:00:00.000Z
logDate (required)
La date à laquelle le client a enregistré l'évènement en interne
2019-01-14T21:00:00.000Z
serviceCode (required)
Le code de la prestation réalisée pendant l'intervention
heater_curative
location (required)
Lieu de la prestation
via assetReference ou address
assetReference
La référence de l'élément de patrimoine concerné par l'opération
chaudiere-3992
address
Adresse de l'élément concerné par l'intervention
address/way
La rue de l'élément de patrimoine...
5 Rue du bonheur
address/city
La ville...
LILLE
address/zip
Code postal
59000
address/country
Le pays de l'intervention
France
address/complement
Complément d'information...
Hall B
geo
Coordonnées géographiques...
geo/longitude
Degré de longitude...
3.057256
geo/latitude
Degré de latitude...
50.62925
parentReference
La référence de l'opération liée à l'opération...
DEV_9872
workType (required)
Le type de prestation demandée. Parmi: preventive, operational, corrective, adaptive, setup, renovation, energetic_coaching, diagnosis (diagnostic de l'état de santé d'un équipement), regulatory, work_order, none
preventive
contacts
Les informations d'un contact lié à l'opération
Au format vCard
technicalReason
La raison technique, après diagnostic post intervention. Parmi: vandalism, power_failure, false_alert, abnormal_use, external_reason, time_worn, other_pm, technical_failure, other_sp
vandalism
origin
L'origine de la demande. Parmi: pm, sp, other
pm
documentUrls
l'url du document
equipmentWorkingOrder
L'état de fonctionnement. Parmi: operational, not_operational
not_operational
equipmentStatus
Le statut plus précis de l'équipement. Parmi: new, ok, bad_condition, to_be_replaced, warning
ok
visitAttempt
Le nombre de tentatives de passage
4
replacingEquipment
La référence de l'équipement de remplacement
chaudiere-4829
warning
Si une alerte est émise
true
warningComment
La description de l'alerte émise
la machine n'est pas réparable
occupantSignature
Si l'occupant a validé et signé l'intervention. Parmi: ok, occupant_denial, na
ok
orderDocReference
La référence d'un document complémentaire
doc-230
dischargeDocReference
La référence de quitus du locataire ou du gestionnaire
doc-2139
additionalOrder
Si une commande complémentaire a été effectuée
true
additionalOrderComment
Le commentaire sur la commande complémentaire
il y a besoin de commander une nouvelle chaudière
fileKey
La clé identifiant le fichier utilisé pour importer les logs
file-dj4h
criticalLevel
Le niveau de criticité de la demande. -1=NULL, 0=non urgent, 1=urgent faible, 2=urgent fort, 3=stratégique, 4=prioritaire faible, 5=prioritaire fort
4
reminderLevel
Le niveau de relance de la demande. De 1 à 5
3
reminderComment
Commentaire sur la relance
l'hiver arrive, il est nécessaire de réparer cette chaudière
suggestedProvisionalDate
La date limite souhaitée de réalisation
2016-10-21T12:00:00Z
suggestedTimeSlot
Les périodes durant lesquelles le travail devrait être effectué
De préférence le matin
tags/NouveauTagPerso
Tag pour créer un champ de votre choix
Satisfaction: 5 étoiles
Ajouter les champs de votre choix
IntentPlatform offre la possibilité de créer ses propres champs s'ils n'existent pas dans le listing ci-dessus.
Pour créer un nouveau champ, il suffit de rajouter des tags avec un couple clé/valeur. Dans le body de la requête, ajouter :
"tags": {
  "NouveauTagPerso":"valeur1",
  "TagDeMonChoix":"valeur2"
}
Champ Location
Si vous renseignez le champ assetReference, il n'est pas nécessaire d'indiquer les champs address. Le lien avec l'assetReference permettra d'avoir l'adresse, la ville, le code postal et la géolocalisation de l'élément.

Définition des statuts d'avancement des opérations

Intervention

status
events
signification
open
requested
intervention demandée, à l'initiative du gestionnaire
acknowledged
le prestataire "accuse réception" de la demande
due
intervention à échéance (date anniversaire)
planned
planification de l'intervention
client_planned
planification à l'initiative du locataire/occupant
commented
commentaire sur l'intervention
pending
replanned
replanification succédant à une intervention ou une tentative
on_site
date d'arrivée du technicien sur site
start
date de début d'intervention
end
date de fin d'intervention
commented
commentaire sur l'intervention
hold
occupant_absent
remise à plus tard pour absence de l'occupant
occupant_denial
remise à plus tard pour refus de l'occupant
technical_issue
remise à plus tard à cause d'un problème technique
safety_issue
remise à plus tard à cause d'un problème de sécurité
quote_request
demande/proposition de devis hors forfait
missing_item
pièce manquante pour effectuer la réparation
extension_request
demande d'extension du périmètre
postponed
remise à plus tard à l'initiative du prestataire
temporary_repair
remise à plus tard suite à réparation temporaire
partial_repair
remise à plus tard suite à réparation partielle
commented
commentaire sur l'intervention
closed
done
clôture "normale" de l'intervention par le prestataire
temporary_repair
clôture avec notification de réparation temporaire
partial_repair
clôture avec notification de réparation partielle
formal_notice
clôture avec notification formelle (LAR, etc.)
occupant_absent
Clôture pour occupant absent
occupant_denial
Clôture pour refus de l'occupant
solved
acceptation de l'intervention par le demandeur
dismissed
refus de l'intervention par le demandeur
denied
canceled
refus sans motif
unable
refus pour impossibilité d'intervenir
non_contractual
refus parce que hors contrat

Quotation

status
events
signification
open
requested
Le client demande un devis pour une intervention.
proposed
Le prestataire soumet sa proposition de devis.
acknowledged
Le système du client confirme la bonne réception.
temporary_accepted
Validation temporaire
precisions_requested
Le client demande une modification ou des précisions.
updated
Le prestataire soumet une nouvelle version de son devis.
closed
accepted
Check Mark Button Succès ! Le devis est accepté par le client.
rejected
Cross Mark Le devis a été refusé par le client.
canceled
Cross Mark Le client a annulé sa demande de devis.
canceled_order
Cross Mark Le client a annulé la commande

Reservation

status
events
signification
open
requested
Réserve émise
acknowledged
Accusé de réception de la réserve
precisions_requested
Précisions demandées
updated
Réserve mise à jour
closed
solved
Réserve traitée
dismissed
Réserve refusée

Best practises

Fonctionnement des dates et heures

Format de date ISO-8601
Toutes les dates doivent être au format ISO-8601 avec le fuseau horaire UTC (Z).
Exemple : 2016-10-14T14:00:00.000Z
IntentPlatform stocke les dates en UTC mais peut les restituer dans le fuseau horaire CET/Paris selon la configuration du projet. Cependant, lors de l'envoi de données via l'API, les dates doivent toujours être en UTC (Z).
A propos de l'usage des champs date
Trois champs de date importants :
  • creationDate : Date de création de l'objet en base de données
  • eventDate : Date de l'événement/de l'étape de l'opération
  • logDate : Date à laquelle l'événement a été enregistré par le client
Ces trois dates peuvent être différentes. Par exemple, une intervention planifiée pour le 15 octobre peut être enregistrée le 10 octobre.
eventDate et logDate : planification d'une intervention
Lors de la planification d'une intervention, les dates jouent un rôle crucial :
  • eventDate : La date/heure planifiée de l'intervention = 2018-11-22T10:00:00.000Z
  • logDate : La date/heure de l'enregistrement de cette planification = 2018-11-19T15:30:00.000Z
Dans cet exemple, le gestionnaire a enregistré le 19 novembre à 15h30 la planification d'une intervention pour le 22 novembre à 10h00.

Contacts liés à une intervention

Voir  Contact - Vcard  du chapitre API Assets.

1 élément de patrimoine par intervention

Un objet (intervention, quotation, reservation) ne peut concerner qu'un et unique élément asset.
Si lors d'une intervention vous intervenez sur plusieurs équipements, il faudra créer un nouvel objet pour chaque équipement visité.

Exemple de déroulé d'une intervention préventive avec LAR

Voici un exemple complet du déroulé d'une intervention préventive avec une notification formelle (LAR) au locataire.
    Planification d'une intervention préventive
    Locataire absent lors du 1er passage
    Replannification de l'intervention
    Clôture de l'intervention
    Envoi d'une LAR au locataire

Planification d'une intervention préventive

URL
Title
URL
 https://apisandbox.hubintent.com/api/operations/v2/logs 
verbe HTTP
POST
{
  "reference": "PREV_2019",
  "description": "Visite de prévention chauffage annuelle",
  "contractReference": "multi_2019_FR",
  "status": "open",
  "event": "planned",
  "eventDate": "2018-11-22T10:00:00.000Z",
  "logDate": "2018-11-19T15:30:00.000Z",
  "serviceCode": "heater_preventive",
  "assetReference": "chaudiere-3992",
  "workType": "preventive"
}

Locataire absent lors du 1er passage

URL
Title
URL
 https://apisandbox.hubintent.com/api/operations/v2/logs 
verbe HTTP
POST
{
  "reference": "PREV_2019",
  "contractReference": "multi_2019_FR",
  "status": "hold",
  "event": "occupant_absent",
  "eventDate": "2018-11-22T10:30:00.000Z",
  "logDate": "2018-11-22T11:00:00.000Z",
  "serviceCode": "heater_preventive",
  "assetReference": "chaudiere-3992",
  "workType": "preventive"
}

Replannification de l'intervention

URL
Title
URL
 https://apisandbox.hubintent.com/api/operations/v2/logs 
verbe HTTP
POST
{
  "reference": "PREV_2019",
  "contractReference": "multi_2019_FR",
  "status": "pending",
  "event": "replanned",
  "eventDate": "2018-11-29T14:00:00.000Z",
  "logDate": "2018-11-22T14:30:00.000Z",
  "serviceCode": "heater_preventive",
  "assetReference": "chaudiere-3992",
  "workType": "preventive"
}

Clôture de l'intervention

URL
Title
URL
 https://apisandbox.hubintent.com/api/operations/v2/logs 
verbe HTTP
POST
{
  "reference": "PREV_2019",
  "contractReference": "multi_2019_FR",
  "status": "closed",
  "event": "occupant_absent",
  "eventDate": "2018-11-29T14:00:00.000Z",
  "logDate": "2018-11-29T15:30:00.000Z",
  "serviceCode": "heater_preventive",
  "assetReference": "chaudiere-3992",
  "workType": "preventive",
  "equipmentWorkingOrder": "operational"
}

Envoi d'une LAR au locataire

URL
Title
URL
 https://apisandbox.hubintent.com/api/operations/v2/logs 
verbe HTTP
POST
{
  "reference": "PREV_2019",
  "contractReference": "multi_2019_FR",
  "status": "closed",
  "event": "formal_notice",
  "eventDate": "2018-11-29T16:00:00.000Z",
  "logDate": "2018-11-29T16:15:00.000Z",
  "serviceCode": "heater_preventive",
  "assetReference": "chaudiere-3992",
  "workType": "preventive",
  "dischargeDocReference": "LAR_2019_001"
}