API Assets: Gestion des actifs immobiliers




Organisation hiérarchique

L'organisation hiérarchique permet la structuration du patrimoine selon une logique hiérarchique, c'est à dire un environnement dans lequel chaque élément dépend du précédent et commande le suivant. Par exemple, un élément de patrimoine, tel qu'un logement peut-être contenu dans un bâtiment, lui-même contenu dans une résidence, elle-même contenue dans un programme immobilier de résidences, lui-même contenu dans un groupe, lui-même contenu dans une agence de regroupement.


L'organisation hiérarchique est entièrement paramétrable pour prendre en compte les spécificités de chaque structure de patrimoine (Habitat, Tertiaire, Bâtiment communaux, Industrie, etc.), que ce soit pour le nom des niveaux que pour le nombre de niveaux de patrimoine.
La modélisation d'un patrimoine hiérarchique se constitue de deux grandes familles :
  • Les Bâtis : matérialisent les différents composants, bâti ou organisationnelle, de la structure d’un bâtiment. Un bâti peut désigner un élément simple (un logement, une pièce, une salle de réunion, une cafétéria, etc.) ou un ensemble plus large (un complexe sportif, une résidence, un îlot, etc.).
  • Les Equipements : matérialisent un appareil ou un système technique (ex: ascenseur, chaudière, système de ventilation, etc.). Un équipement peut desservir aucun, un ou plusieurs bâtis.


Bâti

Un bâti de patrimoine hiérarchique est décrit par 3 familles d'attributs :
  • 1. Les path
  • 2. Les intent tags
  • 3. Les tags libres


Path

Les PATH permettent de déclarer les niveaux hiérarchiques et ensuite de rattacher hiérarchiquement les éléments entre eux. Pour chaque niveau hiérarchique, il y a 2 attributs :
Path
Type
Description
Exemple
code*
string
Le code du bâti
INTENT-0001-01-1903
label
string
Le nom du bâti
Résidence des oiseaux bleus
(*) : champ obligatoire

Le label servira de nom d’affichage dans les apps web et mobile d'intentPlatform.
Si un élément hiérarchique n’a aucun libellé d’indiqué, IntentPlatform indiquera sa référence code sur les interfaces web et mobile.

Chaque attribut d'un couple de path (code / label) a un nom. Il vous permet de nommer vos niveaux hiérarchiques à la fois en terme de référence (code) qu'en terme d'affichage (label).
Par exemple : Je souhaite déclarer une niveau hiérarchique "Résidence" dont les références se nomment "ESI_RES"Le code se nommera "ESI_RES" et prendra la valeur "INTENT-0001-01-1903".Le label se nommera "Résidence" et prendra la valeur "Résidence des oiseaux bleus"


Intent tags

Les INTENT TAGS sont des champs automatiquement reconnus par intentPlatform.
Intent tag
Type
Description
Exemple
intent_reference*
string
La référence du bâti. Elle doit être unique pour une entité.
LGT20110506
intent_type
string
Le type du bâti
Logement
intent_commissioning_date
string (ISO 8601)
La date de mise en service du bâti
1995-09-28
intent_decommissioning_date
string (ISO 8601)
La date de décommissionnement du bâti
2018-03-12
intent_address_way
string
Le N° et la rue du bâti
12 Rue du paradis
intent_address_city
string
La ville du bâti
Lille
intent_address_zip
string
Le code postal du bâti
59000
intent_address_complement
string
Le complément d'adresse du bâti
Résidence des oiseaux
intent_longitude
number
La longitude du bâti
50.6307293
intent_latitude
number
La latitude du bâti
3.0007823
intent_surface
number
La surface du bâti
73
intent_contacts
Vcard (or string)
Le contact associé au bâti
intent_scancode
string
Le code retourné par le scan d’un QRCode
intent_brand
string
Marque de l'équipement
Nespresso
intent_model
string
Modèle de l'équipement
Carbon RL800
(*) : champ obligatoire

Le champ intent_type est libre. Vous pouvez indiquer le type du bâti de votre choix (Bureau, Partie commune, Local Technique, etc.). Cependant, un certain nombre de intent_type sont reconnus par IntentPlatform :
intent_type
Description
dwelling
Un lot privatif, un appartement, dont les données sont destinées à l'occupant.
collective_residential_building
Un immeuble, un bâtiment collectif dont l'usage est partagé.

Tags libres

Les TAGS LIBRES sont des informations complémentaires que vous souhaitez apporter à vos bâtis. Il vous est possible d’en créer autant que vous le voulez.Les tags libres sont constitués d'un couple clé / valeur. La clé correspond au titre du tag libre.
Exemple 1 : vous souhaitez indiquer le niveau d'amiante dans vos logements pour le partager à vos prestataires :
  • clé = niveau_amiante
  • valeur = liste A, liste B, liste C

Caractères interdits

Les codes ne doivent pas contenir de "/"
Les labels ne doivent pas contenir de "/"
Les clés des tags ne peuvent pas contenir des "."

Méthodes

