> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.useopenwrench.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Account and utilities

# Identité, approvisionnement d'utilisateurs et utilitaires dans l'API Acheteur

> Vérifier les identifiants, inspecter l'identité derrière une clé d'API Acheteur, approvisionner des utilisateurs acheteurs avec des rôles limités et obtenir les taux de change de devises.

Cette page couvre les petits endpoints dont toute intégration finit par avoir besoin : la vérification d'état, l'identité de la clé, l'approvisionnement d'utilisateurs et les taux de change.

Tous les exemples supposent :

```bash theme={null}
export BASE="https://api.useopenwrench.com/api/external"
export KEY="<your-api-key>"
export SECRET="<shared-secret>"
```

## Ping et identité

`GET /v1/buyer/ping` vérifie les deux en-têtes et retourne `{"type":"pingpong","data":"pong","status":"ok"}`. Cet endpoint n'est pas limité en débit, il convient donc aux sondes de surveillance.

`GET /v1/buyer/me` retourne l'identité derrière votre clé sous forme de projection délibérément réduite : `email` du contact, nom, `contactType`, `buyerFacilityName`, `buyerCompanyId` et `buyerCompanyName`.

```bash theme={null}
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/buyer/me"
```

Appelez-le une fois au démarrage : la création de bon de travail nécessite votre `buyerCompanyId` et l'id d'établissement [dans le corps de la requête](/buyer-api/work-orders#create-a-work-order), et journaliser l'identité rend les erreurs de clé évidentes.

## Approvisionner des utilisateurs acheteurs

`POST /v1/buyer/user/provision` crée un contact acheteur, optionnellement avec un identifiant de connexion, et envoie un courriel d'invitation. Utilisez-le pour synchroniser des utilisateurs depuis votre système RH ou de gestion d'identité.

```bash theme={null}
curl -X POST "$BASE/v1/buyer/user/provision" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jordan@example.com",
    "nameGiven": "Jordan",
    "nameFamily": "Rivera",
    "roles": ["BUYER_FM"],
    "title": "Facilities Manager",
    "hasAccessToAllLocations": false,
    "locationIds": [1204, 1205]
  }'
```

Règles appliquées par l'endpoint :

* `email`, `nameGiven`, `nameFamily` et `roles` sont requis. **Les rôles admin et super-admin sont rejetés avec `403`**. L'approvisionnement par API est réservé aux rôles réguliers.
* L'établissement cible est par défaut celui associé à votre clé d'API. Un `facilityId` fourni doit appartenir à la même entreprise acheteuse (sinon `403`).
* Un compte ou un contact existant déjà pour le courriel renvoie `400` avec un message de conflit.
* Avec un `password`, la connexion est créée immédiatement et le courriel d'invitation indique « vous a invité à OpenWrench »; sans mot de passe, l'invitation demande à l'utilisateur de s'inscrire. `passwordResetRequired` force un changement à la première connexion.
* Portée d'emplacement : `hasAccessToAllLocations`, ou `locationIds`/`brandIds` explicites.
* Les identifiants EPA 608 des techniciens peuvent être attachés avec `epaCertificationType` (validé contre les classes reconnues; les valeurs inconnues renvoient `400`) et `epaCertificationNumber` (format libre, maximum 64 caractères).

Le contact créé est retourné dans l'enveloppe standard.

## Taux de change de devises

Les portefeuilles multidevises peuvent récupérer le dernier taux stocké entre deux codes de devises :

```bash theme={null}
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/currency_exchange/latest/CAD/USD"
```

`GET /v1/buyer/currency_exchange/latest/{targetCurrencyId}/{baseCurrencyId}` prend des codes de devise (par exemple `USD`, `CAD`) et retourne le dernier taux de la devise de base vers la devise cible. Les bons de travail portent les champs associés `currencyId`, `locationCurrencyId` et les deux valeurs `currencyExchangeRate...` lorsque la tarification multidevise est en jeu.