← Tous les articles

Gérer les devises et les taux de change

Chaque compagnie Sage 50 a une devise de base (par exemple CAD). Les devises étrangères comme USD sont configurées par l’API Devises, et les taux de change datés sont gérés par l’API Taux de change. Ensemble, elles permettent d’enregistrer des factures, des achats et des écritures de journal en devise étrangère.

La devise de base existe déjà dans Sage et ne peut pas être créée, modifiée ou supprimée par l’API. Utilisez POST /api/currencies uniquement pour ajouter des devises étrangères.

Prérequis

Avant de travailler avec les devises, assurez-vous d’avoir :

Authentification

Passez votre clé API dans l’en-tête de requête x-api-key :

x-api-key: YOUR_API_KEY

Points de terminaison

GET    /api/currencies
POST   /api/currencies
GET    /api/currencies/{id}
PUT    /api/currencies/{id}
DELETE /api/currencies/{id}
GET    /api/currencies/{code}

GET    /api/exchange-rates?currencyId={id}
POST   /api/exchange-rates
PUT    /api/exchange-rates
DELETE /api/exchange-rates?currencyId={id}&date={date}
GET    /api/exchange-rates/current?currencyId={id}
GET    /api/exchange-rates/exact?currencyId={id}&date={date}

Lister les devises

Utilisez GET /api/currencies pour retourner toutes les devises configurées dans Sage, y compris la devise de base. C’est le meilleur point de départ lorsque vous avez besoin d’un currencyId pour les appels de taux de change ou que vous voulez confirmer quelles devises sont déjà configurées.

[
  {
    "id": 1,
    "code": "CAD",
    "description": "Canadian Dollar",
    "isHomeCurrency": true,
    "symbol": "$",
    "used": true,
    "currentExchangeRate": 1.0
  },
  {
    "id": 2,
    "code": "USD",
    "description": "US Dollar",
    "isHomeCurrency": false,
    "symbol": "$",
    "used": true,
    "currentExchangeRate": 1.48
  }
]

isHomeCurrency indique la devise de base de la compagnie. used est true lorsque la devise est référencée dans des transactions. currentExchangeRate apparaît sur les devises étrangères et reflète le taux en vigueur aujourd’hui par rapport à la devise de base. Les identifiants de devise diffèrent selon la compagnie.

Créer une devise étrangère

Utilisez POST /api/currencies pour ajouter une devise étrangère. La devise de base ne peut pas être créée par ce point de terminaison.

Champ Requis? Si omis
code Oui La requête est rejetée. Le code doit être unique (p. ex. USD)
description Oui La requête est rejetée
symbol Oui La requête est rejetée
decimalPlaces Non Sage utilise sa précision décimale par défaut pour la devise

Corps de la requête :

{
  "code": "EUR",
  "description": "Euro",
  "symbol": "EUR",
  "decimalPlaces": 2
}

Une requête réussie retourne 201 Created avec la nouvelle devise, y compris son id Sage :

{
  "id": 3,
  "code": "EUR",
  "description": "Euro",
  "isHomeCurrency": false,
  "symbol": "EUR",
  "used": false
}

currentExchangeRate est omis tant qu’aucun taux de change n’existe pour la devise.

Consulter une devise

Consultez une devise par identifiant interne Sage :

GET /api/currencies/2

Ou par code de devise lorsque vous le connaissez déjà :

GET /api/currencies/USD

Les deux retournent un objet SageCurrencyDto unique. Utilisez la recherche par code lors de l’intégration avec des systèmes externes qui stockent des codes de devise ISO. Utilisez la recherche par id lorsque vous avez déjà la valeur obtenue via GET /api/currencies ou une réponse de création.

Modifier et supprimer une devise

Modifiez une devise étrangère avec PUT /api/currencies/{id}. Envoyez les mêmes champs que pour la création. La devise de base ne peut pas être modifiée. Le changement de code est rejeté si le nouveau code est déjà utilisé.

{
  "code": "USD",
  "description": "United States Dollar",
  "symbol": "$",
  "decimalPlaces": 2
}

Une modification réussie retourne 204 No Content.

Supprimez une devise étrangère avec DELETE /api/currencies/{id}. La devise de base ne peut pas être supprimée. Si la devise est référencée dans des transactions (used: true), Sage retourne 400 Bad Request avec un message tel que Currency 2 is in use and cannot be deleted.

Taux de change

Les taux de change s’appliquent uniquement aux devises étrangères, pas à la devise de base. Chaque taux est daté et exprimé par rapport à la devise de base de la compagnie. Par exemple, un taux de 1.35 sur USD signifie que 1 USD équivaut à 1,35 CAD lorsque CAD est la devise de base.

Historique des taux

Utilisez GET /api/exchange-rates?currencyId=2 pour retourner tous les taux enregistrés pour une devise étrangère, triés par date.

[
  {
    "currencyId": 2,
    "date": "2025-03-01T00:00:00",
    "rate": 1.34
  },
  {
    "currencyId": 2,
    "date": "2025-03-15T00:00:00",
    "rate": 1.35
  }
]

