openapi: 3.0.1
info:
  title: API Ecobalyse
  description: L'API HTTP Ecobalyse permet de calculer les impacts environnementaux des produits textiles et alimentaires.
  version: 0.0.1-alpha
externalDocs:
  description: Visiter le site
  url: https://ecobalyse.beta.gouv.fr
servers:
  - url: https://ecobalyse.beta.gouv.fr/api
tags:
  - name: Commun
    description: Documentation de l'API multi-domaines au format OpenAPI
    externalDocs:
      description: À propos
      url: https://fabrique-numerique.gitbook.io/ecobalyse
  - name: Textile
    description: Documentation de l'API pour le domaine textile au format OpenAPI
    externalDocs:
      description: À propos
      url: https://fabrique-numerique.gitbook.io/ecobalyse
  - name: Alimentaire
    description: |
      Documentation de l'API pour le domaine alimentaire au format OpenAPI

      **⚠️ En construction, les résultats fournis sont incomplets et probablement invalides.**
    externalDocs:
      description: À propos
      url: https://fabrique-numerique.gitbook.io/ecobalyse
paths:
  /:
    get:
      tags:
        - Commun
      summary: Documentation OpenAPI de l'API
      description: Sert la documentation de l'API au format [OpenAPI](https://swagger.io/specification/)
      responses:
        200:
          description: Documentation de l'API au format OpenAPI.
  /textile/countries:
    get:
      tags:
        - Textile
      summary: Liste des pays utilisables pour les simulations textiles.
      responses:
        200:
          description: Opération réussie
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CountryListResponse"
  /textile/materials:
    get:
      tags:
        - Textile
      summary: Liste des matières textile
      responses:
        200:
          description: Opération réussie
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MaterialListResponse"
  /textile/products:
    get:
      tags:
        - Textile
      summary: Liste des types de produits textiles
      responses:
        200:
          description: Opération réussie
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductListResponse"
  /textile/simulator:
    get:
      tags:
        - Textile
      summary: Calcul des impacts environnementaux d'un produit textile
      parameters:
        - $ref: "#/components/parameters/massParam"
        - $ref: "#/components/parameters/materialsParam"
        - $ref: "#/components/parameters/productParam"
        - $ref: "#/components/parameters/countrySpinningParam"
        - $ref: "#/components/parameters/countryFabricParam"
        - $ref: "#/components/parameters/countryDyeingParam"
        - $ref: "#/components/parameters/countryMakingParam"
        - $ref: "#/components/parameters/fabricProcessParam"
        - $ref: "#/components/parameters/airTransportRatioParam"
        - $ref: "#/components/parameters/qualityParam"
        - $ref: "#/components/parameters/reparabilityParam"
        - $ref: "#/components/parameters/makingWasteParam"
        - $ref: "#/components/parameters/makingComplexityParam"
        - $ref: "#/components/parameters/yarnSizeParam"
        - $ref: "#/components/parameters/surfaceMassParam"
        - $ref: "#/components/parameters/fadingParam"
        - $ref: "#/components/parameters/disabledStepsParam"
        - $ref: "#/components/parameters/ennoblingHeatSourceParam"
        - $ref: "#/components/parameters/dyeingMediumParam"
        - $ref: "#/components/parameters/printingParam"
      responses:
        200:
          description: Opération réussie
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericImpactsResponse"
        400:
          description: Paramètres invalides
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidParametersError"
    post:
      tags:
        - Textile
      summary: Calcul des impacts environnementaux d'un produit textile
      requestBody:
        description: Requête modélisant les paramètres du produit à évaluer
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TextileQuery"
            examples:
              tShirtFrance:
                $ref: "#/components/examples/tShirtFrance"
              tShirtChina:
                $ref: "#/components/examples/tShirtChina"
      responses:
        200:
          description: Opération réussie
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericImpactsResponse"
        400:
          description: Paramètres invalides
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidParametersError"
  /textile/simulator/{impact}:
    get:
      tags:
        - Textile
      summary: Calcul d'un impact environnemental spécifique d'un produit textile
      parameters:
        - $ref: "#/components/parameters/impactUrlParam"
        - $ref: "#/components/parameters/massParam"
        - $ref: "#/components/parameters/materialsParam"
        - $ref: "#/components/parameters/productParam"
        - $ref: "#/components/parameters/countrySpinningParam"
        - $ref: "#/components/parameters/countryFabricParam"
        - $ref: "#/components/parameters/countryDyeingParam"
        - $ref: "#/components/parameters/countryMakingParam"
        - $ref: "#/components/parameters/fabricProcessParam"
        - $ref: "#/components/parameters/airTransportRatioParam"
        - $ref: "#/components/parameters/qualityParam"
        - $ref: "#/components/parameters/reparabilityParam"
        - $ref: "#/components/parameters/makingWasteParam"
        - $ref: "#/components/parameters/makingComplexityParam"
        - $ref: "#/components/parameters/yarnSizeParam"
        - $ref: "#/components/parameters/surfaceMassParam"
        - $ref: "#/components/parameters/fadingParam"
        - $ref: "#/components/parameters/disabledStepsParam"
        - $ref: "#/components/parameters/ennoblingHeatSourceParam"
        - $ref: "#/components/parameters/dyeingMediumParam"
        - $ref: "#/components/parameters/printingParam"
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SingleImpactResponse"
        400:
          description: Paramètres invalides
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidParametersError"
    post:
      tags:
        - Textile
      summary: Calcul des impacts environnementaux d'un produit textile
      parameters:
        - $ref: "#/components/parameters/impactUrlParam"
      requestBody:
        description: Requête modélisant les paramètres du produit à évaluer
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TextileQuery"
            examples:
              tShirtFrance:
                $ref: "#/components/examples/tShirtFrance"
              tShirtChina:
                $ref: "#/components/examples/tShirtChina"
      responses:
        200:
          description: Opération réussie
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenericImpactsResponse"
        400:
          description: Paramètres invalides
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidParametersError"
  /textile/simulator/detailed:
    get:
      tags:
        - Textile
      summary: Calcul exhaustif des impacts environnementaux d'un produit textile
      description: L'intégralité des calculs intermédiaires sont présentés dans une réponse détaillée
      parameters:
        - $ref: "#/components/parameters/massParam"
        - $ref: "#/components/parameters/materialsParam"
        - $ref: "#/components/parameters/productParam"
        - $ref: "#/components/parameters/countrySpinningParam"
        - $ref: "#/components/parameters/countryFabricParam"
        - $ref: "#/components/parameters/countryDyeingParam"
        - $ref: "#/components/parameters/countryMakingParam"
        - $ref: "#/components/parameters/fabricProcessParam"
        - $ref: "#/components/parameters/airTransportRatioParam"
        - $ref: "#/components/parameters/qualityParam"
        - $ref: "#/components/parameters/reparabilityParam"
        - $ref: "#/components/parameters/makingWasteParam"
        - $ref: "#/components/parameters/makingComplexityParam"
        - $ref: "#/components/parameters/yarnSizeParam"
        - $ref: "#/components/parameters/surfaceMassParam"
        - $ref: "#/components/parameters/fadingParam"
        - $ref: "#/components/parameters/disabledStepsParam"
        - $ref: "#/components/parameters/ennoblingHeatSourceParam"
        - $ref: "#/components/parameters/dyeingMediumParam"
        - $ref: "#/components/parameters/printingParam"
      responses:
        200:
          description: Opération réussie
          content:
            application/json:
              schema:
                type: object
        400:
          description: Paramètres invalides
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidParametersError"
    post:
      tags:
        - Textile
      summary: Calcul des impacts environnementaux d'un produit textile
      requestBody:
        description: Requête modélisant les paramètres du produit à évaluer
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TextileQuery"
            examples:
              tShirtFrance:
                $ref: "#/components/examples/tShirtFrance"
              tShirtChina:
                $ref: "#/components/examples/tShirtChina"
      responses:
        200:
          description: Opération réussie
          content:
            application/json:
              schema:
                type: object
        400:
          description: Paramètres invalides
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidParametersError"
  /food/countries:
    get:
      tags:
        - Alimentaire
      summary: Liste des pays utilisables pour les simulations alimentairess.
      responses:
        200:
          description: Opération réussie
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CountryListResponse"
  /food/ingredients:
    get:
      tags:
        - Alimentaire
      summary: Liste des ingrédients disponibles pour élaborer une recette
      responses:
        200:
          description: Opération réussie
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IngredientListResponse"
  /food/transforms:
    get:
      tags:
        - Alimentaire
      summary: Liste des procédés de transformation alimentaire
      responses:
        200:
          description: Opération réussie
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransformListResponse"
  /food/packagings:
    get:
      tags:
        - Alimentaire
      summary: Liste des emballages disponibles pour conditionner une recette
      responses:
        200:
          description: Opération réussie
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PackagingListResponse"
  /food/recipe:
    get:
      tags:
        - Alimentaire
      summary: Calcul des impacts environnementaux d'une recette alimentaire
      parameters:
        - $ref: "#/components/parameters/ingredientsParam"
        - $ref: "#/components/parameters/transformParam"
        - $ref: "#/components/parameters/packagingParam"
        - $ref: "#/components/parameters/distributionParam"
        - $ref: "#/components/parameters/preparationParam"
      responses:
        200:
          description: Opération réussie
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecipeResultsResponse"
        400:
          description: Paramètres invalides
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidParametersError"
    post:
      tags:
        - Alimentaire
      summary: Calcul des impacts environnementaux d'une recette alimentaire
      requestBody:
        description: Requête modélisant les éléments de la recette à évaluer
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FoodQuery"
            examples:
              CarrotCake:
                summary: "Carrot cake conventionnel"
                value:
                  ingredients:
                  - id: egg
                    mass: 120
                  - id: wheat
                    mass: 140
                  - id: milk
                    mass: 60
                  - id: carrot
                    mass: 225
                  transform:
                    code: AGRIBALU000000003103966
                    mass: 545
                  packaging:
                  - code: AGRIBALU000000003104019
                    mass: 105
                  distribution: ambient
                  preparation:
                  - refrigeration
              SpanishOrganicCarrotCake:
                summary: "Carrot cake bio, origine Espagne"
                value:
                  ingredients:
                  - id: egg-organic
                    mass: 120
                    country: ES
                  - id: wheat-organic
                    mass: 140
                    country: ES
                  - id: milk-organic
                    mass: 60
                    country: ES
                  - id: carrot-organic
                    mass: 225
                    country: ES
                  transform:
                    code: AGRIBALU000000003103966
                    mass: 545
                  packaging:
                  - code: AGRIBALU000000003104019
                    mass: 105
                  distribution: ambient
                  preparation:
                  - refrigeration
              BrazilianMango:
                summary: "Mangue du Brésil"
                value:
                  ingredients:
                  - id: mango
                    mass: 500
                    country: BR
                  transform: null
                  packaging: []
                  distribution: ambient
                  preparation: []
              CustomBonuses:
                summary: "Œuf bio France, bonus spécifiques"
                value:
                  ingredients:
                  - id: egg
                    mass: 100
                    country: FR
                    bonuses:
                      agro-diversity: 30
                      agro-ecology: 60
                      animal-welfare: 90
                  transform: null
                  packaging: []
                  distribution: ambient
                  preparation: []
      responses:
        200:
          description: Opération réussie
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecipeResultsResponse"
        400:
          description: Paramètres invalides
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvalidParametersError"
components:
  examples:
    tShirtFrance:
      summary: "T-Shirt France 100% Coton"
      value:
        mass: 0.17
        materials:
        - id: "coton"
          share: 1
          country: "FR"
        product: "tshirt"
        countrySpinning: "FR"
        countryFabric: "FR"
        countryDyeing: "FR"
        countryMaking: "FR"
    tShirtChina:
      summary: "T-Shirt Chine, low-cost, 100% Coton"
      value:
        mass: 0.17
        materials:
        - id: "coton"
          share: 1
        product: "tshirt"
        countrySpinning: "CN"
        countryFabric: "CN"
        countryDyeing: "CN"
        countryMaking: "CN"
        airTransportRatio: 0.33
        quality: 0.9
        reparability: 0.9
        makingWaste: null
        makingComplexity: null
        yarnSize: null
        surfaceMass: null
        fabricProcess: "knitting-mix"
        disabledSteps:
        - use
  parameters:
    impactUrlParam:
      name: impact
      in: path
      description: |
        Trigramme de l'impact étudié ([la liste est documenté ici](https://fabrique-numerique.gitbook.io/ecobalyse/methodologie/impacts-consideres))
      required: true
      schema:
        type: string
        minLength: 3
        maxLength: 3
        default: "cch"
        enum:
          - "acd"
          - "bvi"
          - "cch"
          - "ecs"
          - "etf"
          - "fru"
          - "fwe"
          - "htc"
          - "htn"
          - "ior"
          - "ldu"
          - "mru"
          - "ozd"
          - "pco"
          - "pef"
          - "pma"
          - "swe"
          - "tre"
          - "wtu"
    massParam:
      name: mass
      in: query
      description: Masse du produit fini, **exprimée en kilogrammes**
      required: true
      style: form
      schema:
        type: number
        minimum: 0.01
      example: 0.17
    materialsParam:
      name: "materials[]"
      in: query
      description: |
        Liste des matières composant le produit (liste disponible sur le point d'entrée `/textile/materials`).
        Le format de chaque entrée est composé de l'identifiant de la matière et de la part du produit
        qu'elle représente, optionnellement du [procédé de filature ou filage pour la matière](https://fabrique-numerique.gitbook.io/ecobalyse/textile/etapes-du-cycle-de-vie/etape-2-fabrication-du-fil-new-draft#hypotheses-par-defaut), et optionnellement du code du pays d'origine de la matière :

        - `coton;0.3` signifie *30% coton*;
        - `coton-rdp;0.7` signifie *70% coton recyclé (déchets de production)*;
        - `coton;0.3;UnconventionalSpinning` signifie *30% coton avec un procédé de filature non conventionel*
        - `coton;0.3;UnconventionalSpinning;FR` signifie *30% coton avec un procédé de filature non conventionel en provenance de France*
        - `coton;0.3;;FR` signifie *30% coton avec un procédé de filature par défaut en provenance de France*

        > Par exemple, les paramètres à passer pour un t-shirt 30% coton, 30% coton recyclé et 40% acrylique sont :
        >
        > ```js
        > materials[]=coton;0.3&materials[]=coton-rdp;0.3&materials[]=acrylique;0.4
        > ```

        Le procédé de filature ou filage est à choisir entre :
        - `ConventionalSpinning` : filature conventionnelle (à anneaux : ring spun) pour les matières naturelles ou artificielles
        - `UnconventionalSpinning` : filature non conventionnelle (à bouts libérées : open-end) pour les matières naturelles ou artificielles
        - `SyntheticSpinning` : filage pour les matières synthétiques
      required: true
      style: form
      schema:
        type: array
        items:
          type: string
      examples:
        coton:
          value: ["coton;1"]
        acrylique:
          value: ["coton;0.7", "acrylique;0.3"]
        mixed:
          value: ["coton;0.3", "coton-rdp;0.3", "acrylique;0.4"]
        spinning:
          value: ["coton;0.96;UnconventionalSpinning"]
    productParam:
      name: product
      in: query
      description: Identifiant du produit (liste disponible sur le point d'entrée `/textile/products`)
      required: true
      style: form
      schema:
        type: string
      examples:
        tshirt:
          value: "tshirt"
        pantalon:
          value: "pantalon"
    countrySpinningParam:
      name: countrySpinning
      in: query
      description: |
        Code pays pour l'étape de **Filature** (liste disponible sur le point d'entrée `textile/countries`).
        Si non spécifié, le pays de filature pris en considération est celui de production de
        la matière la plus représentée dans le mix.
      required: false
      style: form
      schema:
        type: string
        minLength: 2
        maxLength: 2
      examples:
        Default:
          value: ""
        Chine:
          value: "CN"
        France:
          value: "FR"
    countryFabricParam:
      name: countryFabric
      in: query
      description: |
        Code pays pour l'étape de **Tissage/Tricotage** (liste disponible sur le point d'entrée `textile/countries`)
      required: true
      style: form
      schema:
        type: string
        minLength: 2
        maxLength: 2
      examples:
        Chine:
          value: "CN"
        France:
          value: "FR"
    countryDyeingParam:
      name: countryDyeing
      in: query
      description: "Code pays pour l'étape de **Teinture** (liste disponible sur le point d'entrée `textile/countries`)"
      required: true
      style: form
      schema:
        type: string
        minLength: 2
        maxLength: 2
      examples:
        Chine:
          value: "CN"
        France:
          value: "FR"
    countryMakingParam:
      name: countryMaking
      in: query
      description: "Code pays pour l'étape de **Confection** (liste disponible sur le point d'entrée `textile/countries`)"
      required: true
      style: form
      schema:
        type: string
        minLength: 2
        maxLength: 2
      examples:
        Chine:
          value: "CN"
        France:
          value: "FR"
    airTransportRatioParam:
      name: airTransportRatio
      in: query
      description: |
        Part de **transport aérien** entre l'étape de **Confection** et l'étape de **Distribution**, entre `0` et `1`
      required: false
      style: form
      schema:
        type: number
        minimum: 0
        maximum: 1
    qualityParam:
      name: quality
      in: query
      description: |
        Qualité intrinsèque du produit. Le coefficient de qualité intrinsèque représente à quel point
        le produit va durer dans le temps. Il varie entre 0.67 (peu durable) et 1.45 (très durable).
        Il est calculé à partir du résultat d’une série de tests de durabilité. Il est utilisé en
        coefficient multiplicateur du nombre de jours d’utilisation du produit.
      required: false
      style: form
      schema:
        type: number
        minimum: 0.67
        maximum: 1.45
    reparabilityParam:
      name: reparability
      in: query
      description: |
        Indice de réparabilité du produit. Il varie entre `1.00` (peu réparable) et `1.15` (très réparable).
        Il est utilisé en coefficient multiplicateur du nombre de jours d’utilisation du produit.
      required: false
      style: form
      schema:
        type: number
        minimum: 1
        maximum: 1.15
    makingWasteParam:
      name: makingWaste
      in: query
      description: |
        Taux de perte en confection (incluant la découpe), entre `0` et `0.4`.

        **⚠️ Sur les produits tricotés en "fully fashioned / seamless", ce paramètre n'a aucun impact (valeur fixe: 0.02).**

        **⚠️ Sur les produits tricotés en "integral / whole garment", ce paramètre n'a aucun impact (valeur fixe: 0).**
      required: false
      style: form
      schema:
        type: number
        minimum: 0
        maximum: 0.4
    makingComplexityParam:
      name: makingComplexity
      in: query
      description: |
        Complexité de la confection, parmi la liste de choix suivants :
          - `very-high` : très élevée
          - `high` : élevée
          - `medium` : moyenne
          - `low` : faible
          - `very-low` : très faible

        **⚠️ Sur les produits tricotés en "fully fashioned / seamless", ce paramètre n'a aucun impact (valeur fixe: very-low).**

        **⚠️ Sur les produits tricotés en "integral / whole garment", ce paramètre n'a aucun impact (valeur fixe: vide, non applicable).**
      required: false
      style: form
      schema:
        type: string
        enum: ["very-high", "high", "medium", "low", "very-low"]
    yarnSizeParam:
      name: yarnSize
      in: query
      description: |
        Titrage du fil exprimé en **numéro métrique** (`Nm`).
        Il est aussi possible de l'exprimer en décitex (`Dtex`) en spécifiant l'unité.
        Exemples de saisie :
          - `40` : 40Nm
          - `40Nm` : 40Nm
          - `250Dtex` : 250Dtex, équivalent à 40Nm
      required: false
      style: form
      schema:
        type: string
        minimum: 9
        maximum: 200
    fabricProcessParam:
      name: fabricProcess
      in: query
      description: |
        Le processus utilisé pour tisser ou tricoter le tissu, parmi la liste de choix suivants :
          - `knitting-mix` : Tricotage moyen (mix de métiers circulaire & rectiligne)
          - `knitting-fully-fashioned` : Tricotage fully-fashioned / seamless
          - `knitting-integral` : Tricotage intégral / whole garment
          - `knitting-circular` : Tricotage circulaire, inventaire désagrégé
          - `knitting-straight` : Tricotage rectiligne, inventaire désagrégé
          - `weaving`  : Tissage
      required: true
      style: form
      schema:
        type: string
        enum:
          "$ref": "#/components/schemas/FabricProcessEnum"
      examples:
        knitting-mix:
          value: "knitting-mix"
        knitting-fully-fashioned:
          value: "knitting-fully-fashioned"
        knitting-integral:
          value: "knitting-integral"
        knitting-circular:
          value: "knitting-circular"
        knitting-straight:
          value: "knitting-straight"
        weaving:
          value: "weaving"
    surfaceMassParam:
      name: surfaceMass
      in: query
      description: |
        Le grammage de l'étoffe, exprimé en gr/m², représente sa masse surfacique.

        **⚠️ Sur les produits tricotés, ce paramètre n'impacte que l'impression.**
      required: false
      style: form
      schema:
        type: number
        minimum: 80
        maximum: 500
    fadingParam:
      name: fading
      in: query
      description: |
        Active l'application du **procédé de délavage** pour l'étape de confection d'un produit.
      required: false
      style: form
      schema:
        type: string
        enum: ["true", "false"]
      examples:
        default:
          value: ""
        enabled:
          value: "true"
        disabled:
          value: "false"
    disabledStepsParam:
      name: disabledSteps
      in: query
      description: |
        Liste des étapes du cycle de vie à désactiver, séparée par des virgules. Chaque étape est identifiée par un code :

        - `material`: Matière
        - `spinning`: Filature
        - `fabric`: Tissage ou Tricotage
        - `ennobling`: Ennoblissement (incluant le pré-traitement, la teinture et la finition)
        - `making`: Confection
        - `distribution`: Distribution
        - `use`: Utilisation
        - `eol`: Fin de vie

        Par exemple, pour désactiver l'étape de filature ainsi que celle d'ennoblissement, on peut passer `disabledSteps=spinning,ennobling`.
      required: false
      style: form
      schema:
        type: string
      examples:
        default:
          summary: "Aucune étape désactivée"
          value: ""
        making:
          summary: "Confection desactivée"
          value: "making"
        spinningDyeing:
          summary: "Filature et ennoblissement désactivés"
          value: "spinning,ennobling"
    ennoblingHeatSourceParam:
      name: ennoblingHeatSource
      in: query
      description: |
        Ce paramètre permet de préciser la source de chaleur à l'étape d'ennoblissement ; il peut prendre les valeurs
        suivantes :

        - `coal`: Vapeur à partir de Charbon
        - `naturalgas`: Vapeur à partir de Gaz naturel
        - `lightfuel`: Vapeur à partir de Fioul léger
        - `heavyfuel`: Vapeur à partir de Fioul lourd

        ⚠️ En l'absence d'utilisation explicite du paramètre, la source de chaleur utilisée sera celle du mix régional.
      required: false
      style: form
      schema:
        type: string
      examples:
        default:
          summary: "par défaut, mix régional"
          value: ""
        coal:
          summary: "Charbon"
          value: "coal"
        naturalGas:
          summary: "Gaz naturel"
          value: "naturalgas"
        lightfuel:
          summary: "Fuel léger"
          value: "lightfuel"
        heavyfuel:
          summary: "Fuel lourd"
          value: "heavyfuel"
    dyeingMediumParam:
      name: dyeingMedium
      in: query
      description: |
        Ce paramètre permet de préciser le support sur lequel s'effectue la teinture ; il peut prendre les valeurs
        suivantes :

        - `article` lorsque la teinture est effectuée sur l'article ;
        - `fabric` lorsqu'elle est effectuée sur le tissu ;
        - `yarn` lorsqu'elle est effectuée sur le fil.

        ⚠️ En l'absence d'utilisation explicite du paramètre, le support de teinture utilisé sera celui affecté par
        défaut à la famille de produit.
      required: false
      style: form
      schema:
        type: string
      examples:
        default:
          summary: "par défaut, sur tissu"
          value: ""
        surArticle:
          summary: "sur article"
          value: "article"
        surTissu:
          summary: "sur tissu"
          value: "fabric"
        surFil:
          summary: "sur fil"
          value: "yarn"
    printingParam:
      name: printing
      in: query
      description: |
        Ce paramètre permet de préciser le type d'impression effectuée sur le produit, suivi du pourcentage de
        surface teinte. Par exemple, `pigment;0.1` signifie impression pigmentaire sur 10% de la superficie du
        vêtement. L'identifiant de procédé d'impression peut prendre les valeurs suivantes :

        - `pigment` pour une impression pigmentaire ;
        - `substantive` pour une impression fixé/lavé ;
      required: false
      style: form
      schema:
        type: string
      examples:
        default:
          summary: "Aucune impression"
          value: ""
        pigment:
          summary: "Pigmentaire sur 50% de la surface"
          value: "pigment;0.5"
        substantive:
          summary: "Fixé/Lavé sur 20% de la surface"
          value: "substantive;0.2"
    ingredientsParam:
      name: "ingredients[]"
      in: query
      description: |
        Liste des ingrédients composant la recette (liste disponible sur le point d'entrée `/food/ingredients`).
        Le format de chaque entrée est composé de :

        - l'identifiant de la matière (pour avoir la liste, utiliser l'API de liste d'ingrédients)
        - sa masse **exprimée en grammes**
        - un éventuel code de pays d'origine (ex: `BR` pour le Brésil)
        - un éventuel transport par avion *uniquement si c'est un [ingrédient de catégorie
          "HORS EUROPE-MAGHREB (AVION)"](https://fabrique-numerique.gitbook.io/ecobalyse/alimentaire/transport#circuits-consideres)*
          (valeurs possible: `<vide>`, `byPlane`, `noPlane`)
        - d'éventuels bonus à appliquer, sous la forme `50:75:33`, signifiant:
          * 50% de bonus diversité agricole
          * 75% de bonus infrastructures agro-écologiques
          * 33% de bonus conditions d'élevage (si applicable pour l'ingrédient sélectionné)

        Quelques exemples :

        - `milk;268` signifie *268g de lait*;
        - `tomato;123;ES` signifie *123g de tomates conventionnelles en provenance d'Espagne*;
        - `mango;123` signifie *123g de mangues en provenance de son origine par défaut (hors Europe-Maghreb, transport par avion)*;
        - `mango;123;;noPlane` signifie *123g de mangues en provenance de son origine par défaut (hors Europe-Maghreb), par bateau*;
        - `mango;123;BR` signifie *123g de mangues en provenance du Brésil, par avion*;
        - `mango;123;BR;byPlane` signifie de la même manière *123g de mangues en provenance du Brésil, par avion*;
        - `mango;123;BR;noPlane` signifie *123g de mangues en provenance du Brésil, par bateau (pas par avion)*;
        - `tomato;123;ES;;50:20` signifie *123g de tomates conventionnelles en provenance d'Espagne avec 50% de bonus pour la diversité agricole et 75% de bonus pour les infrastructures agro-écologiques*;

        > Par exemple, les paramètres à passer pour une recette à base de 268g de lait et 30g de carrotes bio d'espagne sont :
        >
        > ```js
        > ingredients[]=milk;268&ingredients[]=carrot-organic;30;ES
        > ```
      required: true
      style: form
      schema:
        type: array
        items:
          type: string
      examples:
        oneIngredient:
          summary: Lait
          value: ["milk;268"]
        twoIngredients:
          summary: Lait, carrotes bio
          value: ["milk;268", "carrot-organic;30"]
        threeIngredients:
          summary: Lait, carrotes bio, oeuf
          value: ["milk;268", "carrot-organic;30", "egg;149"]
        fourIngredients:
          summary: Lait, carrotes bio, oeuf, tomates d'espagne
          value: ["milk;268", "carrot-organic;30", "egg;149", "tomato;123;;ES"]
        byPlane:
          summary: Mangue du Brésil par avion
          value: ["mango;123;;BR"]
        noPlane:
          summary: Mangue du Brésil par bateau
          value: ["mango;123;;BR;noPlane"]
    packagingParam:
      name: "packaging[]"
      in: query
      description: |
        Liste des emballages composant la recette (liste disponible sur le point d'entrée `/food/packaging`).

        Le format de chaque entrée est composé de l'identifiant de l'emballage et de sa masse **exprimée en grammes**.
      required: true
      style: form
      schema:
        type: array
        items:
          type: string
      examples:
        onePackaging:
          summary: "105g de Carton"
          value: ["AGRIBALU000000003104019;105"]
    transformParam:
      name: transform
      in: query
      description: |
        Identifiant du procédé de transformation (optionnel — liste disponible sur le point d'entrée `/food/transforms`)

        Le format est composé de l'identifiant de l'emballage et de sa masse **exprimée en grammes**.
        Par exemple: `AGRIBALU000000003103966;1000` pour 1kg de matière à cuire.
      required: false
      style: form
      schema:
        type: string
        minLength: 32
        maxLength: 32
      examples:
        Default:
          summary: "Aucune transformation"
          value: ""
        Cuisson:
          summary: Cuisson d'1kg de matière
          value: "AGRIBALU000000003103966;1000"
    distributionParam:
      name: distribution
      in: query
      description: |
        Choix du mode de stockage chez le distributeur, parmi ces valeurs possibles :

        - `ambient`: Température ambiante (valeur par défaut)
        - `fresh`: Réfrigéré
        - `frozen`: Congelé

        La distribution inclut 450km de transport terrestre vers le site de stockage + 150km vers le site de distribution.

      required: false
      style: form
      schema:
        type: string
        description: Type de distribution chez le distributeur
        enum:
          - "ambient"
          - "fresh"
          - "frozen"
      examples:
        ambient:
          summary: "Température ambiante"
          value: "ambient"
        fresh:
          summary: "Réfrigéré"
          value: "fresh"
        frozen:
          summary: "Congelé"
          value: "frozen"
    preparationParam:
      name: preparation[]
      in: query
      description: |
        Liste des techniques de préparation mobilisées **à l'étape de consommation** :

        - `frying`: Friture
        - `pan-cooking`: Cuisson à la poêle
        - `pan-warming`: Réchauffage à la poêle
        - `oven`: Cuisson au four
        - `microwave`: Cuisson au four micro-ondes
        - `refrigeration`: Réfrigération
        - `freezing`: Congélation

        **Un maximum de deux techniques de préparation est autorisé.**
      required: false
      style: form
      schema:
        type: array
        items:
          type: string
          enum:
            - "freezing"
            - "frying"
            - "microwaves"
            - "oven"
            - "pan-cooking"
            - "pan-warming"
            - "refrigeration"
        maxItems: 2
        description: Liste d'identifiants de techniques de préparation.
      examples:
        Default:
          summary: "Sans préparation"
          value: ""
        frying:
          summary: Friture
          value: frying
        freezing:
          summary: Congélation
          value: freezing
        freezingAndOven:
          summary: Congélation et cuisson au four
          value: ["freezing", "oven"]
  schemas:
    Impacts:
      type: object
      properties:
        acd:
          type: number
          description: "Acidification (mol éq. H+)"
        bvi:
          type: number
          description: "Biodiversité locale (BVI)"
        cch:
          type: number
          description: "Changement climatique (kg éq. CO2)"
        ecs:
          type: number
          description: "Score d'impacts (µPts d'impact)"
        etf:
          type: number
          description: "Écotoxicité de l'eau douce (CTUe)"
        fru:
          type: number
          description: "Utilisation de ressources fossiles (MJ)"
        fwe:
          type: number
          description: "Eutrophisation eaux douces (kg éq. P)"
        htc:
          type: number
          description: "Toxicité humaine - cancer (CTUh)"
        htn:
          type: number
          description: "Toxicité humaine - non-cancer (CTUh)"
        ior:
          type: number
          description: "Radiations ionisantes (éq. kBq U235)"
        ldu:
          type: number
          description: "Utilisation des sols (sans dimension (pt))"
        mru:
          type: number
          description: "Utilisation de ressources minérales et métalliques (kg éq. Sb)"
        ozd:
          type: number
          description: "Appauvrissement de la couche d'ozone (kg éq. CFC 11)"
        pco:
          type: number
          description: "Formation d'ozone photochimique (kg éq. COVNM)"
        pef:
          type: number
          description: "Score PEF (µPt)"
        pma:
          type: number
          description: "Particules (incidence de maladie)"
        swe:
          type: number
          description: "Eutrophisation marine (kg éq. N)"
        tre:
          type: number
          description: "Eutrophisation terrestre (mol éq. N)"
        wtu:
          type: number
          description: "Utilisation de ressources en eau (m³)"
    TextileQuery:
      type: object
      additionalProperties: false
      required:
      - materials
      - countrySpinning
      - countryFabric
      - countryDyeing
      - countryMaking
      properties:
        mass:
          type: number
          description: Masse du produit fini
        materials:
          type: array
          description: Liste des matières composant le vêtement
          items:
            "$ref": "#/components/schemas/TextileQueryMaterial"
          minItems: 1
        product:
          type: string
          description: Le type de produit
          enum:
          - chemise
          - jean
          - jupe
          - manteau
          - pantalon
          - pull
          - tshirt
        countrySpinning:
          type: string
          description: Pays de filature
        countryFabric:
          type: string
          description: Pays de tissage ou de tricotage
        countryDyeing:
          type: string
          description: Pays de teinture ou d'ennoblissement
        countryMaking:
          type: string
          description: Pays de confection
        airTransportRatio:
          type: number
          description: Part de transport aérien
          minimum: 0
          maximum: 1
          required: false
        quality:
          type: number
          description: Qualité intrinsèque
          minimum: 0.67
          maximum: 1.45
          required: false
        reparability:
          type: number
          description: Indice de réparabilité du produit
          minimum: 1
          maximum: 1.15
          required: false
        makingWaste:
          type: number
          description: Taux de perte en confection
          minimum: 0
          maximum: 0.4
          required: false
        makingComplexity:
          type: string
          description: Complexité de la confection
          required: false
          enum:
          - very-high
          - high
          - medium
          - low
          - very-low
          - not-applicable
        yarnSize:
          type: number
          description: Titrage du fil, exprimé en numéro métrique (Nm)
          required: false
        surfaceMass:
          type: number
          description: Le grammage de l'étoffe, exprimé en gr/m²
          minimum: 80
          maximum: 500
          required: false
        fabricProcess:
          type: string
          required: true
          enum:
            "$ref": "#/components/schemas/FabricProcessEnum"
        disabledSteps:
          type: string
          required: false
          enum:
          - material
          - spinning
          - fabric
          - making
          - ennobling
          - distribution
          - use
          - eol
    TextileQueryMaterial:
      type: object
      additionalProperties: false
      required:
      - id
      - share
      properties:
        id:
          type: string
        share:
          type: number
          min: 0.01
          max: 1
        spinning:
          type: string
          enum:
          - ConventionalSpinning
          - UnconventionalSpinning
          - SyntheticSpinning
        country:
          type: string
          minLength: 2
          maxLength: 2
    FoodQuery:
      type: object
      additionalProperties: false
      required:
      - ingredients
      properties:
        ingredients:
          type: array
          items:
            "$ref": "#/components/schemas/FoodQueryIngredient"
          minItems: 1
        transform:
          "$ref": "#/components/schemas/FoodQueryTransform"
        packaging:
          type: array
          items:
            "$ref": "#/components/schemas/FoodQueryPackaging"
        distribution:
          type: string
          description: Distribution
          enum: [ambient, fresh, frozen]
        preparation:
          type: array
          description: Préparation avant consommation
          items:
            type: string
            enum:
            - frying
            - pan-cooking
            - pan-warming
            - oven
            - microwave
            - refrigeration
            - freezing
    FoodQueryIngredient:
      type: object
      additionalProperties: false
      required:
      - id
      - mass
      properties:
        id:
          type: string
          description: Identifiant de l'ingrédient
        mass:
          type: number
          description: Masse de l'ingrédient, **en grammes**
        country:
          type: string
          description: Code ISO du pays d'origine
        byPlane:
          type: string
          description: Transport par avion
          enum: ["", byPlane, noPlane]
        bonuses:
          required:
          - "agro-diversity"
          - "agro-ecology"
          properties:
            "agro-diversity":
              type: number
              description: Bonus agro-diversité **en pourcentage**
            "agro-ecology":
              type: number
              description: Bonus agro-écologie **en pourcentage**
            "animal-welfare":
              type: number
              description: Si applicable, bonus de bien-être animal **en pourcentage**
    FoodQueryTransform:
      type: object
      additionalProperties: false
      required:
      - code
      - mass
      properties:
        code:
          type: string
          description: Identifiant du procédé de transformation
        mass:
          type: number
          description: Masse de produit à transformer, **en grammes**
    FoodQueryPackaging:
      type: object
      additionalProperties: false
      required:
      - code
      - mass
      properties:
        code:
          type: string
          description: Identifiant du procédé d'emballage, **en grammes**
        mass:
          type: number
          description: Masse de cet emballage, **en kilogrammes**
    InvalidParametersError:
      type: object
      properties:
        error:
          type: array
          description: Description de l'erreur de validation des paramètres fournis
          items:
            type: string
        documentation:
          type: string
          description: "Lien hypertexte vers la documentation de l'API"
    FabricProcessEnum:
      - knitting-mix
      - knitting-fully-fashioned
      - knitting-integral
      - knitting-circular
      - knitting-straight
      - weaving
    CountryListResponse:
      type: array
      description: Liste des pays.
      items:
        type: object
        properties:
          code:
            type: string
          name:
            type: string
    MaterialListResponse:
      type: array
      description: Liste des matières
      items:
        type: object
        properties:
          uuid:
            type: string
          name:
            type: string
    ProductListResponse:
      type: array
      description: Liste des types de produits
      items:
        type: object
        properties:
          id:
            type: string
          name:
            type: string
    RecipeResultsResponse:
      type: object
      description: |
        Recipe impact results.
      properties:
        results:
          type: object
          properties:
            impacts:
              $ref: "#/components/schemas/Impacts"
    GenericImpactsResponse:
      type: object
      description: |
        Impacts environnementaux exprimés dans leurs unités respectives, dont
        [la documentation est disponible ici](https://fabrique-numerique.gitbook.io/ecobalyse/methodologie/impacts-consideres).
      properties:
        impacts:
          $ref: "#/components/schemas/Impacts"
        description:
          type: string
          description: Une description de la simulation.
        query:
          type: object
          description: Le jeu de paramètres utilisé pour effectuer la simulation.
    SingleImpactResponse:
      type: object
      properties:
        impacts:
          type: object
          properties:
            "{impact}":
              type: number
              description: Valeur de l'impact recherché
        description:
          type: string
          description: Une description de la simulation.
        query:
          type: object
          description: Le jeu de paramètres utilisé pour effectuer la simulation.
    IngredientListResponse:
      type: array
      description: Liste des ingrédients utilisables dans une recette
      items:
        type: object
        properties:
          id:
            type: string
          name:
            type: string
          defaultOrigin:
            type: string
            description:
              Lieu d'origine par défaut de cet ingrédient dont la liste est disponible dans
              [la documentation](https://fabrique-numerique.gitbook.io/ecobalyse/alimentaire/transport#circuits-consideres)
    PackagingListResponse:
      type: array
      description: Liste des emballages utilisables pour conditionner une recette
      items:
        type: object
        properties:
          code:
            type: string
          name:
            type: string
    TransformListResponse:
      type: array
      description: Liste des procédés de transformation utilisables pour une recette
      items:
        type: object
        properties:
          code:
            type: string
          name:
            type: string