API Contracts: gestion des partages de données et contrats de services

Base des contrats de fourniture de services et de partage de données entre les gestionnaires et leurs partenaires.


Concepts

L'API CONTRACTS vous permet de :
  • gérer un contrat avec un partenaire,
  • gérer des prestations de services et des engagements de services,

Un CONTRAT va vous permettre :
  • d'autoriser votre partenaire à publier des données sur votre patrimoine, par exemple ses reporting d'intervention, ses documents.
  • lui partager des données comme votre référentiel de patrimoine, vos diagnostics amiante.
  • d'accéder au reporting d'intentPlatform sous forme de tableau de bord et d'indicateurs pour piloter au mieux vos contrats de façon agrégée ou unitaire.

Contenu d'un contrat

Description des champs

Champ
Description
Exemple
reference
La référence de votre contrat
INTENT-1029-01
label
Le titre du contrat
Ascenseur Agence Nord
description
La description du contrat
Contrat de maintenance et travaux des ascenseurs de l'agence nord
contacts
Le contact référent du contrat
format vCard
thirdParty_id
L'identifiant de l'entité avec qui vous souhaitez créer le contrat
012235-44534-ffdd-efcbadcf
thirdParty_reference
La référence du contrat de votre partenaire
PROVIDER_2018AX
thirdParty_contacts
Le contact référent de votre partenaire
format vCard
stardDate
Date de début du contrat
2017-01-01
endDate
Date de fin du contrat
2021-12-31
deactivationDate
Date de fin de partage des éléments et flux de données
2022-01-10

Différence entre endDate et deactivationDate

La endDate représente la date contractuelle de fin de contrat entre vous et votre partenaire.
La deactivationDate représente la date à laquelle les éléments ne seront plus partagés à votre partenaire et donc la date où il ne pourra plus publier de données sur le contrat et donc les éléments qui y sont partagés.
Cette différence vous permet de continuer à recevoir des données même si le contrat est terminé.
Par exemple, elle vous permet d'accorder à votre votre partenaire un délai pour qu'il vous transmette ses dernières données.

thirdParty_id
Pour récupérer cette information, il vous faut contacter le service client d'Intent Technologies ( serviceclient@intent.tech ).

Il est également possible de rajouter des informations supplémentaires au contrat sous forme de tag libre. Par exemple :
"tags":{"Ref logiciel": "ref-029","Facturation":"semestrielle"}


Méthodes

Action
Verbe
Route HTTP
Créer un contrat
POST
/api/contracts/v1/contracts
Récupérer ma liste de contrat
GET
/api/contracts/v1/contracts
Rechercher un contrat précis par sa référence
GET
/api/contracts/v1/contracts/{reference}
Modifier un contrat
PATCH
/api/contracts/v1/contracts/{reference}
Désactiver un contrat
PATCH
/api/contracts/v1/contracts/{reference}
Modification d'un contrat

Via les APIs d'IntentPlatform, il n'est pas possible de modifier les références, ni les dates de début et fin du contrat.

Les champs possibles à modifier sont :
1) label
2) tags libres
3) description
4)contacts

La désactivation d'un contrat s'effectue par une requête
URL
/api/contracts/v1/contracts/{reference}
verbe HTTP
PATCH
{
"deactivationDate": "2022-01-10"
}


Prestations de service

Il est possible d'associer à un contrat des prestations de services et leur attribuer plusieurs engagements de service (délais - SLA).

Par exemple, pour un contrat d'ascenseur, nous pouvons avoir :
  • Prestation de service = dépannage pour personne bloquée
  • Engagement de service n°1 "Temps pour intervenir" = 2h
  • Engagement de service n°2 "Temps pour remise en service" = 6h

Pour créer une prestation de service, nous pouvons la segmenter en 3 étapes :
    Création de la prestation
    Association des engagements de service (délais - SLA) à une prestation
    Attribution à un périmètre géographique

Indicateurs - Dashboard

Si vous souhaitez bénéficier des services de dashboard d'intentPlatform sur les demandes et tickets d'intervention, il est obligatoire de créer des prestations de services et des engagements de services.


Description des champs

Création de la prestation

Champ
Description
Exemple
code
votre référence de prestation
asc_personne_bloquee
thirdPartyCode
la référence de prestation de votre partenaire
urgent_Cur_1A
label
Le titre de la prestation de service
Dépannage pour personne bloquée
description
La description de la prestation de service
Intervention de dépannage pour désincarcération d'une personne dans un ascenseur.
workType
Le type de la prestation de service
corrective
fixedRate
Tarif de la prestation
227.90
Transcodification des codes de prestations

