Passer au contenu principal
L’API Acheteur d’OpenWrench donne aux exploitants d’installations un accès programmatique à l’ensemble du côté acheteur de la plateforme. Vous pouvez l’utiliser pour créer et suivre des bons de travail, gérer des actifs et des emplacements, réviser des soumissions et des factures, surveiller l’entretien préventif et interroger votre réseau de fournisseurs.

URL de base

Tous les endpoints acheteur sont sous /v1/buyer/.

Authentification

Chaque requête doit comporter deux en-têtes : X-API-KEY (votre clé d’API, émise par contact acheteur) et OW-KEY (le secret partagé OpenWrench émis avec la clé). La clé restreint automatiquement chaque requête à votre entreprise. Vous ne voyez que vos propres données. Les requêtes auxquelles il manque l’un des en-têtes renvoient 401.
Pour obtenir une clé d’API et un secret partagé, communiquez avec support@useopenwrench.com. Utilisez GET /v1/buyer/me pour inspecter l’identité (contact, établissement, entreprise) associée à votre clé. Les clés n’expirent pas d’elles-mêmes. Pour en effectuer la rotation, demandez au soutien une nouvelle paire clé/secret partagé, déployez la nouvelle paire, puis demandez au soutien de révoquer l’ancienne.
La section API Équipes internes plus bas dans cet onglet utilise une clé d’API partenaire distincte. Votre clé acheteur ne s’authentifiera pas contre les endpoints /v1/partners/. Voir l’introduction à l’API Équipes internes pour les détails.

Limites de débit

10 requêtes par fenêtre de 20 secondes par clé. Au-delà, vous recevrez 429 Too Many Requests : attendez au moins 20 secondes avant de réessayer, et espacez les tâches en arrière-plan (par exemple les exports paginés complets) pour qu’elles demeurent sous la limite.

Garder les bons de travail synchronisés

Si votre intégration réplique les bons de travail dans un autre système (un outil de billetterie, un ERP, un entrepôt de données), bâtissez-la sur la poussée, pas sur le sondage :
  1. Enregistrez un endpoint webhook. OpenWrench envoie les événements workorder.create, workorder.status_update et workorder.new_note à mesure qu’ils se produisent.
  2. À chaque événement, récupérez ce seul bon de travail avec GET /v1/buyer/work_order/work_orders/{id}.
  3. Utilisez GET /v1/buyer/work_order/work_orders pour les requêtes ponctuelles, le chargement initial unique et la réconciliation occasionnelle, avec un filtre étroit et une petite page.
Ne sondez pas l’endpoint de liste selon un horaire pour trouver les bons de travail nouveaux ou modifiés. C’est la lecture la plus coûteuse de l’API, elle est lente sur les gros comptes et elle rivalise avec votre vrai travail pour la limite de débit. Voir Bons de travail pour les détails.

Enveloppe de réponse

Réponses à entité unique :
Les réponses de liste ajoutent un count total :
Erreurs :
401 signifie une clé manquante ou invalide; 400 couvre les entrées incorrectes, les filtres invalides et les refus de permission; 429 correspond à la limite de débit.

Pagination et filtrage

Les endpoints de liste acceptent offset, limit (par défaut 10, maximum 25), sort_by et order (asc | desc). Les paramètres de requête supplémentaires sont traités comme des filtres. Chaque endpoint prend en charge son propre ensemble de clés de filtre, et les clés qu’il ne reconnaît pas sont ignorées plutôt que rejetées. Les filtres à plusieurs valeurs utilisent une clé au pluriel avec des valeurs séparées par des virgules (statuses=Unassigned,PendingApproval). Pour les bons de travail, consultez la référence des filtres.

Formats de date

La plupart des horodatages sont des chaînes ISO 8601 avec décalage (par exemple 2026-08-14T13:05:22.000-07:00); certains champs d’horodatage de base de données sont sérialisés au format yyyy-MM-dd HH:mm:ss.S. Les dates simples sont au format yyyy-MM-dd. Lorsque vous envoyez des dates-heures, utilisez le format ISO 8601. Les filtres de date des listes de factures, de propositions et de bons de travail font exception. Ils prennent MM/dd/yyyy HH:mm:ss, une heure locale sans décalage, par exemple 10/09/2026 00:00:00 :
  • Fuseau horaire. Passez le paramètre de requête facultatif timezone pour définir le fuseau dans lequel OpenWrench lit les valeurs. Utilisez un nom de fuseau IANA, comme America/Chicago, America/New_York ou UTC. Les noms sont sensibles à la casse. Sans timezone, OpenWrench lit les valeurs en UTC.
  • Fuseaux rejetés. Les décalages fixes (-05:00, GMT-5, Z, Etc/GMT+5), les abréviations (CST) et les noms inconnus renvoient 400.
  • Aucun décalage dans la valeur. OpenWrench ignore un décalage comme -05:00 à la fin d’une valeur de filtre. Utilisez plutôt timezone.
  • Les valeurs mal formées renvoient 400. Une valeur qui ne correspond pas au format renvoie 400, par exemple Invalid markedPaidAtStartDate. Expected format MM/dd/yyyy HH:mm:ss. Cela inclut les valeurs ISO 8601 (2026-10-09T00:00:00), les dates sans heure (10/09/2026) et les valeurs composées uniquement d’espaces. OpenWrench lit encore une valeur vide comme le 1er janvier 1970.
  • Bornes de fin. Les dates de fin des factures et des propositions couvrent toute la journée de fin : OpenWrench remplace l’heure par 23:59:59 à cette date dans le fuseau timezone. Les dates de fin des bons de travail sont exactes, alors envoyez 23:59:59 pour inclure toute la journée.
  • Heure avancée. Une heure située dans l’heure sautée lors du passage à l’heure avancée est avancée de la durée de l’écart. Une heure située dans l’heure répétée lors du retour à l’heure normale désigne l’occurrence en heure normale, soit la deuxième.
Par exemple, cette requête renvoie les factures marquées payées le 9 octobre 2026, heure du Centre :
Pour les filtres de chaque liste, consultez les règles des valeurs de filtre pour les bons de travail, les factures et les propositions.

Guides détaillés

Les guides de cet onglet parcourent chaque partie de l’API en profondeur, avec des charges utiles, des modèles de statut et des modèles d’intégration :

Bons de travail

Créer, filtrer, réaffecter, clôturer. Modèle de statut, notes et types de problèmes.

Webhooks

Événements de création de bon de travail, de changement de statut et de nouvelle note envoyés à votre endpoint.

Appels de service

Preuves de visite : journaux de travail, temps de travail réel et détails des techniciens.

Actifs et emplacements

Emplacements, régions, types d’actifs, modèles, compteurs et suivi des frigorigènes.

Factures

Pipeline d’approbation, synchronisation avec les comptes fournisseurs, exports aplatis et mises à jour en lot.

Soumissions et propositions

Lire les soumissions des fournisseurs et les réconcilier avec les factures.

Entretien préventif

Lire les calendriers, sauter des exécutions et piloter l’entretien préventif depuis un planificateur externe.

Réseau de fournisseurs

Interroger votre réseau et classer les fournisseurs du réseau privé pour la répartition.

Inspections de site

Visites d’inspection et bons de travail issus de leurs constats.

Fichiers et pièces jointes

Téléverser une fois, référencer partout, télécharger les preuves.

Compte et utilitaires

Ping, identité de la clé, approvisionnement d’utilisateurs et taux de change.