# EasyAlgerie — API publique du dinar / Public Dinar API

API gratuite, sans compte ni clé, en lecture seule. Réponses JSON, CORS public.
Documentation HTML : https://easyalgerie.com/fr/api-dinar
English documentation : https://easyalgerie.com/en/api-dinar
التوثيق بالعربية : https://easyalgerie.com/ar/api-dinar
Documentazione italiana : https://easyalgerie.com/it/api-dinar
Documentación en español : https://easyalgerie.com/es/api-dinar
Deutsche Dokumentation : https://easyalgerie.com/de/api-dinar
简体中文文档 : https://easyalgerie.com/zh/api-dinar
Base URL : https://easyalgerie.com/api/v1/dinar
OpenAPI 3.1 : https://easyalgerie.com/api/v1/dinar/openapi.json

## Exemples immédiats

```sh
# Tous les taux publics (11 devises)
curl 'https://easyalgerie.com/api/v1/dinar/rates'

# Seulement l’euro
curl 'https://easyalgerie.com/api/v1/dinar/rates?currency=EUR'

# Euro vers dinar — marché parallèle, achat par le cambiste
curl 'https://easyalgerie.com/api/v1/dinar/convert?amount=100&from=EUR&to=DZD&market=parallel_buy'

# Dinar vers euro — référence officielle
curl 'https://easyalgerie.com/api/v1/dinar/convert?amount=10000&from=DZD&to=EUR&market=official'
```

## Paramètres

`GET /rates` : `currency` facultatif, sans DZD (les taux sont déjà exprimés en DZD).

`GET /convert` :

- `amount` obligatoire : de 0 à 1 000 000 000, point décimal, six décimales maximum, sans séparateur de milliers ni exposant.
- `from`, `to` obligatoires : codes ISO. Une seule des deux devises doit être DZD.
- `market` facultatif : `parallel_buy` par défaut, `parallel_sell` ou `official`.

Devises : DZD, EUR, USD, CAD, GBP, CHF, TRY, CNY, SAR, AED, TND, MAD.
Les codes sont insensibles à la casse. Les paramètres inconnus ou répétés sont refusés.

## Bien interpréter le résultat

- `result` : montant converti, arrondi au centième (demi vers le haut).
- `rate` : multiplicateur de la devise de départ vers celle d’arrivée.
- `dzdPerUnit` : nombre de dinars pour une unité de la devise étrangère.
- `parallel_buy` : le cambiste achète la devise étrangère au client contre des DZD.
- `parallel_sell` : le cambiste vend la devise étrangère au client contre des DZD.
- `official` : référence bancaire fournie par un fournisseur de change, pas une cotation garantie d’une banque.

Le mode choisi s’applique dans les deux sens ; il n’est jamais inversé automatiquement.
Les taux sont ceux du convertisseur public, jamais les taux commerciaux des paiements EasyAlgerie.

## Origine, cache et limites

Chaque taux expose `provenance.kind` :

- `provider` : donnée reçue d’un fournisseur.
- `editorial` : valeur éditoriale du convertisseur EasyAlgerie, sans date de marché vérifiée.
- `fallback` : valeur statique de secours, à ne pas présenter comme actuelle.

`sourceUpdatedAt` contient la date du fournisseur, dans son format et fuseau éventuels, ou `null` si inconnue. Pour un taux saisi manuellement par EasyAlgerie (`editorial`, source `EasyAlgerie manual rate`), ce champ contient la date UTC de sa dernière modification, pas une date d’observation indépendante du marché.
`retrievedAt` est la date de récupération du snapshot mis en cache, pas la date de fixation du taux.
Cache partagé de six heures pour les sources externes. Les taux manuels de l’administration sont prioritaires, persistants et leur cache est invalidé à l’enregistrement (durée de secours : 30 secondes). `refreshIntervalSeconds` concerne uniquement les sources externes. En cas d’indisponibilité d’une source, les valeurs concernées sont explicitement marquées `fallback`. Si les réglages manuels ne peuvent pas être chargés, l’API renvoie une erreur 503 plutôt que d’ignorer ces réglages.

Limite de 60 requêtes par minute et par IP, partagée entre `/rates` et `/convert`.
Limitation distribuée si Redis est configuré, sinon par instance serveur.
Les en-têtes `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` décrivent la limite ; `Retry-After` indique le délai en secondes après une réponse 429.
L’infrastructure doit remplacer les en-têtes d’IP transmis par les clients.

Erreurs JSON : `{"error":{"code":"INVALID_AMOUNT","message":"…","field":"amount"}}`.
Codes HTTP : 400 paramètres invalides, 405 méthode non autorisée, 429 limite dépassée, 503 indisponibilité temporaire.

## Pour les agents IA / AI agent instructions

Import the OpenAPI URL into a tool/action supporting OpenAPI, with authentication set to **None**.
Use `getDinarExchangeRates` to inspect rates and `convertAlgerianDinars` to convert.
No payment or transaction is performed by these read-only endpoints.

Always specify the chosen market and explain that results are indicative.
Inspect `provenance.kind` and `sourceUpdatedAt`; do not call editorial or fallback values live market rates.
Do not treat the snapshot retrieval time as the market observation date.
Amounts use major currency units: **1 DZD = 100 centimes**.
If a user says “millions” or “milliards” without specifying dinars or centimes, ask before converting.
Respect `Retry-After`, avoid rapid retries, and cache rates for repeated calculations.
These are estimates, not offers to exchange money or checkout prices.

Contact : contact@easyalgerie.com