Actifs, types d'actifs, modèles, compteurs et emplacements

Tout ce que pointe un bon de travail se trouve ici : les emplacements (vos sites physiques, regroupés en régions) et les actifs (é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 :

export BASE="https://api.useopenwrench.com/api/external"
export KEY="<your-api-key>"
export SECRET="<shared-secret>"

Emplacements

Les emplacements sont principalement en lecture via l’API :

# Liste (la taille de page sur cet endpoint est limitée à 10, même si vous demandez davantage)
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/buyer/location/locations?limit=10"

# Nombre correspondant à un filtre
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/buyer/location/locations/count_by?regionId=4"

# Un emplacement, ou plusieurs en un seul aller-retour
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/buyer/location/locations/1204"
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/buyer/location/locations/multiple/1204,1205,1210"

Notes :

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.

curl -X POST "$BASE/v1/buyer/asset/asset_types" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Walk-in cooler",
    "usesRefrigerant": true,
    "refrigerantTypeCode": "R-448A",
    "fullChargeLb": 12.5
  }'

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.
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.

curl -X POST "$BASE/v1/buyer/asset/assets" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cooler #2 - back of house",
    "assetTypeId": 301,
    "locationId": 1204,
    "isActive": true,
    "isLeased": false,
    "serialNumber": "WC2-99841",
    "manufacturer": "Arctic Air",
    "assetModelId": 77,
    "installDate": "2024-05-01"
  }'

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 l’inscription n’est désactivée que par un false explicite.
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 :

# Liste complète avec filtres
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/buyer/asset/assets?locationId=1204&limit=25"

# Projection allégée : id, nom, type, numéro de série, emplacement, garanties
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/buyer/asset/assets/asset_lite?locationId=1204"

# Un actif, hydraté avec ses compteurs
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/buyer/asset/assets/5511"

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), 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. Parcourir le catalogue avec GET /v1/buyer/asset/asset_labels, ou en récupérer 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).

curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/asset/asset_labels?no_pagination=true"

Remplacer 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.

curl -X PUT "$BASE/v1/buyer/asset/assets/5511/labels" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [7, 21] }'

Comportement à connaître :

Un ids manquant ou qui n’est pas un tableau, ou un id qui n’est pas un nombre entier, est rejeté avec 400.
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 :

curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/asset/asset_models/fuzzy/Arctic%20Air%20WC-200/301"

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 :

# 1. Créer le compteur
curl -X POST "$BASE/v1/buyer/asset/meters" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Box temperature",
    "assetId": 5511,
    "meterTypeId": 2,
    "readingMode": "direct_reading"
  }'

# 2. Enregistrer des relevés (p. ex. depuis un pont IoT)
curl -X POST "$BASE/v1/buyer/asset/meter_readings" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "meterId": 9310,
    "value": "38.2",
    "expectedValue": "36",
    "recordedAt": "2026-08-21T09:00:00.000-07:00",
    "recordedBy": "iot-bridge@example.com"
  }'

# 3. Lister, compter et récupérer les compteurs et les relevés
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/buyer/asset/meters?assetId=5511"
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/buyer/asset/meters/count_by?assetId=5511"
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/buyer/asset/meters/9310"

curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/buyer/asset/meter_readings?meterId=9310"
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/buyer/asset/meter_readings/count_by?meterId=9310"
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/buyer/asset/meter_readings/40021"

Remarques :

valueType, valueUnit et locationId ne sont pas lus dans le corps de création du compteur : ils sont dérivés côté serveur à partir de l’actif et du type de compteur référencés; 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.

Premiers pas

Guides

Référence de l’API

Internal Teams API

Actifs, types d'actifs, modèles, compteurs et emplacements

Emplacements

Types d’actifs

Actifs

Étiquettes d’actifs

Modèles d’actifs

Compteurs et relevés

Stratégie de synchronisation

​Emplacements

​Types d’actifs

​Actifs

​Étiquettes d’actifs

​Modèles d’actifs

​Compteurs et relevés

​Stratégie de synchronisation

Emplacements

Types d’actifs

Actifs

Étiquettes d’actifs

Modèles d’actifs

Compteurs et relevés

Stratégie de synchronisation