L'optimisation des achats génériques Margen, dans votre logiciel.

1 Obtenir une clé

1. Créez votre compte dans la console et confirmez votre e-mail.
2. Activation sous 24 h ouvrées : la console indique quand c'est fait.
3. Une fois validé, créez une clé de test mgn_test_…. Elle n'est affichée qu'une fois : copiez-la.

Vérifiez qu'elle fonctionne : la réponse indique votre offre et le quota restant.

export MARGEN_API_KEY=mgn_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl -sS https://public-api.margen.fr/v1/usage -H "Authorization: Bearer $MARGEN_API_KEY"

2 Vérifier vos CIP et trouver les labo_id

Facultatif mais recommandé avant le premier appel. Ces deux requêtes sont gratuites (hors quota).

# Vos CIP sont-ils connus ? (groupe générique, labo, PFHT en vigueur)
curl -sS "https://public-api.margen.fr/v1/reference/generics?cip=3400930000014,3400930000021" \
  -H "Authorization: Bearer $MARGEN_API_KEY"

# Identifiants des labos (labo_id), pour vos RSF et remises arrière
curl -sS https://public-api.margen.fr/v1/reference/labos -H "Authorization: Bearer $MARGEN_API_KEY"

{
  "object": "list",
  "data": [
    {
      "cip": "3400930000014",
      "label": "…",
      "gen_group_id": "…",
      "labo_id": 12,
      "labo": "…",
      "is_generic": true,
      "pfht_eur": 2.41
    }
  ],
  "not_found": ["3400930000021"]
}

3 Préparer la requête

Le minimum : vos achats. Ajoutez vos RSF pour un résultat réaliste. Enregistrez ce fichier sous optimize.json.

{
  "year": 2026,
  "purchases": [
    { "finess": "750000010", "cip": "3400930000014", "month": "2026-01", "qty": 120 },
    { "finess": "750000010", "cip": "3400930000014", "month": "2026-02", "qty": 98 },
    { "finess": "750000028", "cip": "3400930000021", "month": "2026-01", "qty": 40 }
  ],
  "rsf": [
    { "cip": "3400930000014", "rate_pct": 30 },
    { "cip": "3400930000021", "rate_pct": 22.5 },
    { "labo_id": 12, "rate_pct": 17 }
  ]
}

Les RSF : par CIP, par labo, groupement ou officine

• • cip + rate_pct : le taux négocié pour ce CIP. C'est le cas courant.
• • labo_id sans cip : taux par défaut pour tous les autres CIP de ce labo.
• • Sans finess, le taux vaut pour tout le groupement. Avec finess, il ne vaut que pour cette officine (avec "scope": "per_officine").
• • Si plusieurs taux s'appliquent, le plus précis gagne : officine + CIP, puis officine + labo, puis CIP, puis labo, sinon 0 %.
• • Taux variables dans l'année : ajoutez valid_from / valid_to (« AAAA-MM-JJ »).

Les remises arrière (facultatif)

Un programme par labo. Ici : 3 % jusqu'à 50 000 € d'achats (PFHT), 6 % au-delà. Ajoutez ce bloc au même niveau que purchases. Le plafond légal (RSF + remise arrière, art. L.138-9 CSS : 40 % pour les génériques en 2026, suivi année par année) est appliqué automatiquement.

"remises_arrieres": [
  {
    "labo_id": 12,
    "type": "threshold_bands",
    "tiers": [
      { "min_eur": 0,     "max_eur": 50000, "rate_pct": 3 },
      { "min_eur": 50000,                   "rate_pct": 6 }
    ]
  }
]

4 Lancer l'optimisation

Prefer: wait=60 demande d'attendre le résultat jusqu'à 60 secondes. Idempotency-Key évite d'être décompté deux fois si vous renvoyez la même requête.

curl -sS https://public-api.margen.fr/v1/optimize \
  -H "Authorization: Bearer $MARGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @optimize.json

