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 security: - token: [] 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: 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}: 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: 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" /textile/trims: get: tags: - Textile summary: Liste des accessoires pour vêtements responses: 200: description: Opération réussie content: application/json: schema: $ref: "#/components/schemas/TrimListResponse" /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: 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: cf30d3bc-e99c-418a-b7e3-89a894d410a5 mass: 120 - id: 38788025-a65e-4edf-a92f-aab0b89b0d61 mass: 140 - id: 8f3863e7-f981-4367-90a2-e1aaa096a6e0 mass: 60 - id: 4d5198e7-413a-4ae2-8448-535aa3b302ae mass: 225 transform: id: 83b897cf-9ed2-5604-83b4-67fab8606d35 mass: 545 packaging: - id: 25595091-35b6-5c62-869f-a29c318c367e mass: 105 distribution: ambient preparation: - refrigeration SpanishOrganicCarrotCake: summary: "Carrot cake bio, origine Espagne" value: ingredients: - id: cfd4a437-aa49-49ff-818e-353421f2fc09 mass: 120 country: ES - id: a98b8776-a96d-48e9-b218-976f5452907a mass: 140 country: ES - id: 2bf307e8-8cb0-400b-a4f1-cf615d9e96f4 mass: 60 country: ES - id: 9042b6d0-c309-4757-a03f-ba802f0c8c01 mass: 225 country: ES transform: id: 83b897cf-9ed2-5604-83b4-67fab8606d35 mass: 545 packaging: - id: 25595091-35b6-5c62-869f-a29c318c367e mass: 105 distribution: ambient preparation: - refrigeration BrazilianMango: summary: "Mangue du Brésil" value: ingredients: - id: db0e5f44-34b4-4160-b003-77c828d75e60 mass: 500 country: BR 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: securitySchemes: token: description: > Un jeton d'API (token) vous permet d'accéder aux impacts détaillés des calculs effectués. Il peut être passé dans les entêtes `Authorization: Bearer` ou `token` de la requête. type: apiKey name: token in: header examples: tShirtFrance: summary: "T-Shirt France 100% Coton" value: mass: 0.17 materials: - id: "ei-coton" share: 1 country: "FR" product: "tshirt" countrySpinning: "FR" countryFabric: "FR" countryDyeing: "FR" countryMaking: "FR" fabricProcess: "knitting-mix" tShirtChina: summary: "T-Shirt Chine, low-cost, 100% Coton" value: mass: 0.17 materials: - id: "ei-coton" share: 1 product: "tshirt" countrySpinning: "CN" countryFabric: "CN" countryDyeing: "CN" countryMaking: "CN" airTransportRatio: 0.33 makingWaste: null makingDeadStock: 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" 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: - mass - materials - product properties: mass: type: number description: Masse du produit fini, en kilogrammes minimum: 0.01 example: 0.17 product: type: string description: | Identifiant du produit (liste disponible sur le point d'entrée `/textile/products`) enum: - calecon - chaussettes - chemise - jean - jupe - maillot - manteau - pantalon - pull - slip - tshirt materials: type: array description: Liste des matières composant le vêtement items: "$ref": "#/components/schemas/TextileQueryMaterial" minItems: 1 airTransportRatio: type: number description: | Part de **transport aérien** entre l'étape de **Confection** et l'étape de **Distribution**, entre `0` et `1` minimum: 0 maximum: 1 business: type: string description: | Type d'entreprise et d'offre de services : - `small-business`: PME/TPE - `large-business-with-services`: Grande entreprise avec service de réparation - `large-business-without-services` (par défaut): Grande entreprise sans service de réparation enum: - small-business - large-business-with-services - large-business-without-services countryDyeing: type: string description: | Code pays pour l'étape de **Teinture** (liste disponible sur le point d'entrée `textile/countries`) minLength: 2 maxLength: 2 countryFabric: type: string description: | Code pays pour l'étape de **Tissage/Tricotage** (liste disponible sur le point d'entrée `textile/countries`) minLength: 2 maxLength: 2 countryMaking: type: string description: | Code pays pour l'étape de **Confection** (liste disponible sur le point d'entrée `textile/countries`) minLength: 2 maxLength: 2 countrySpinning: type: string 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. minLength: 2 maxLength: 2 disabledSteps: type: array 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`. enum: - material - spinning - fabric - making - ennobling - distribution - use - eol dyeingProcessType: type: string description: | Ce paramètre permet de préciser le type de procédé avec lequel est teint le produit; il peut prendre les valeurs suivantes : - `average`: Teinture moyenne - `continuous`: Teinture en continu - `discontinuous`: Teinture discontinue ⚠️ En l’absence d’utilisation explicite du paramètre, le type de teinture utilisé sera teinture moyenne. enum: - average - continuous - discontinuous fabricProcess: type: string 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 enum: - knitting-mix - knitting-fully-fashioned - knitting-integral - knitting-circular - knitting-straight - weaving fading: type: boolean description: | Active l'application du **procédé de délavage** pour l'étape de confection d'un produit. makingComplexity: type: string 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).** enum: - very-high - high - medium - low - very-low - not-applicable makingDeadStock: type: number description: | Taux de stocks dormants lors de la confection, entre `0` et `0.3`. minimum: 0 maximum: 0.3 makingWaste: type: number 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).** minimum: 0 maximum: 0.4 numberOfReferences: description: | Nombre de références au catalogue de la marque. type: number minimum: 1 maximum: 999999 physicalDurability: description: La durabilité physique du produit. type: number minimum: 0.67 maximum: 1.45 price: description: | Prix du produit, en Euros (€). type: number minimum: 1 maximum: 1000 printing: type: object description: | Ce paramètre permet de préciser le type d'impression effectuée sur le produit. Par exemple, `{"kind": "pigment", "ratio": 0.1}` signifie impression pigmentaire sur 10% de la superficie du vêtement. required: ["kind"] properties: kind: type: string description: | Type de procédé d'impression pouvant prendre les valeurs suivantes : - `pigment` pour une impression pigmentaire ; - `substantive` pour une impression fixé/lavé ; enum: - pigment - substantive ratio: type: number description: | Pourcentage de surface imprimée, exprimé entre `0` et `1` surfaceMass: type: number 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.** minimum: 80 maximum: 500 traceability: description: | Traçabilité renforcée type: boolean trims: description: | Liste des accessoires du vêtement (boutons, zip, etc). La liste des accessoires disponibles est accessible sur le point d'entrée `/textile/trims`. type: array items: type: object properties: id: type: string format: uuid quantity: type: integer minimum: 0 upcycled: description: | Produit remanufacturé type: boolean yarnSize: oneOf: - type: string - type: integer 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 minimum: 9 maximum: 200 TextileQueryMaterial: type: object description: | Liste des matières composant le produit additionalProperties: false required: - id - share properties: id: type: string description: | Identifiant de la matière, la liste des matières disponibles est accessible sur le point d'entrée `/textile/materials` share: type: number description: | Part du produit que cette matière représente (entre `0` et `1`) minimum: 0.01 maximum: 1 spinning: type: string description: | Procédé de filature ou de filage pour la matière, dont la valeur peut être : - `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 enum: - ConventionalSpinning - UnconventionalSpinning - SyntheticSpinning country: type: string description: Code du pays d'origine de la matière 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: | 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. enum: [ambient, fresh, frozen] preparation: type: array 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é.** items: type: string enum: - frying - pan-cooking - pan-warming - oven - microwave - refrigeration - freezing FoodQueryIngredient: type: object 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: ``, `byPlane`, `noPlane`) 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] FoodQueryTransform: type: object description: | Précision du procédé de transformation et de la masse de produit à transformer. additionalProperties: false required: - id - mass properties: id: type: string description: Identifiant du procédé de transformation (liste disponible sur le point d'entrée `/food/transforms`) mass: type: number description: Masse de produit à transformer, **en grammes** FoodQueryPackaging: type: object description: | Liste des emballages composant la recette. additionalProperties: false required: - id - mass properties: id: type: string description: Identifiant du procédé d'emballage (liste disponible sur le point d'entrée `/food/packaging`) mass: type: number description: Masse de cet emballage, **en grammes** InvalidParametersError: type: object properties: error: type: object description: | Un dictionnaire dont la clé est le nom d'un champ en erreur et la valeur le message d'erreur. properties: decoding: type: string description: Une erreur de décodage JSON general: type: string description: Une erreur d'ordre général additionalProperties: type: string description: Une erreur particulière pour un champ spécifique documentation: type: string description: | Lien hypertexte vers la documentation de l'API 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 TrimListResponse: type: array description: Liste des accessoires pour vêtements 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: id: type: string name: type: string TransformListResponse: type: array description: Liste des procédés de transformation utilisables pour une recette items: type: object properties: id: type: string name: type: string