TracePass
Inizia ora
Passaporti

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

POST/api/v1/passports/{id}/measurements
Scarica OpenAPI 3.1
POST/api/v1/passports/{id}/measurements

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.

Parametri di percorso

  • idobbligatorio

    ObjectId

    ID del passaporto.

Header

  • Authorizationobbligatorio

    string

    `Bearer <token>` — 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.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

  • Idempotency-Key

    string

    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.

Richiesta

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"
      }
    ]
  }'

Risposta

{
  "accepted": 2,
  "storedCount": 2,
  "materializedCount": 2,
  "duplicates": 0,
  "measurementIds": [
    "6750a1b2c3d4e5f6a7b8c9d0",
    "6750a1b2c3d4e5f6a7b8c9d1"
  ]
}

Endpoint correlati