Acquisire misurazioni

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=<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.