Passer au contenu principal
Tout ce que pointe un bon de travail se trouve ici : les emplacements et les actifs. Les emplacements sont vos sites physiques, regroupés en régions. Les actifs sont des équipements sur un emplacement, classés par type d’actif, éventuellement normalisés par modèle d’actif et instrumentés avec des compteurs. Tous les exemples supposent :

Emplacements

Les emplacements sont principalement en lecture via l’API :
Remarques :
  • L’endpoint de liste limite limit à 10 (la plupart des endpoints de liste permettent 25). Planifiez vos boucles de pagination en conséquence.
  • multiple/{ids} prend des ids séparés par des virgules et omet silencieusement tout id pour lequel vous n’avez pas la permission de lecture. Vérifiez quels ids ont été retournés plutôt que de présumer que tous l’ont été.
  • La seule écriture est PATCH /v1/buyer/location/locations/{id}, et elle ne lit que locationTypeDetails dans le corps (les valeurs de champ personnalisées pour le type de l’emplacement). Tous les autres champs sont ignorés.
Les régions regroupent les emplacements : GET /v1/buyer/location/regions et GET /v1/buyer/location/regions/{id}.

Types d’actifs

Les types d’actifs classent l’équipement (« Chambre froide », « Unité de toit ») et portent des valeurs par défaut au niveau de la classe, y compris les paramètres de frigorigène.
  • name est le seul champ requis. buyerCompanyId est dérivé de votre clé et ne peut pas être défini.
  • applianceCategory, refrigerantTypeCode et fullChargeLb acceptent un null explicite pour effacer la valeur par défaut au niveau de la classe. fullChargeLb doit être positif lorsqu’il est fourni.
  • fullChargeLb accepte au plus 5 décimales et 14 chiffres au total, soit jusqu’à 9 chiffres avant le point décimal. Les décimales supplémentaires vous permettent de stocker exactement les conversions d’onces, par exemple 0.0625 (1 oz), 0.03125 (une demi-once) ou 0.00625 (un dixième d’once). OpenWrench refuse les valeurs plus précises avec une erreur 400. Il ne les arrondit pas.
  • Passer un id met à jour un type existant.
Lecture avec GET /v1/buyer/asset/asset_types et GET /v1/buyer/asset/asset_types/{id}.

Actifs

Créez un actif avec POST /v1/buyer/asset/assets. Requis : name, assetTypeId, locationId, isActive, isLeased.
Comportement à connaître :
  • buyerFacilityId et buyerCompanyId sont dérivés de l’emplacement, jamais lus depuis le corps.
  • Les remplacements de frigorigène sont effaçables. refrigerantTypeCode, fullChargeLb, applianceCategory et refrigerantRequiresProcessShutdown sont des remplacements par unité des valeurs par défaut du type d’actif. Omettre la clé conserve la valeur stockée; un null explicite (ou une chaîne vide) l’efface pour revenir à hériter du type. isRefrigerantTracked se comporte de la même façon : omis ou null conserve la valeur stockée, et seul un false explicite désactive l’inscription.
  • fullChargeLb sur un actif suit les mêmes règles de positivité et de précision que sur un type d’actif.
  • Sous-actifs. parentId en fait un sous-actif. Cela nécessite que les sous-actifs soient activés pour votre entreprise, et l’enfant doit être au même emplacement que le parent.
  • Passer un id met à jour un actif existant.
Lectures :
asset_lite est le moyen économique de synchroniser un sélecteur d’actifs. Lorsque vous ne passez aucun paramètre de pagination, il retourne l’ensemble complet non paginé, avec count égal au nombre d’éléments retournés. La lecture d’un seul actif hydrate les compteurs (le type de l’enveloppe indique ApiAssetWithMeter).

Étiquettes d’actifs

Les étiquettes d’actifs sont des marqueurs légers que votre équipe définit dans l’application OpenWrench (un nom et une couleur optionnelle). Elles sont utiles pour découper la liste d’actifs de façons que les champs intégrés ne couvrent pas. Via l’API, vous pouvez lire le catalogue et remplacer les étiquettes appliquées à un actif. La création et la modification des étiquettes elles-mêmes restent dans l’application. Parcourez le catalogue avec GET /v1/buyer/asset/asset_labels, ou récupérez-en une avec GET /v1/buyer/asset/asset_labels/{id}. La liste est restreinte aux étiquettes de votre entreprise et paginée à 10 par page par défaut. Elle accepte les filtres search et label sur le texte de l’étiquette. Passez no_pagination=true pour récupérer tout le catalogue en un seul appel (le tri s’applique toujours).
Remplacez les étiquettes d’un actif avec PUT /v1/buyer/asset/assets/{assetId}/labels. Le corps est { "ids": [...] } et il s’agit d’un remplacement complet : les étiquettes non listées sont retirées, et un tableau vide les efface toutes. La réponse liste les étiquettes désormais actives sur l’actif.
Comportement à connaître :
  • OpenWrench rejette avec 400 un ids manquant ou qui n’est pas un tableau, ou un id qui n’est pas un nombre entier.
  • Chaque id doit être une étiquette active du catalogue de votre entreprise. Les ids inconnus ou d’un autre locataire répondent 400 avec la liste des ids fautifs.
  • L’écriture requiert la permission d’écriture sur les actifs. Un id d’actif inconnu, supprimé ou étranger répond le même 400 qu’une écriture refusée, pas un 404.

Modèles d’actifs

Les modèles normalisent les caractéristiques et les manuels par type. POST /v1/buyer/asset/asset_models requiert modelName et assetTypeId, avec des pièces jointes manuals et specs optionnelles. L’appariement approximatif est pratique lors des importations, quand vos données sources contiennent des noms de modèles en texte libre :
GET /v1/buyer/asset/asset_models/fuzzy/{name}/{assetTypeId} retourne le modèle le plus proche dans le type d’actif, ou 404 si rien n’est suffisamment proche. Repliez-vous sur la création du modèle en cas de 404.

Compteurs et relevés

Les compteurs attachent une série mesurable à un actif (température, heures de fonctionnement, nombres de cycles). Créez le compteur une fois, puis enregistrez des relevés :
Remarques :
  • valueType, valueUnit et locationId ne sont pas lus dans le corps de création du compteur. Le serveur les dérive à partir de l’actif et du type de compteur référencés, donc les envoyer n’a aucun effet.
  • readingMode (renommé depuis seriesType) vaut direct_reading, change_from_baseline ou compare_to_target; la valeur par défaut est direct_reading si omis.
  • Les endpoints de liste et de comptage des relevés ne sont pas limités à un seul compteur. Ils couvrent tous les relevés de votre entreprise acheteuse, sauf si vous filtrez par meterId.
  • Lorsque le readingMode d’un compteur est change_from_baseline, le lastBaselineValue d’un relevé récupéré est calculé à partir du relevé antérieur le plus récent marqué isBaseline sur ce compteur, en date de recordedAt. Pour les autres modes, il vaut null.

Stratégie de synchronisation

Pour une synchronisation nocturne des actifs : paginez asset_lite pour l’ensemble des ids, comparez avec votre système, puis récupérez les fiches complètes par id uniquement pour les actifs modifiés. Cela vous garde bien à l’intérieur de la limite de débit (10 requêtes par fenêtre de 20 secondes), beaucoup plus confortablement que de paginer la liste complète à 25 par appel.