Action
Verbe
Route HTTP
Créer un élément de patrimoine bâti
POST
/api/assets
Modifier un élément de patrimoine bâti
PATCH
/api/assets/{reference}
Rechercher un élément de patrimoine bâti
GET
/api/assets/{reference}
Lister les assets de mon patrimoine
GET
/api/assets
Récupérer tous les évènements qui se sont déroulés sur un asset
GET
/api/assets/{reference}/events
Lors de vos requêtes, il est possible de placer plusieurs paramètres (l'asset parent, les assets liés, le titre, le type de l'asset, etc.) pour affiner vos recherches dans votre patrimoine


Equipements

Un Equipement est décrit par 3 familles d'attributs :
  • 1. Les liens d'installation et usages
  • 2. Les intent tags
  • 3. Les tags libres


Liens d'installation et usages

Ces informations sont utilisées uniquement pour les équipements. Elles sont facultatives pour la création d'un équipement.
  • installationReference permet d’indiquer sur quel bâti l’équipement est installé.
  • usageLinksReferences permet d’indiquer le ou les bâtis qui sont concernés par l’équipement en question.
Les valeurs prises en compte par ces 2 champs sont les intent_reference des bâtis.
Par exemple pour une Chaufferie collective installée au sous-sol du Bâtiment 1 et qui dessert les Bâtiments 1, 2, 3, 4.
  • installationReference : INTENT-BAT1
  • usageLinksReferences : INTENT-BAT1, INTENT-BAT2, INTENT-BAT3, INTENT-BAT4.


Intent tags

Les INTENT TAGS sont des champs automatiquement reconnus par intentPlatform.
Se référer au tableau ci-dessus : Bâti / Intent tags

Tags libres

Les TAGS LIBRES vous permettent d'ajouter des caractéristiques supplémentaires à vos assets. Les tags libres sont constitués d'un couple clé / valeur. La clé correspond au titre du tag libre.
Exemple 1 : vous souhaitez indiquer le type de vos ascenseurs et leur niveau de vétusté :
  • clé 1 = type_ascenseur
  • valeur 1 = hydraulique, mécanique
  • clé 2 = vétusté
  • valeur 2 = 1, 2, 3, 4, 5
Caractères interdits

Les références et labels ne doivent pas contenir de "/"
Les clés des tags ne peuvent pas contenir des "."


Méthodes

Action
Verbe
Route HTTP
Créer un élément de patrimoine bâti
POST
/api/assets
Modifier un élément de patrimoine bâti
PATCH
/api/assets/{reference}
Rechercher un élément de patrimoine bâti
GET
/api/assets/{reference}
Lister les assets de mon patrimoine
GET
/api/assets
Récupérer tous les évènements qui se sont déroulés sur un asset
GET
/api/assets/{reference}/events


Contacts - Vcard

Il est possible d'associer un contact à n'importe quel asset (bâti et équipement). Il faut utiliser le champ intent_contacts.
Le champ intent_contacts supporte le format Vcard.
L'ensemble des champs de la Vcard sont stockés et disponible via l'API. En terme, d'affichage web et mobile, IntentPlatform affiche les champs suivants :Première ligne :
  • n.prefix
  • n
  • fn
  • roleDeuxième ligne :
  • email
  • tel
Par exemple, pour une Vcard associée à un bâtiment :
BEGIN:VCARDVERSION:3FN;CHARSET=UTF-8:Pierre DUPONTN;CHARSET=UTF-8:DUPONT ;PierreTEL;TYPE=WORK,VOICE:0734220902TEL;TYPE=HOME,VOICE:0685874445ADR;TYPE=WORK:165 Avenue de Bretagne;59000;LILLE;FranceROLE;CHARSET=UTF-8:GardienEMAIL;CHARSET=UTF-8;TYPE=WORK,INTERNET: p.dupont@internet.fr END:VCARD
L'affichage est :

Il vous est possible d'associer plusieurs contacts pour un même élément de patrimoine.
PATCH https://apisandbox.hubintent.com/api/assets/v1/assets/{reference}
{
	"tags":[
		{
			"operation":"add",
			"name":"intent_contacts",
			"value":"BEGIN:VCARD\n\nVERSION:3\r\nFN;CHARSET=UTF-8:Pierre DUPONT\r\nN;CHARSET=UTF-8:DUPONT ;Pierre\r\nTEL;TYPE=WORK,VOICE:0734220902\r\nTEL;TYPE=HOME,VOICE:0685874445\r\nADR;TYPE=WORK:165 Avenue de Bretagne;59000;LILLE;France\r\nROLE;CHARSET=UTF-8:Gardien\r\nEMAIL;CHARSET=UTF-8;TYPE=WORK,INTERNET:p.dupont@internet.fr\r\nEND:VCARD\r\nBEGIN:VCARD\n\nVERSION:3\r\nFN;CHARSET=UTF-8:Marie FRANCE\r\nN;CHARSET=UTF-8:FRANCE ;Marie\r\nTEL;TYPE=WORK,VOICE:0709243902\r\nTEL;TYPE=HOME,VOICE:0385874498\r\nADR;TYPE=WORK:165 Avenue du Bretagne;59000;LILLE;France\r\nROLE;CHARSET=UTF-8:Locataire 2\r\nEMAIL;CHARSET=UTF-8;TYPE=WORK,INTERNET:mfrance@internet.fr\r\nEND:VCARD"
		}
	]
}