--- title: Acquisire misurazioni description: Invia misurazioni della batteria (stato di salute, cicli) a un passaporto pubblicato. Solo passaporti batteria; 1–500 per chiamata. Supporta Idempotency-Key. canonical: "https://www.tracepass.eu/it/docs/capture-measurements" locale: it source: "https://www.tracepass.eu/it/docs/capture-measurements" --- # Acquisire misurazioni > Invia misurazioni della batteria (stato di salute, cicli) a un passaporto pubblicato. Solo passaporti batteria; 1–500 per chiamata. Supporta Idempotency-Key. ```http POST /api/v1/passports/{id}/measurements ``` **Solo per passaporti della batteria** (Regolamento (UE) 2023/1542 Art. 77, Allegato XIII punto 4 — dati d'uso). Il passaporto deve essere pubblicato; una bozza o un passaporto sospeso restituisce 422 `passport_not_active`. Un passaporto non relativo a una batteria restituisce 422 `not_a_battery`. Inviare da 1 a 500 misurazioni per chiamata, ciascuna come `{ fieldKey, value, measuredAt, externalId?, unit? }` — `measuredAt` è un timestamp ISO 8601, non può essere nel futuro; `value` deve essere al massimo **16 KB una volta serializzato** (un valore più grande restituisce 400 `invalid_value`). Le `fieldKey` accettate sono i campi dati d'uso dell'Allegato XIII punto 4: `stateOfHealth`, `stateOfCertifiedEnergy`, `remainingCapacity`, `remainingPowerCapability`, `remainingRoundTripEfficiency`, `evolutionOfSelfDischargeRate`, `currentInternalResistancePack`, `capacityFade`, `powerFade`, `internalResistanceIncrease`, `dynamicRatedCapacity`, `dynamicPowerCapability`, `dynamicInternalResistance`, `dynamicEnergyRoundTripEfficiency`, `dynamicExpectedLifetimeCycles`, `numberOfFullEquivalentChargingCycles`, `numberOfChargingEvents`, `currentStateOfCharge`, `negativeEvents`, `temperatureConditionsHistorical`. Ogni misurazione viene archiviata. La più recente per campo (in base a `measuredAt`) diventa il valore corrente di quel campo nel passaporto e imposta `dynamicDataAsOf`. Una misurazione più vecchia arrivata in ritardo viene mantenuta nella cronologia ma non sovrascrive un valore corrente più recente. Fornire un `externalId` rende una misurazione **idempotente**: un invio ripetuto viene conteggiato in `duplicates`, non archiviato né addebitato nuovamente. È supportata anche l'intestazione `Idempotency-Key` — stessa chiave + stesso corpo riproduce la risposta cached per 24 h; stessa chiave + corpo diverso restituisce 422. Scope OAuth: `passports:write`. `batteryStatus` **non** è un campo di misurazione — le modifiche allo stato del ciclo di vita avvengono tramite la dashboard. Una batteria preparata per il riutilizzo, per il cambio di destinazione o per la rifabbricazione riceve un nuovo passaporto della batteria collegato all'originale tramite `lineage` alla creazione del passaporto. Un campo che il Regolamento esclude per la categoria della batteria restituisce 422 `field_not_applicable` (ad es. `stateOfCertifiedEnergy` non è applicabile per le batterie LMT; le cinque metriche di capacità residua dell'Allegato VII Parte A non sono applicabili per le batterie EV). Una forma alternativa di indirizzamento è disponibile su `POST /api/v1/passports/by-serial/{serial}/measurements` — stesso corpo, stessa risposta. Se un numero di serie non è univoco nel proprio account, aggiungere `?gtin=` per disambiguare. Le misurazioni contano contro il **contingente mensile** di misurazioni del piano (`maxMeasurementsPerMonth`), non contro il budget giornaliero di scritture v1. I piani a pagamento continuano ad accettare e contare misurazioni oltre il contingente senza addebiti; il piano Free si ferma al raggiungimento del contingente. La visualizzazione di un passaporto non è mai addebitata. ## Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `Authorization` | header | string | yes | `Bearer ` — una chiave API `tp_` (Developer → API Keys; più semplice, per server-to-server) oppure un access token OAuth 2.0 (Developer → OAuth Apps; per app autorizzate dall'utente, scoped e revocabili). La pagina Authentication contiene il flusso OAuth completo e l'elenco degli scopes. | | `id` | path | ObjectId | yes | ID del passaporto. | | `Idempotency-Key` | header | string | no | Chiave di idempotenza opzionale (UUID v4 o qualsiasi stringa opaca ≤ 64 caratteri). Stessa chiave + stesso corpo riproduce la risposta cached per 24 h; stessa chiave + corpo diverso restituisce 422. | ## Examples ```bash curl -sS -X POST \ https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1/measurements \ -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "measurements": [ { "fieldKey": "stateOfHealth", "value": 96.4, "measuredAt": "2027-03-01T06:00:00Z", "externalId": "bms-7781-2027-03-01" }, { "fieldKey": "numberOfFullEquivalentChargingCycles", "value": 112, "measuredAt": "2027-03-01T06:00:00Z" } ] }' ``` ```typescript const res = await fetch( `https://app.tracepass.eu/api/v1/passports/${id}/measurements`, { method: "POST", headers: { Authorization: `Bearer ${process.env.TRACEPASS_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID(), }, body: JSON.stringify({ measurements: [ { fieldKey: "stateOfHealth", value: 96.4, measuredAt: new Date().toISOString(), externalId: "bms-7781-2027-03-01", }, { fieldKey: "numberOfFullEquivalentChargingCycles", value: 112, measuredAt: new Date().toISOString(), }, ], }), }, ); const result = await res.json(); console.log("accepted:", result.accepted, "stored:", result.storedCount); ``` ```python import os, uuid, requests res = requests.post( f"https://app.tracepass.eu/api/v1/passports/{passport_id}/measurements", headers={ "Authorization": f"Bearer {os.environ['TRACEPASS_API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "measurements": [ { "fieldKey": "stateOfHealth", "value": 96.4, "measuredAt": "2027-03-01T06:00:00Z", "externalId": "bms-7781-2027-03-01", }, { "fieldKey": "numberOfFullEquivalentChargingCycles", "value": 112, "measuredAt": "2027-03-01T06:00:00Z", }, ] }, ) res.raise_for_status() data = res.json() print("accepted:", data["accepted"], "stored:", data["storedCount"]) ``` ## Responses ### 200 — Misurazioni accettate ```json { "accepted": 2, "storedCount": 2, "materializedCount": 2, "duplicates": 0, "measurementIds": [ "6750a1b2c3d4e5f6a7b8c9d0", "6750a1b2c3d4e5f6a7b8c9d1" ] } ``` ### 200 — Duplicato ignorato (riutilizzo di externalId) ```json { "accepted": 1, "storedCount": 0, "materializedCount": 0, "duplicates": 1, "measurementIds": [] } ``` ### 400 — Chiave campo non valida (batteryStatus) ```json { "error": "invalid_field_key", "details": "batteryStatus is not a measurement field" } ``` ### 400 — Valore troppo grande (> 16 KB) ```json { "error": "invalid_value", "details": "value exceeds 16 KB serialised limit" } ``` ### 402 — Contingente mensile di misurazioni del piano Free esaurito ```json { "error": "measurement_allowance_exceeded" } ``` ### 422 — Non è un passaporto della batteria ```json { "error": "not_a_battery" } ``` ### 422 — Passaporto non pubblicato ```json { "error": "passport_not_active" } ``` ## Related - [Cronologia delle misurazioni](https://www.tracepass.eu/it/docs/list-measurements.md) - [Ultime misurazioni](https://www.tracepass.eu/it/docs/latest-measurements.md) - [Creare passaporto (lineage)](https://www.tracepass.eu/it/docs/create-passport.md)