Prodotti
Un prodotto è un articolo che acquistate o vendete come articolo finito: un prodotto confezionato, un semilavorato acquistato pronto, un articolo dal catalogo di un fornitore. La sua composizione deriva di solito dalla dichiarazione degli ingredienti sulla confezione.
Lo salvate una volta, con il vostro id, e ne leggete l'impronta calcolata. Un prodotto salvato si può anche usare in una ricetta — richiamatelo con type: "products".
Salvare un prodotto
PUT /products/{id}, con il vostro id nell'URL. La response contiene già il calcolo completo — non serve una seconda request.
{
"id": "carrot-puree-500g",
"gtin": "00123456789023",
"names": [{"language": "de", "value": "Karottenpüree"}],
"amount": 500,
"unit": "gram",
"producer": "ACME Foods",
"ingredients-declaration": "Karotten, Wasser, Salz",
"nutrient-values": {
"energy-kcal": 35,
"fat-gram": 0.2,
"protein-gram": 0.9,
"carbohydrates-gram": 7.5
}
}
È l'ingredients-declaration a dirci di cosa è fatto davvero il prodotto: includetela ogni volta che la confezione la riporta. Senza di essa il prodotto viene identificato solo dal nome.
Per caricare un catalogo usate POST /products/batch. Ogni prodotto viene elaborato separatamente e ha una propria voce nella response, quindi un prodotto che non si può calcolare non blocca gli altri. Abbinate le voci alla vostra request tramite product-id o tramite il request-id che avete inviato.
Dopo il caricamento, mantenete allineata la vostra copia locale con GET /products?updated-since — vedere Mantenere aggiornati i dati.
Mantenere aggiornati i dati
I valori che calcoliamo non sono fissi. Migliorano nel tempo — un ingrediente viene abbinato con più precisione, i dati di background vengono aggiornati — quindi un prodotto caricato mesi fa può avere oggi un valore di CO₂ migliore.
GET /products restituisce gli id dei vostri prodotti. Aggiungete updated-since con la data della vostra ultima sincronizzazione e riceverete solo quelli da scaricare di nuovo:
GET /products?updated-since=2026-07-01
{
"products": ["carrot-puree-500g", "tomato-sauce-400g"]
}
Cioè: i prodotti che avete modificato, quelli mai calcolati e quelli i cui valori possono essere cambiati perché è migliorato qualcosa da cui dipendono. Scaricate ognuno con GET /products/{id}. Un prodotto caricato con POST /products/batch si comporta in questo feed esattamente come uno caricato con un singolo PUT.
Un unico namespace di id
Prodotti e ingredienti ordinari condividono un unico namespace di id: un id appartiene o a un prodotto o a un ingrediente, mai a entrambi. GET /products/{id} restituisce quello che lo detiene e il campo type indica quale:
type | Chi detiene l'id |
|---|---|
products | Un prodotto. Cambia solo tramite gli endpoint dei prodotti. |
conceptual-ingredients | Un ingrediente ordinario. Lo definisce una ricetta o una fornitura, e qualsiasi ricetta o fornitura lo modifica. |
Una ricetta o una fornitura che invia un id modifica l'ingrediente ordinario con quell'id, mai un prodotto. Per salvare un prodotto con un id già detenuto da un ingrediente ordinario, impostate convert-ingredient-to-product=true.
Proprietà del prodotto
Proprietà della request
| Proprietà | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
id | String | Sì | Il vostro identificatore univoco del prodotto |
names | Array | Sì | Nome del prodotto come array di oggetti lingua: [{"language": "de", "value": "Karottenpüree"}] |
ingredients-declaration | String | Best practice | Lista degli ingredienti come dichiarata sulla confezione. Viene analizzata per determinare di cosa è fatto il prodotto. |
nutrient-values | Object | Best practice | Valori nutrizionali per 100g come dichiarati sulla confezione (vedere Riferimento) |
gtin | String | Best practice | Global Trade Item Number (www.gtin.info) |
amount | Float | Best practice | Quantità del prodotto nell'unità indicata. Senza di essa, l'impronta si riferisce a un chilogrammo. |
unit | String | No | Unità: kg, gram o liter. Default: gram |
producer | String | Best practice | Il produttore o il marchio del prodotto |
date | String | No | Data di produzione per i calcoli stagionali. Formato: YYYY-MM-DD |
origin | String | Best practice | Luogo di produzione: indirizzo postale o paese |
transport | String | Best practice | Mezzo di trasporto: air o ground |
production | String | Best practice | Metodo di produzione: standard, greenhouse, organic, fair-trade, farm, wild-caught, sustainable-fish |
processing | String | No | Livello di lavorazione: raw, unboned, boned, skinned, beheaded, fillet, cut, boiled, peeled |
conservation | String | Best practice | Metodo di conservazione: fresh, frozen, dried, conserved, canned, boiled-down |
packaging | String | No | Tipo di imballaggio: none, plastic, paper, pet, tin, alu, glas, cardboard, tetra |
Proprietà della response
Il prodotto viene restituito sotto product, accanto a uno statuscode che indica se è stato possibile calcolarlo.
| Proprietà | Tipo | Descrizione |
|---|---|---|
statuscode | Integer | 200 quando il prodotto è stato calcolato. Vedere Codici di stato. |
message | String | Spiega lo statuscode quando non è 200 |
product-id | String | L'id del prodotto a cui si riferisce questa voce |
product | Object | Il prodotto e i suoi valori calcolati (vedere sotto) |
| Proprietà | Tipo | Descrizione |
|---|---|---|
id | String | Identificatore del prodotto |
type | String | products (protetto da scrittura) o conceptual-ingredients (qualsiasi ricetta può sovrascriverlo) |
names | Array | Nomi del prodotto come array di oggetti lingua |
co2-value | Integer | Emissioni di CO₂ in grammi CO₂e per l'amount indicato (vedere la nota sotto) |
rating | String | Valutazione CO₂ (A-E). A è la migliore, E la peggiore. |
eaternity-award | Boolean | true se il prodotto è rispettoso del clima |
co2-value-improvement-percentage | Float | Confronto tra l'impronta di CO₂ di questo prodotto per food unit e la media |
co2-value-reduction-value | Float | Grammi di CO₂ risparmiati rispetto a un prodotto medio con lo stesso valore nutrizionale |
food-unit | Float | Valore nutrizionale del prodotto per l'amount indicato |
amount | Float | Quantità del prodotto, ripresa dalla vostra request |
unit | String | Unità di misura |
gtin | String | Global Trade Item Number |
date | String | Data di produzione |
ingredients-declaration | String | Il testo originale della dichiarazione degli ingredienti (con ingredients-declaration=true) |
nutrient-values-estimated-per-specified-amount | Object | Valori nutrizionali stimati dal backend e scalati sulla quantità indicata (con nutrient-values=true) |
indicators | Object | Indicatori ambientali (con indicators=true) |
co2-value e food-unit sono calcolati per l'amount (e la unit) della vostra request — dieci volte la quantità significa dieci volte l'impronta. 500 gram e 0.5 kilogram danno lo stesso risultato. Se non inviate una quantità, l'impronta si riferisce a un chilogrammo.
Se invece richiamate il prodotto da una ricetta, è l'amount di quella riga della ricetta a scalarlo — l'amount del prodotto stesso non viene ripreso.
Esempio di response
{
"statuscode": 200,
"message": "",
"request-id": 0,
"product-id": "carrot-puree-500g",
"product": {
"food-unit": 0.62,
"eaternity-award": true,
"co2-value": 77,
"rating": "A",
"co2-value-improvement-percentage": 84,
"co2-value-reduction-value": 403,
"id": "carrot-puree-500g",
"gtin": "00123456789023",
"names": [{"language": "de", "value": "Karottenpüree"}],
"amount": 500.0,
"unit": "gram",
"producer": "ACME Foods",
"origin": "",
"transport": "",
"production": "",
"processing": "",
"conservation": "",
"packaging": "",
"type": "products"
}
}
Codici di stato
Oltre ai consueti codici di stato, i prodotti usano:
| Codice | Significato | Cosa fare |
|---|---|---|
| 612 | Il prodotto richiamato non esiste | Salvate prima il prodotto, poi inviate la ricetta |
| 613 | Una scrittura che un prodotto non accetta — una ricetta ha cercato di definire un ingrediente con l'id di un prodotto, oppure la scrittura di un prodotto convertirebbe un ingrediente esistente | Richiamate il prodotto con type: "products" invece di definirlo. Per convertire intenzionalmente un ingrediente, aggiungete convert-ingredient-to-product=true. |
Nota: prodotti e ingredienti
Un prodotto e un ingrediente descrivono la stessa cosa: un alimento con un nome, una quantità e attributi come origine, produzione e conservazione. Si differenziano per il modo in cui vengono salvati. Un prodotto viene salvato una volta con il proprio id e cambia solo tramite gli endpoint dei prodotti. Un ingrediente viene definito all'interno di una ricetta o di una fornitura.
Endpoint
📄️ List products
Returns the ids of all products stored for your account.
📄️ Create or update a batch of products
Create or update many products in a single request - the recommended way to upload a product
📄️ Create or update a product
Create or update a single product. The response already contains the finished calculation, so
📄️ Get a product
Retrieve a product together with its calculated values.
📄️ Delete a product
Delete a product. Like the read, this also resolves an ordinary ingredient stored under this