L'API ELEGG FX

Démarrer

Un administrateur du compte crée une clé dans ELEGG FX : Paramètres → API. Une clé par logiciel, à son nom : vous pourrez en révoquer une sans couper les autres. La clé n'est affichée qu'une fois ; rangez-la dans les réglages sécurisés de votre ERP.

Chaque appel porte la clé dans l'en-tête Authorization. Vérifiez qu'elle fonctionne :

curl https://eleggfinance.com/api/v1/account \
  -H "Authorization: Bearer elegg_live_…"

Les règles communes

• Adresse de base : https://eleggfinance.com/api/v1. Corps et réponses en JSON (UTF-8).
• Chaque ligne porte une « reference » : le numéro de la facture ou du contrat dans votre ERP (1 à 100 caractères). Renvoyer la même référence remplace la ligne au lieu de la dupliquer — vous pouvez donc renvoyer tout votre carnet chaque nuit.
• Votre ERP fait foi : une ligne renvoyée remplace aussi les retouches faites dans ELEGG FX, et un champ facultatif absent de l'envoi est effacé.
• Tout ou rien : si une seule ligne est refusée, rien n'est enregistré et la réponse liste chaque erreur. 1000 lignes au plus par envoi.
• Le sens n'est jamais deviné : « buy » quand vous achetez la devise (facture fournisseur, importation), « sell » quand vous la vendez (facture client, exportation).
• Dates au format AAAA-MM-JJ. Montants dans la devise de la ligne. Cours exprimés en devise pour 1 euro (EUR/USD 1,0875 s'écrit 1.0875).
• 120 appels par minute et par clé. Au-delà : réponse 429, réessayez quelques secondes plus tard.

Les points d'accès

Besoins en devises

Un besoin est un montant en devise à payer ou à encaisser : en pratique, le restant dû d'une facture. Il entre dans l'exposition, le calendrier de couverture et le reporting.

curl -X PUT https://eleggfinance.com/api/v1/needs \
  -H "Authorization: Bearer elegg_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "needs": [
      {
        "reference": "FAC-2026-0142",
        "currency": "USD",
        "side": "buy",
        "amount": 125000,
        "due_date": "2026-12-15",
        "counterparty": "Shenzhen Parts Ltd",
        "invoice_number": "SP-88412",
        "budget_rate": 1.08
      }
    ]
  }'

{
  "created": 1,
  "updated": 0,
  "results": [
    { "reference": "FAC-2026-0142", "id": "5f0c…", "status": "created" }
  ]
}

Factures payées

Quand une facture est réglée, signalez-le : le besoin sort de l'exposition et rejoint l'historique des paiements. « date » vaut aujourd'hui par défaut ; « rate », le cours obtenu, est facultatif. Seuls les besoins créés par l'API se règlent ici.

curl -X POST https://eleggfinance.com/api/v1/needs/settlements \
  -H "Authorization: Bearer elegg_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "settlements": [{ "reference": "FAC-2026-0142", "date": "2026-12-14", "rate": 1.0921 }] }'

Couvertures

Produits acceptés : forward, forward_open, ndf, vanilla, tunnel, leveraged, ki_forward. Les TARF et accumulateurs, qui se déplient en une ligne par constatation, se saisissent dans ELEGG FX par dépôt de la term sheet.

Les champs propres à chaque produit sont ceux de la saisie manuelle et suivent les mêmes contrôles : un tunnel exige son plafond, une barrière son niveau, etc.

curl -X PUT https://eleggfinance.com/api/v1/hedges \
  -H "Authorization: Bearer elegg_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "hedges": [
      {
        "reference": "FWD-2026-031",
        "product_type": "forward",
        "currency": "USD",
        "side": "buy",
        "notional": 500000,
        "rate": 1.0875,
        "maturity_date": "2027-03-31",
        "trade_date": "2026-10-19",
        "counterparty": "BNP Paribas"
      }
    ]
  }'

{
  "valued_at": "2026-10-19T08:12:03.512Z",
  "total_mtm_eur": 3184.52,
  "hedges": [
    {
      "id": "9a71…",
      "reference": "FWD-2026-031",
      "source": "api",
      "product_type": "forward",
      "currency": "USD",
      "side": "buy",
      "notional": 500000,
      "rate": 1.0875,
      "maturity_date": "2027-03-31",
      "mtm_eur": 3184.52,
      …
    }
  ],
  "structures": [],
  "count": 1
}

Lire le MTM

GET /hedges rend chaque couverture vivante avec « mtm_eur » : sa valeur de marché en euros au moment de l'appel, calculée comme sur votre tableau de bord. Une valeur positive est en votre faveur.

« mtm_eur » vaut null quand la couverture ne peut pas être valorisée (donnée de marché manquante). Les TARF et accumulateurs se valorisent en bloc : leur valeur est dans « structures », par group_id.

Ces valorisations sont des références de négociation, pas des prix d'exécution.

Erreurs

Toute erreur rend le même objet : un code stable, à tester dans votre programme, et un message lisible.

• 400 invalid_body / invalid_parameter — corps ou paramètre illisible.
• 401 missing_key / invalid_key — clé absente, inconnue ou révoquée.
• 403 account_disabled — le compte n'a plus accès à ELEGG FX.
• 404 not_found — aucune ligne créée par l'API sous cette référence.
• 422 validation_failed — au moins une ligne refusée ; « details » les liste toutes, rien n'est écrit.
• 429 rate_limited — trop d'appels, réessayez dans un instant.
• 500 internal_error — écrivez-nous avec l'heure de l'appel.

{
  "error": {
    "code": "validation_failed",
    "message": "1 erreur(s) : aucune ligne n'a été enregistrée.",
    "details": [
      { "index": 0, "reference": "FAC-2026-0142", "field": "side",
        "message": "Sens obligatoire : « buy » … ou « sell » …" }
    ]
  }
}