Les API de transcodification
Chaque organisation utilise des référentiels et des nomenclatures pour désigner et identifier un déchet ou un matériel. Cela s'applique bien évidemment à d'autres informations.
Les codes utilisés ne sont pas toujours normalisés. Ce qui rend la communication entre les applications parfois difficile. Les API de transcodification ont pour objectif de faciliter les échanges avec le SI Trinov.
La transcodification s'appliquera à des ressources exposés par Trinov, comme la ressource Waste, Equipment, CollectionPoint dont la description est disponible dans la documentation API Waste Collections.
Authentification
Toutes les authentifications aux API Trinov se font via le protocole OIDC.
curl --location '<https://keycloak-staging.trinov.com/realms/demo/protocol/openid-connect/token>' \\
--header 'Content-Type: application/x-www-form-urlencoded' \\
--data-urlencode 'client_id=demo' \\
--data-urlencode 'client_secret=xxxxxxxxxxxxxxxx' \\
--data-urlencode 'grant_type=client_credentials' \\
--data-urlencode 'scope=openid profile'Le jeton obtenu contient des informations sur le compte de service, notamment l'organisation à laquelle il est rattaché. Cette information est enregistrée sous l'attribut "tenant".
L'information "tenant" est utilisée par les API de transcodifications pour n'exposer et ne permettre l'administration que des données qui lui sont rattachées. Par exemple, un prestataire A ne pourra ni voir, ni modifier ni supprimer des données de transcodification d'un prestataire B.
Liste des éléments nécessaire pour identifier une transcodification
Nous rappelons ci-dessous les éléments importants qui permettre d'identifier une transcodification.
Champ technique dans l'API | Description |
|---|---|
producerOrganization | Organisation productrice de déchet. Il s'agit du producteur de déchet. |
externalOrganization | Il s'agit de toute organisation qui s'interface avec Trinov. Il s'agit des prestataires de déchets, notamment les transporteurs ou les centres de traitement. |
field | Il représente l'élement transcodé. Le déchet ou le matériel sont par exemple des éléments à transcoder. Le champ field est une liste prédéfinie de valeur. Les valeurs disponibles sont consultables dans la documentation de l'API. |
producerValue | Valeur de l'élément pour l'organisation productrice |
externalValue | Valeur de l'élément pour l'organisation externe |
direction | Sens de la transcodification. Trois valeurs possibles : BOTH, IN ou OUT.
|
Modélisation des ressources dans les API de Transcodification
La transcodification est représentée par 2 ressources étroitement liée. La combinaison de ces 2 ressources permet de retrouver toutes les informations citées dans le chapitre précédent.
La ressource TranscodificationHeader regroupe les informations principales
| Attribut | Type | Description |
|---|---|---|
| id | numérique | identifiant unique de l'objet |
| producerOrganization | chaine de caractère | organisation producrtice, client de Trinov |
| externalOrganization | chaine de caractère | organisation externe (prestataire) |
| field | énumération (WASTE,EQUIPMENT,COLLECITON_POINT) | élément transcodé |
| direction | énumération (BOTH,IN,OUT) | sens de la transcodification |
| keyStructure | objet KeyStructure | décrit le moyen de composer les identifiants à partir des objets métiers Trinov selon le type Field. Nous décrirons plus loin le fonctionnement de la structure de clé. |
| active | booléen | indique si la transcodification de l'élément est activé ou désactivé |
| replace | booléen | si replace est à true, on remplace les valeurs de l'objet métier d'origine par le résultat de la transcodification, sinon on fusionne les informations. Ceci sera détaillé plus loin dans la documentation |
Pour initialiser un nouvel élément à transcoder il faut donc créer une ressource TranscodificationHeader pour ensuite créer l'ensemble des valeurs à transcoder.
Pour cette deuxième partie, la ressource à utiliser est TranscodificationItem. Il fait obligatoirement référence à une ressource TranscodificationHeader et contient seulement 3 autres attributs : un identifiant unique, la valeur d'origine et la valeur cible.
| Attribut | Type | Description |
|---|---|---|
| id | numérique | identifiant unique de la ressource |
| headerId | numérique | Identifiant de la ressource TranscodificationHeader auquel il fait référence |
| producerValue | chaine de caractère | valeur de l'élément transcodé reconnue par l'organisation productrice |
| externalValue | chaine de caractère | valeur de l'élément transcodé reconnue par l'organisation externe |
Exemple des ressources TranscodificationHeader et TranscodifiatioItem :
TranscodificationHeader :
{
"id": "1231456",
"producerOrganization": "producer1",
"externalOrganization": "external1",
"field": "WASTE",
"direction": "IN",
"keyStructure": "{”fields”: [{”field”: “waste.name”, “rank”: 0}]}",
"replace": "true"
}
TranscodificationItem (qui fait référence à la précédente ressource TranscodificationHeader :
{
"id" : "4564",
"headerId" : "1231456",
"producerValue" : "carton",
"externalValue" : "carton 90/10"
}
Structure de clé
L'objet KeyStructure permet de définir la façon dont on va composer une clé unique à partir des objets métiers Trinov que nous transmettons vers un prestataire ou que nous recevons d'un prestataire.
Prenons l'exemple d'une ressource WasteCollection qui représente une collecte de déchet. Cette ressource contient une ressource Waste qui représente et contient l'ensemble des informations sur le déchet à collecter.
Un prestataire qui souhaite créer une collecte de déchet dans Trinov par le biais de l'endpoint POST /api/v1/waste-collection va renseigner dans le body de son appel une ressource WasteCollection.
La ressource Waste contient plusieurs attributs dont l'attribut "name".
Le prestataire aura renseigné comme valeur "carton 90/10" dans l'attribut "name" de la ressource Waste. Le service Trinov qui réceptionne la ressource WasteCollection à créer va appeler les services de transcodification avec pour paramètres les informations de l'appelant (externalOrganization), du producteur de déchet visé (producerOrganization), field = WASTE puisqu'on transcode ici une ressource Waste, direction = IN. Il va alors récupérer l'objet KeyStructure pour générer la valeur de l'organisation externe.
A partir de l'ensemble de ces informations, le service récupère la valeur cible, c'est-à-dire la valeur de l'organisation productrice pour envoyer la ressource WasteCollection avec les valeurs des référentiels du client Trinov.
Le mode Replace
Ce mode n'est effectif que pour le sens sortant, c'est à dire pour les transcodifications qui prennent la valeur d'un élément basé sur les référentiels du producteur de déchet pour retourner la valeur de l'organisation externe correspondante.
Imaginons toujours la ressource Waste contenant les informations du déchet à collecter. Cette ressource est très complète lorsqu'elle est issue de Trinov (tous les attributs ou presque sont renseignés). Dans le cas de la transcodification sortante, si on décide de remplacer la ressource d'origine par les valeurs issues de la transcodification, l'API effacera tous les attributs puis affectera les nouvelles valeurs.
Si on décide de ne pas remplacer, les attributs d'origine resteront intactes, seuls les attributs faisant l'objet de la transcodificaiton (basé sur la KeyStructure) seront changés. On obtient alors une ressource Waste très complète.
Updated about 1 month ago