Définir un taux

Utilisez POST /api/exchange-rates pour créer ou remplacer le taux pour une date précise. PUT /api/exchange-rates se comporte de la même façon. Le taux doit être supérieur à zéro. Si un taux existe déjà à cette date, il est remplacé.

Champ Requis? Si omis
currencyId Oui La requête est rejetée. Utilisez l’identifiant interne de la devise étrangère
date Oui La requête est rejetée
rate Oui La requête est rejetée. Doit être supérieur à zéro

Corps de la requête :

{
  "currencyId": 2,
  "date": "2025-03-15T00:00:00",
  "rate": 1.35
}

Une requête réussie retourne 200 OK :

{
  "currencyId": 2,
  "date": "2025-03-15T00:00:00",
  "rate": 1.35
}

Consulter un taux

Deux points de terminaison récupèrent un taux unique, mais ils se comportent différemment :

Point de terminaison Comportement
GET /api/exchange-rates/current?currencyId=2&asOf=2025-03-20T00:00:00 Retourne le taux en vigueur à la date donnée. Si aucun taux n’existe exactement à cette date, Sage retourne le taux le plus récent à cette date ou avant. Omettez asOf pour utiliser la date du jour.
GET /api/exchange-rates/exact?currencyId=2&date=2025-03-15T00:00:00 Retourne le taux enregistré exactement à cette date. Retourne 404 lorsqu’aucun taux n’existe à cette date précise.

Utilisez /current lorsque vous avez besoin du taux que Sage appliquerait à une date de transaction. Utilisez /exact lorsque vous devez confirmer si un taux a été défini un jour précis.

Supprimer un taux

Utilisez DELETE /api/exchange-rates?currencyId=2&date=2025-03-15T00:00:00 pour supprimer le taux enregistré à cette date. Une suppression réussie retourne 204 No Content. Retourne 404 lorsqu’aucun taux n’existe à cette date.

Utiliser les devises dans les transactions

Une fois une devise étrangère et son taux de change configurés, vous pouvez enregistrer des transactions dans cette devise. Les factures de vente, les factures d’achat et les écritures de journal général acceptent les champs facultatifs currencyCode et exchangeRate dans l’en-tête de la requête.

Si vous omettez les deux champs, Sage utilise la devise de base de la compagnie. Pour une écriture en devise étrangère, envoyez currencyCode et exchangeRate.

Consultez l’article sur le journal général pour un exemple complet d’écriture en devise étrangère avec currencyCode: "USD" et exchangeRate: 1.35.

Les clients et les fournisseurs stockent aussi un currencyCode. Utilisez GET /api/customers ou GET /api/vendors pour voir quelle devise chaque fiche utilise.

Exemples cURL

Lister toutes les devises :

curl "/api/currencies" \
  -H "x-api-key: YOUR_API_KEY"

Créer une devise étrangère :

curl -X POST "/api/currencies" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "code": "EUR",
    "description": "Euro",
    "symbol": "EUR",
    "decimalPlaces": 2
  }'

Définir un taux de change :

curl -X POST "/api/exchange-rates" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "currencyId": 2,
    "date": "2025-03-15T00:00:00",
    "rate": 1.35
  }'

Obtenir le taux en vigueur à une date :

curl "/api/exchange-rates/current?currencyId=2&asOf=2025-03-20T00:00:00" \
  -H "x-api-key: YOUR_API_KEY"

Réponse d’erreur

Si la requête est invalide ou que Sage rejette l’opération, l’API retourne une erreur avec un corps ProblemDetails. Cas courants :

Code de devise en double à la création :

{
  "title": "Bad request",
  "status": 400,
  "detail": "Currency code USD already exists",
  "code": "400",
  "requestId": "632969a5-d81a-418c-a098-116184f03b3e"
}

Devise utilisée lors de la suppression :

{
  "title": "Bad request",
  "status": 400,
  "detail": "Currency 2 is in use and cannot be deleted",
  "code": "400",
  "requestId": "1d508efd-e91b-429e-a973-4d63fa9509d4"
}

La devise de base ne peut pas être modifiée ou supprimée :

{
  "title": "Bad request",
  "status": 400,
  "detail": "Home currency cannot be deleted",
  "code": "400",
  "requestId": "3816dc8e-17f3-4131-9cc9-96fba880e181"
}

Le taux de change doit être supérieur à zéro :

{
  "title": "Bad request",
  "status": 400,
  "detail": "Exchange rate must be greater than zero",
  "code": "400",
  "requestId": "7d30ae67-0960-4423-bf13-30a93ec59355"
}

Taux de change introuvable lors d’une recherche exacte :

{
  "title": "Not found",
  "status": 404,
  "detail": "Exchange rate for currency 2 on 2025-04-01 not found",
  "code": "404",
  "requestId": "a2ff44ea-4bdd-46eb-a382-ec9cf396e428"
}

Les autres causes courantes incluent une tentative de modification de la devise de base (Home currency cannot be modified) et l’utilisation d’un currencyId qui n’existe pas.

Prochaines étapes