Données de référence acheteur et masquage

Les bons de travail référencent un monde possédé par vos acheteurs : leurs entreprises, emplacements, régions et actifs. L’API Fournisseur en expose des vues en lecture seule, filtrées à ce que vos relations vous permettent de voir. Tous les exemples supposent :

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

Masquage de données

Ce que vous voyez dépend du type de fournisseur auquel appartient votre clé :

Les clés d’équipes de service internes (votre entreprise fournisseur est l’équipe interne de l’acheteur) reçoivent les fiches complètes.
Les clés de fournisseurs tiers reçoivent des fiches masquées sur les bons de travail, les emplacements et les factures : les champs privés à l’acheteur sont vidés avant que la réponse soit retournée.

Si un champ que vous attendez est systématiquement vide, le masquage est la première chose à vérifier. La portée elle-même ne peut pas être élargie par des filtres; les filtres de sécurité de locataire dérivés de votre clé s’appliquent toujours.

Entreprises acheteuses

GET /v1/supplier/buyer_company/buyer_companies retourne chaque entreprise acheteuse ayant une relation avec votre fournisseur. Aucune pagination ni filtre n’est honoré : l’ensemble complet avec portée de locataire revient dans une seule réponse (les buyerCompanySettings de chaque entreprise sont enlevés).

curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/buyer_company/buyer_companies"

Utilisez-le pour indexer le comportement par acheteur dans votre intégration (quels types de problèmes utiliser, quels acheteurs approuvent automatiquement les complétions de tiers, etc.).

Emplacements et régions

# Liste : la taille de page est plafonnée à 10 sur cet endpoint (les limites plus grandes sont réduites silencieusement)
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/location/locations?limit=10"

# Décompte, un seul, ou plusieurs à la fois
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/supplier/location/locations/count_by"
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/supplier/location/locations/1204"
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/supplier/location/locations/multiple/1204,1205"

La liste d’emplacements plafonne limit à 10; la plupart des autres listes permettent 25.
multiple/{ids} supprime silencieusement les ids que vous ne pouvez pas lire; le count de la réponse égale ce qui a été effectivement retourné.
Les régions (regroupements d’emplacements par entreprise acheteuse) sont à GET /v1/supplier/location/regions et /regions/{id} avec pagination standard.

Actifs et types d’actifs

Les actifs sont l’équipement que vos techniciens entretiennent; les types d’actifs les classent.

curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/asset/assets?locationId=1204&limit=25"
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/supplier/asset/assets/5511"
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/supplier/asset/asset_types?limit=25"

La lecture d’un seul actif hydrate les compteurs de l’actif (enveloppe de type ApiAssetWithMeter), ce qui donne à vos techniciens le contexte de l’historique des compteurs avant une visite. Les quatre endpoints (assets, assets/{id}, asset_types, asset_types/{id}) sont en lecture seule avec pagination standard et filtres par champ.

Étiquettes d’actifs

Les étiquettes d’actifs sont des marqueurs définis par l’acheteur sur les actifs (un nom et une couleur optionnelle). Elles appartiennent toujours à une entreprise acheteuse, alors l’accès via l’API Fournisseur est limité aux clés de l’équipe de service interne d’un acheteur : ces clés voient le catalogue de leur entreprise acheteuse, tandis que la clé d’un fournisseur tiers obtient une liste vide.

# Le catalogue (clés d'équipes de service internes seulement)
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/asset/asset_labels?no_pagination=true"

# Remplacer les étiquettes sur un actif
curl -X PUT "$BASE/v1/supplier/asset/assets/5511/labels" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [7, 21] }'

Le catalogue est en lecture seule (GET /v1/supplier/asset/asset_labels et /{id}); les étiquettes se créent et se modifient dans l’application OpenWrench. La liste est paginée à 10 par page par défaut, accepte les filtres search et label sur le texte de l’étiquette, et no_pagination=true retourne tout le catalogue. PUT /v1/supplier/asset/assets/{assetId}/labels remplace l’ensemble complet des étiquettes sur l’actif ({ "ids": [...] }; un tableau vide les efface toutes) et retourne les étiquettes désormais actives. L’écriture requiert la permission d’écriture sur les actifs, et chaque id doit être une étiquette active du catalogue de votre entreprise acheteuse. La clé d’un fournisseur tiers obtient 400 même lorsqu’elle détient 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.

Stratégie de cache

Les données de référence changent lentement. Une configuration pratique :

Rafraîchissez les entreprises acheteuses quotidiennement (un appel).
Synchronisez les emplacements et les actifs pour les bons de travail actifs à la demande, en mettant en cache par id.
Traitez 400 sur une lecture unique comme « hors de votre portée » et 404 comme « n’existe pas », et attendez-vous à ce que des ids disparaissent de votre vue lorsqu’une relation acheteur se termine.

Premiers pas

Guides

Référence de l’API

Données de référence acheteur et masquage

Masquage de données

Entreprises acheteuses

Emplacements et régions

Actifs et types d’actifs

Étiquettes d’actifs

Stratégie de cache

​Masquage de données

​Entreprises acheteuses

​Emplacements et régions

​Actifs et types d’actifs

​Étiquettes d’actifs

​Stratégie de cache

Masquage de données

Entreprises acheteuses

Emplacements et régions

Actifs et types d’actifs

Étiquettes d’actifs

Stratégie de cache