---
title: "Calcul des impacts environnementaux d'un produit"
method: POST
path: "/{scope}/simulator"
tags: ["Générique"]
---

# Calcul des impacts environnementaux d'un produit

`POST /{scope}/simulator`

## Request

- Base URL: `https://ecobalyse.beta.gouv.fr/api`
- URL: `https://ecobalyse.beta.gouv.fr/api/{scope}/simulator`
- Auth: API key in header `token`

Calcule l'ensemble des impacts à partir d'une requête `GenericQuery`.
Le corps JSON est le même que celui exposé par l'onglet Partage du simulateur web
(composants catalogue et/ou composants personnalisés).

## Path parameters

- `scope` string, required

## Request body

- GenericQuery: Requête de simulation générique.
  - `components` GenericQueryItem[]: Liste des composants constituant le produit. Un composant du catalogue se référence par `id` (liste disponible sur `/{scope}/catalog`). Un composant personnalisé se décrit via `name` et `elements` à la racine de l'item (matières listées sur `/{scope}/processes/material`). L'objet imbriqué `custom` reste accepté.
    - `id` string, uuid: Identifiant d'un composant du catalogue (liste disponible sur `/{scope}/catalog`).
    - `quantity` integer, required: Nombre d'exemplaires de ce composant.
    - `unitMass` number: Masse unitaire finale du composant, en kilogrammes (optionnel) : - Si le champ est fourni, il est prioritaire sur la masse cumulée des éléments du composant ; - Si le champ est omis, la masse cumulée des éléments du composant est utilisée.
    - `name` string: Nom du composant personnalisé.
    - `elements` GenericQueryElement[]
      - `amount` number, required: Quantité de matière, exprimée dans l'unité du procédé matière (`unit` renvoyé par `/{scope}/processes/material`).
      - `material` union, required: Procédé localisé : UUID seul (pays d'origine par défaut), ou objet `{ "id", "country" }` pour mobiliser le mix énergétique du pays.
        - string, uuid: Identifiant du procédé (pays d'origine par défaut).
        - object
          - `id` string, uuid, required: Identifiant du procédé.
          - `country` string: Code pays de localisation (liste disponible sur `/{scope}/countries`).
      - `transforms` GenericQueryLocalizedProcess[]: Transformations successives de la matière (liste disponible sur `/{scope}/processes/transform/{materialType}`). Champ optionnel : l'omettre équivaut à une absence de transformation. Chaque entrée accepte un UUID seul ou un objet de forme `{ "id", "country" }`.
        - union: Procédé localisé : UUID seul (pays d'origine par défaut), ou objet `{ "id", "country" }` pour mobiliser le mix énergétique du pays.
          - string, uuid: Identifiant du procédé (pays d'origine par défaut).
          - object
            - `id` string, uuid, required: Identifiant du procédé.
            - `country` string: Code pays de localisation (liste disponible sur `/{scope}/countries`).
    - `scopes` string[]: Scopes associés.
  - `product` string, uuid: Identifiant de la catégorie de produit (liste disponible sur `/{scope}/categories`). Lorsque ce champ est fourni, ses valeurs par défaut s'appliquent aux champs suivants s'ils sont vides ou absents : - `assembly.operations` - `consumptions` - `distribution` - `transportOptions.cooling`
  - `assembly` GenericQueryAssembly
    - `country` string: Code pays d'assemblage (liste disponible sur `/{scope}/countries`).
    - `operations` string[]: Procédés d'assemblage (liste disponible sur `/{scope}/processes/assembly`). `[]` désactive explicitement les opérations par défaut de la catégorie.
  - `consumptions` GenericQueryConsumption[]: Liste des procédés de consommation à l'étape d'utilisation (liste disponible sur `/{scope}/processes/consumption`). Si omis, les consommations de la catégorie de produit sélectionnée s'appliquent. Un procédé dont l'entrée sera la masse du produit (catégorisé `productmassdependent`) s'identifie par un simple UUID (celui du procédé en question), sans quantité associée. Les autres types de procédés exigent que la quantité soit spécifiée (`{ "amount", "processId" }`).
    - union
      - string, uuid: Identifiant d'un procédé `productmassdependent` (sans `amount`).
      - object
        - `processId` string, uuid, required: Identifiant d'un procédé `productmassdependent` (sans `amount`).
      - object
        - `amount` number, required: Quantité exprimée dans l'unité du procédé. Interdit si le procédé est `productmassdependent` ; obligatoire sinon.
        - `processId` string, uuid, required: Identifiant du procédé.
  - `distribution` string, uuid: Identifiant du procédé de distribution (liste disponible sur `/{scope}/processes/distribution`). Si omis, le procédé de la catégorie de produit sélectionnée ou de la configuration du périmètre générique s'applique.
  - `durability` number: Coefficient de durabilité du produit. Ignoré (et rejeté) lorsque la durabilité n'est pas activée pour le périmètre générique actif.
  - `packagings` GenericQueryQuantifiedProcess[]: Emballages du produit (liste disponible sur `/{scope}/processes/packaging`).
    - `amount` number, required: Quantité exprimée dans l'unité du procédé (`unit` renvoyé par le point d'entrée catalogue correspondant).
    - `processId` string, uuid, required: Identifiant du procédé.
  - `recyclable` boolean: Produit recyclable (défaut `true`).
  - `transportOptions` GenericQueryTransportOptions
    - `byAir` number: Part de transport aérien vers la distribution, en pourcentage entre `0` et `100`.
    - `cooling` boolean: Transport réfrigéré vers la distribution. Si omis, la valeur de la catégorie de produit s'applique.

## Response `200`

Opération réussie

- GenericSimulatorResponse: Réponse du simulateur pour un périmètre générique.
  - `webUrl` string, required: URL vers la simulation dans l'interface web.
  - `score` GenericScore, required: Éléments du score en Pts d'impact : - `ecs` est le coût environnemental total en Pts d'impact, compléments hors ACV inclus - `complements` est la somme en Pts d'impact de tous les compléments hors ACV
    - `ecs` number, required: Score d'impact (Pts), compléments inclus
    - `complements` number, required: Somme des compléments hors ACV (en Pts). Une valeur négative **diminue** le coût environnemental.
  - `impacts` PhysicalImpacts, required: Catégories d'impacts physiques, dans leurs unités respectives. Ne contient pas de coûts agrégés comme `ecs`.
    - `acd` number: Acidification (mol éq. H+)
    - `cch` number: Changement climatique (kg éq. CO2)
    - `etf` number: Écotoxicité de l'eau douce (CTUe)
    - `etf-c` number: Écotoxicité de l'eau douce, corrigée (CTUe)
    - `fru` number: Utilisation de ressources fossiles (MJ)
    - `fwe` number: Eutrophisation eaux douces (kg éq. P)
    - `htc` number: Toxicité humaine - cancer (CTUh)
    - `htc-c` number: Toxicité humaine - cancer, corrigée (CTUh)
    - `htn` number: Toxicité humaine - non-cancer (CTUh)
    - `htn-c` number: Toxicité humaine - non-cancer, corrigée (CTUh)
    - `ior` number: Radiations ionisantes (éq. kBq U235)
    - `ldu` number: Utilisation des sols (sans dimension (pt))
    - `mru` number: Utilisation de ressources minérales et métalliques (kg éq. Sb)
    - `ozd` number: Appauvrissement de la couche d'ozone (kg éq. CFC 11)
    - `pco` number: Formation d'ozone photochimique (kg éq. COVNM)
    - `pma` number: Particules (incidence de maladie)
    - `swe` number: Eutrophisation marine (kg éq. N)
    - `tre` number: Eutrophisation terrestre (mol éq. N)
    - `wtu` number: Utilisation de ressources en eau (m³)
  - `productMass` number, required: Masse du produit fini, en kilogrammes.
  - `complements` GenericComplementPoints, required: Points d'impact (`ecs`) par complément, après application de la durabilité. Une clé absente signifie que ce complément ne s'applique pas. Une valeur négative **diminue** le coût environnemental.
    - `cropDiversity` number: Diversité culturale (Pts d'impact)
    - `forest` number: Forêt (Pts d'impact)
    - `hedges` number: Haies (Pts d'impact)
    - `microfibers` number: Microfibres (Pts d'impact)
    - `outOfEuropeEOL` number: Export hors Europe (Pts d'impact)
    - `permanentPasture` number: Prairies permanentes (Pts d'impact)
    - `plotSize` number: Taille des parcelles (Pts d'impact)
  - `subscores` GenericSubscores, required: Points d'impact (`ecs`) par sous-score, **après** application de la durabilité. Ces sous-scores sont recalculés à partir des indicateurs physiques. Leur somme peut différer de `score.ecs` d'une fraction de point.
    - `biodiversity` number, required: Biodiversité (Pts d'impact)
    - `climate` number, required: Climat (Pts d'impact)
    - `health` number, required: Santé environnementale (Pts d'impact)
    - `resources` number, required: Ressources (Pts d'impact)
    - `complements` number, required: Compléments (en Pts d'impact, une valeur négative **diminue** le score)
  - `stages` GenericStages, required: Coût environnemental en Pts d'impact (`ecs`) de chaque étape, après durabilité. Une étape sans impact vaut 0.
    - `materials` number, required: Matières premières (Pts d'impact), hors compléments
    - `transform` number, required: Transformation (Pts d'impact)
    - `assembly` number, required: Assemblage (Pts d'impact)
    - `packaging` number, required: Emballage (Pts d'impact)
    - `transports` number, required: Transports (Pts d'impact)
    - `distribution` number, required: Distribution (Pts d'impact)
    - `usage` number, required: Utilisation (Pts d'impact)
    - `endOfLife` number, required: Fin de vie (Pts d'impact)
  - `composition` GenericCompositionItem[], required: Impacts de composition du produit à **l'étape de production** uniquement, après application de la durabilité.
    - `id` string, uuid: Identifiant du composant catalogue. Absent pour un composant personnalisé
    - `name` string: Nom du composant.
    - `quantity` integer, required: Quantité demandée pour ce composant.
    - `mass` number, required: Masse de la ligne, en kilogrammes. La quantité est déjà appliquée : ne pas multiplier `mass` par `quantity`.
    - `score` GenericScore, required: Éléments du score en Pts d'impact : - `ecs` est le coût environnemental total en Pts d'impact, compléments hors ACV inclus - `complements` est la somme en Pts d'impact de tous les compléments hors ACV
      - `ecs` number, required: Score d'impact (Pts), compléments inclus
      - `complements` number, required: Somme des compléments hors ACV (en Pts). Une valeur négative **diminue** le coût environnemental.
    - `impacts` PhysicalImpacts, required: Catégories d'impacts physiques, dans leurs unités respectives. Ne contient pas de coûts agrégés comme `ecs`.
      - `acd` number: Acidification (mol éq. H+)
      - `cch` number: Changement climatique (kg éq. CO2)
      - `etf` number: Écotoxicité de l'eau douce (CTUe)
      - `etf-c` number: Écotoxicité de l'eau douce, corrigée (CTUe)
      - `fru` number: Utilisation de ressources fossiles (MJ)
      - `fwe` number: Eutrophisation eaux douces (kg éq. P)
      - `htc` number: Toxicité humaine - cancer (CTUh)
      - `htc-c` number: Toxicité humaine - cancer, corrigée (CTUh)
      - `htn` number: Toxicité humaine - non-cancer (CTUh)
      - `htn-c` number: Toxicité humaine - non-cancer, corrigée (CTUh)
      - `ior` number: Radiations ionisantes (éq. kBq U235)
      - `ldu` number: Utilisation des sols (sans dimension (pt))
      - `mru` number: Utilisation de ressources minérales et métalliques (kg éq. Sb)
      - `ozd` number: Appauvrissement de la couche d'ozone (kg éq. CFC 11)
      - `pco` number: Formation d'ozone photochimique (kg éq. COVNM)
      - `pma` number: Particules (incidence de maladie)
      - `swe` number: Eutrophisation marine (kg éq. N)
      - `tre` number: Eutrophisation terrestre (mol éq. N)
      - `wtu` number: Utilisation de ressources en eau (m³)
    - `complements` GenericComplementPoints, required: Points d'impact (`ecs`) par complément, après application de la durabilité. Une clé absente signifie que ce complément ne s'applique pas. Une valeur négative **diminue** le coût environnemental.
      - `cropDiversity` number: Diversité culturale (Pts d'impact)
      - `forest` number: Forêt (Pts d'impact)
      - `hedges` number: Haies (Pts d'impact)
      - `microfibers` number: Microfibres (Pts d'impact)
      - `outOfEuropeEOL` number: Export hors Europe (Pts d'impact)
      - `permanentPasture` number: Prairies permanentes (Pts d'impact)
      - `plotSize` number: Taille des parcelles (Pts d'impact)
  - `description` string: Une description de la simulation.
  - `query` GenericQuery, required: Requête de simulation générique.
    - `components` GenericQueryItem[]: Liste des composants constituant le produit. Un composant du catalogue se référence par `id` (liste disponible sur `/{scope}/catalog`). Un composant personnalisé se décrit via `name` et `elements` à la racine de l'item (matières listées sur `/{scope}/processes/material`). L'objet imbriqué `custom` reste accepté.
      - `id` string, uuid: Identifiant d'un composant du catalogue (liste disponible sur `/{scope}/catalog`).
      - `quantity` integer, required: Nombre d'exemplaires de ce composant.
      - `unitMass` number: Masse unitaire finale du composant, en kilogrammes (optionnel) : - Si le champ est fourni, il est prioritaire sur la masse cumulée des éléments du composant ; - Si le champ est omis, la masse cumulée des éléments du composant est utilisée.
      - `name` string: Nom du composant personnalisé.
      - `elements` GenericQueryElement[]
        - `amount` number, required: Quantité de matière, exprimée dans l'unité du procédé matière (`unit` renvoyé par `/{scope}/processes/material`).
        - `material` union, required: Procédé localisé : UUID seul (pays d'origine par défaut), ou objet `{ "id", "country" }` pour mobiliser le mix énergétique du pays.
          - string, uuid: Identifiant du procédé (pays d'origine par défaut).
          - object
            - `id` string, uuid, required: Identifiant du procédé.
            - `country` string: Code pays de localisation (liste disponible sur `/{scope}/countries`).
        - `transforms` GenericQueryLocalizedProcess[]: Transformations successives de la matière (liste disponible sur `/{scope}/processes/transform/{materialType}`). Champ optionnel : l'omettre équivaut à une absence de transformation. Chaque entrée accepte un UUID seul ou un objet de forme `{ "id", "country" }`.
          - union: Procédé localisé : UUID seul (pays d'origine par défaut), ou objet `{ "id", "country" }` pour mobiliser le mix énergétique du pays.
            - string, uuid: Identifiant du procédé (pays d'origine par défaut).
            - object
              - …
      - `scopes` string[]: Scopes associés.
    - `product` string, uuid: Identifiant de la catégorie de produit (liste disponible sur `/{scope}/categories`). Lorsque ce champ est fourni, ses valeurs par défaut s'appliquent aux champs suivants s'ils sont vides ou absents : - `assembly.operations` - `consumptions` - `distribution` - `transportOptions.cooling`
    - `assembly` GenericQueryAssembly
      - `country` string: Code pays d'assemblage (liste disponible sur `/{scope}/countries`).
      - `operations` string[]: Procédés d'assemblage (liste disponible sur `/{scope}/processes/assembly`). `[]` désactive explicitement les opérations par défaut de la catégorie.
    - `consumptions` GenericQueryConsumption[]: Liste des procédés de consommation à l'étape d'utilisation (liste disponible sur `/{scope}/processes/consumption`). Si omis, les consommations de la catégorie de produit sélectionnée s'appliquent. Un procédé dont l'entrée sera la masse du produit (catégorisé `productmassdependent`) s'identifie par un simple UUID (celui du procédé en question), sans quantité associée. Les autres types de procédés exigent que la quantité soit spécifiée (`{ "amount", "processId" }`).
      - union
        - string, uuid: Identifiant d'un procédé `productmassdependent` (sans `amount`).
        - object
          - `processId` string, uuid, required: Identifiant d'un procédé `productmassdependent` (sans `amount`).
        - object
          - `amount` number, required: Quantité exprimée dans l'unité du procédé. Interdit si le procédé est `productmassdependent` ; obligatoire sinon.
          - `processId` string, uuid, required: Identifiant du procédé.
    - `distribution` string, uuid: Identifiant du procédé de distribution (liste disponible sur `/{scope}/processes/distribution`). Si omis, le procédé de la catégorie de produit sélectionnée ou de la configuration du périmètre générique s'applique.
    - `durability` number: Coefficient de durabilité du produit. Ignoré (et rejeté) lorsque la durabilité n'est pas activée pour le périmètre générique actif.
    - `packagings` GenericQueryQuantifiedProcess[]: Emballages du produit (liste disponible sur `/{scope}/processes/packaging`).
      - `amount` number, required: Quantité exprimée dans l'unité du procédé (`unit` renvoyé par le point d'entrée catalogue correspondant).
      - `processId` string, uuid, required: Identifiant du procédé.
    - `recyclable` boolean: Produit recyclable (défaut `true`).
    - `transportOptions` GenericQueryTransportOptions
      - `byAir` number: Part de transport aérien vers la distribution, en pourcentage entre `0` et `100`.
      - `cooling` boolean: Transport réfrigéré vers la distribution. Si omis, la valeur de la catégorie de produit s'applique.

## Other responses

- `400`: Paramètres invalides
- `401`: Jeton d’API manquant ou invalide
- `403`: Accès refusé ; cela peut être dû à un scope désactivé sur cette instance, ou à un compte non autorisé (par exemple, accès réservé aux bêta-testeurs et superutilisateurs)
- `500`: Erreur irrécupérable du serveur

## Changes

- **2026-10-20** `53c2de0c8ef0`: 2 info
  - added the new optional request property `components/items/unitMass`
  - added the optional property `query/allOf[#/components/schemas/GenericQuery]/components/items/unitMass` to the response with the `200` status
- **2026-10-15** `811ec3300dbe`: 2 breaking, 18 warning, 18 info
  - the `impacts` response's property type changed from `object` to no type for status `200`
  - the `query` response's property type changed from `object` to no type for status `200`
  - removed the optional property `impacts/acd` from the response with the `200` status
  - removed the optional property `impacts/bvi` from the response with the `200` status
  - …34 more
- **2026-09-22** `c6595cf5feef`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/betagouv/apis/api-ecobalyse/changes/:scope/simulator/post.md)

---

[API](https://skmtc.dev/betagouv/apis/api-ecobalyse.md) - [All operations](https://skmtc.dev/betagouv/apis/api-ecobalyse/llms.txt) - [OpenAPI document](https://skmtc.dev/betagouv/apis/api-ecobalyse/revisions/53c2de0c8ef0?raw)