# Réponse 202 ? Le calcul continue : interrogez le job jusqu'à "status": "succeeded"
curl -sS https://public-api.margen.fr/v1/jobs/JOB_ID -H "Authorization: Bearer $MARGEN_API_KEY"

5 Lire le résultat

Les montants sont en euros, nets de RSF et de remises arrière. Les valeurs ci-dessous sont illustratives.

{
  "object": "optimize_result",
  "year": 2026,
  "scope": "groupement",
  "summary": {
    "hist_effective_eur": 18240.50,
    "opt_effective_eur": 16912.10,
    "savings_eur": 1328.40,
    "savings_rate": 0.0728
  },
  "units": [
    {
      "finess": null,
      "by_gen_group": [
        {
          "gen_group_id": "…",
          "label": "…",
          "delta_eur": -412.30,
          "current":     [ { "cip": "3400930000021", "labo_id": 52, "qty": 1400, … } ],
          "recommended": [ { "cip": "3400930000014", "labo_id": 12, "qty": 1400, … } ]
        }
      ],
      "by_labo": [ … ]
    }
  ],
  "warnings": []
}

summary.savings_eur

Économie totale par rapport aux achats tels qu'ils ont été faits (net de RSF et remises arrière).

units[]

Un élément pour le groupement, ou un par officine en scope per_officine (finess renseigné).

by_gen_group[].to_buy

Ce qu'il faut acheter à partir de maintenant : CIP, labo et boîtes, pour les mois restants (année en cours) ou toute l'année (année suivante).

by_gen_group[].recommended

La répartition optimale sur l'année entière (mois déjà achetés inclus tels qu'achetés) ; current = les achats réels.

by_labo[]

Montants par labo, palier de remise arrière atteint et reste à acheter pour le palier suivant.

warnings[]

Points d'attention (CIP inconnus, lignes ignorées, plafond légal dépassé…).

Les résultats restent disponibles 7 jours sur GET /v1/jobs/{id} ; DELETE /v1/jobs/{id} les efface tout de suite.

Pour le montrer à un pharmacien : le générateur de rapport transforme un résultat en page imprimable par officine, à votre nom, dans le navigateur.

6 Optimiser l'année en cours ou la suivante

Le même appel POST /v1/optimize couvre trois cas, choisis avec mode. Quand l'année n'est pas terminée, Margen prévoit les volumes des mois restants à partir de votre historique et optimise sur l'année complète.

Chaque groupe générique indique alors ce qui est déjà acheté (purchased_qty), ce qui est prévu (forecast_qty) et le détail par mois (forecast_months) : qty = purchased_qty + forecast_qty. to_buy donne les CIP à acheter pour ces mois restants (toute l'année en forecast_next). Une prévision marquée "forecast_confidence": "limited" repose sur un historique court (moins de 14 mois) : envoyez 24 mois d'historique quand c'est possible.

"units": [
  {
    "last_data_month": 9,
    "forecast_from": "2026-10",
    "by_gen_group": [
      {
        "gen_group_id": "…",
        "qty": 1480,
        "purchased_qty": 1110,
        "forecast_qty": 370,
        "forecast_confidence": "standard",
        "forecast_months": [
          { "month": "2026-10", "qty": 124 },
          { "month": "2026-11", "qty": 121 },
          { "month": "2026-12", "qty": 125 }
        ],
        "to_buy": [
          { "cip": "3400930000014", "labo_id": 12, "qty": 370, "months": [10, 11, 12], … }
        ],
        "recommended": [ … ]
      }
    ]
  }
]

Erreurs

Toujours le même format : { "error": { "type", "code", "message", "rows" }, "request_id" }. Donnez le request_id au support si besoin.

Liste complète dans la référence de l'API (openapi.yaml).

Unités et limites

Une optimisation = un calcul (un par officine en per_officine). Les calculs en échec ou annulés ne sont pas décomptés. En Sandbox : 20 optimisations par mois, 10 officines par requête, 2 calculs en parallèle. Les clés de test gardent ces limites sur toutes les offres ; les clés live suivent celles de votre offre (tarifs).