IntentPlatform gère la transcodification des codes de prestations entre vous et votre partenaire. Par exemple pour une prestation de "dépannage pour personne bloquée" :
votre code de prestation : asc_personne_bloquee
celui de votre partenaire : urgent_Cur_1A


Association des engagements de service (SLA) à une prestation

Champ
Description
Exemple
periodicity (value / unit)
Récurrence de la prestation. Utile pour les prestations préventives.
6 / week
estimatedInterventionDuration (value / unit)
Durée estimative de l'intervention
2 / hour
maxTimeToIntervention (value / unit)
Temps maximum pour intervenir
24 / hour
maxTimeToRecovery (value / unit)
Temps maximum pour remise en service
2 / day
Calcul des engagements de services

maxTimeToIntervention : Temps entre signalement (statut = open) et début d'intervention (statut = pending)
maxTimeToRecovery : Temps entre début d'intervention (statut = pending) et fin d'intervention (statut = closed)


Attribution à un périmètre géographique

Champ
Description
Exemple
intent_type
Le type de bâti ou équipement
Appartement
category
La catégorie du bâti ou de l'équipement
Module
Ces informations sont récupérables avec l'API Assets en réalisant une requête de type GET.

Méthodes

Action
Verbe
Route HTTP
Créer une prestation de service et un engagement de service
POST
/api/contracts/v1/contracts/{reference}/servicecodes
Modifier une prestation et/ou un engagement de service
PATCH
/api/contracts/v1/contracts/{reference}/servicecodes/{serviceCodeId}
Supprimer une prestation de service
DELETE
/api/contracts/v1/contracts/{reference}/servicecodes/{serviceCodeId}
Modification d'une prestation de service

Il n'est pas possible de modifier les références de prestations code et thirdPartyCode

Les champs possibles à modifier sont :
label
description
workType
fixedRate
estimatedInterventionDuration (value/unit)
periodicity (value/unit)
maxTimeToIntervention (value/unit)
maxTimeToRecovery (value/unit)
assetPerimeters (intent_type)

Utilisation du contrat

Le contrat va être utile pour s'échanger des données :
  • Gestionnaire : Partager mon patrimoine à mon prestataire
  • Prestataire de service : Publier des données (interventions, objets connectés, etc.) sur le patrimoine de mon client.
Nous allons donc retrouver dans plusieurs API le champ contract_reference qui va permettre de correctement réaliser le partage de données entre 2 entités sur la période définie.
Mauvaise référence de contrat

Si vous tentez de publier des données avec une référence de contrat non connue dans intentPlatform, vos données seront rejetées. Vous recevrez un message d'erreur 500.
La référence contrat n'étant pas un champ obligatoire, si vous n'indiquez aucune référence de contrat, vos données seront acceptées mais pas forcément partagées avec votre client.


Partage de patrimoine

API Assets
Le partage de données de type patrimoine se fait avec l'API Assets. Il faut indiquer la référence du contrat en question dans le body de la requête.
Une fois votre contrat créé, vous pouvez partager des éléments de patrimoine avec votre partenaire. Pour réaliser ce partage, il faut utiliser l'API Assets et réaliser une requête PATCH.
Quelles informations d'un asset sont partagées ?
Lorsque vous partagez un asset sur un contrat, vous partagez toutes les informations qui lui sont attribuées, c'est-à-dire tous ses intent_tags (référence, adresse, géolocalisation) ainsi que tous les tags libres que vous lui avez ajoutés, par exemple la marque et le modèle d'un équipement ou encore le type de logement et sa classe énergétique pour un building.



Méthodes

Action
Verbe
Route HTTP
Partager un asset via un contrat
PATCH
/api/assets/v1/assets/{reference}
Les données sont partagées à votre partenaire jusqu'à la deactivationDate indiquée dans le contrat.


Partage de données Interventions et Objets connectés


Lorsque vous publiez des données de type Interventions ou Objets connectés, vous pouvez renseigner le champ : contractReference.
Il va permettre de correctement réaliser le partage de la donnée avec votre client ou fournisseur de service.
On retrouve le champ contractReference dans l'API Operation pour la publication de tickets et demande d'intervention et l'API Data pour la création de flux de données.
Néanmoins, si vous publiez des données sur un élément de patrimoine qui vous a été partagé et sans indiquer de contractReference, la donnée sera quand même partagée mais pas qualifiée dans sa totalité.