batterypass
Prodotto
Come funziona Funzioni Confronto
Soluzioni
Accumulo (BESS) Veicoli leggeri Batterie industriali Veicoli elettrici Fornitori
Conformità
Panoramica della conformità Regolamento UE sulle batterie Verifica obblighi Sicurezza e privacy
Risorse
Tutti gli articoli Da dove vengono i dati Quali dati servono al passaporto Codice QR sulla batteria Chi è responsabile? Glossario Sviluppatori e API Stato del servizio Modifiche al prodotto
Batterypass
Prezzi Chi siamo
Accedi Inizia gratis
Sviluppatori

Colleghi i dati del passaporto ai Suoi sistemi.

API REST, importazione ed esportazione CSV, indirizzi fissi e tutti i campi dati. Con una chiave di prova può provare tutto senza modificare dati.

50.000passaporti per file
38campi dati nell’app
3formati: CSV, SVG, PNG

Panoramica

Quattro oggetti e quattro vie per lo scambio di dati. Per iniziare basta un file CSV; per l’uso continuativo c’è l’API REST.

  1. AziendaIl Suo account con utenti e piano
  2. ModelloDati anagrafici, una volta per modello
  3. PassaportoUna batteria con numero di serie e indirizzo proprio
  4. EventoRiparazione, riconversione o rifiuto
ViaA cosa serveStato
Importazione CSVRiprendere i numeri di serie da ERP, MES o ExcelDisponibile
Esportazione CSVRiportare ID e indirizzi nei Suoi sistemiDisponibile
Indirizzo del passaporto e codice QRCreare etichette proprie o collegare i passaportiDisponibile
API RESTCreare modelli e passaporti automaticamente, senza caricamenti manualiDisponibile

Importazione CSV

Disponibile

La via abituale dall’ERP: esportare un elenco e caricarlo in un modello. Ogni nuovo numero di serie riceve un passaporto.

export.csv
Material;Serialnummer;Fertigungsdatum;Charge;Werk;Status
BX-48V;SN-0001;01.03.2027;L2027-03;Essen;frei
BX-48V;SN-0002;01.03.2027;L2027-03;Essen;frei
BX-48V;SN-0003;02.03.2027;L2027-03;Essen;frei
RegolaSpecifica
CodificaUTF-8 con o senza BOM. Windows-1252 viene rilevato e convertito.
SeparatorePunto e virgola, virgola o tabulazione. Decide la prima riga.
DimensioneMassimo 8 MB e 50.000 righe per file.
StrutturaUna batteria per riga, senza interruzioni di riga in un campo.
IntestazioneFacoltativa. Con l’intestazione le colonne possono avere qualsiasi ordine e quelle aggiuntive vengono ignorate. Senza, vale l’ordine della tabella qui sotto.
ColonnaCampoNomi di colonna riconosciutiObbligatorioRegola
1Numero di serieseriennummer, serialnummer, serial, serial number, serialnumber, serial no, sn, serien-nr, seriennr, sernrSìMassimo 120 caratteri: lettere, cifre, spazi e - _ . / :
2Data di produzioneherstelldatum, produktionsdatum, fertigungsdatum, manufacturing date, production date, date, datumFacoltativo2027-03-01, 01.03.2027, 1.3.2027, 01/03/2027, 1/3/2027 o 2027/03/01
3Lottocharge, chargennummer, batch, lot, losFacoltativoMassimo 120 caratteri
4Luogo di produzioneherstellort, produktionsort, werk, place, plant, manufacturing placeFacoltativoMassimo 190 caratteri

Cosa succede al caricamento

  • Prima appare un’anteprima; non viene ancora salvato nulla.
  • Le righe errate vengono segnalate con il numero e saltate.
  • I numeri doppi nel file e quelli già presenti in questo modello vengono saltati.
  • I passaporti nascono solo dopo la Sua conferma, in un’unica operazione. L’importazione compare nel registro di audit.

Verifica un file

Disponibile

Verifichi un’esportazione prima di accedere. Valgono le stesse regole dell’importazione nell’app.

La verifica avviene solo nel Suo browser; il file non viene caricato. Se un numero esiste già nel modello lo mostra solo l’anteprima nell’app.

Esportazione CSV

Disponibile

Per ogni modello si può scaricare l’elenco di tutti i passaporti, in UTF-8 con BOM e separato da punto e virgola. Così ID e indirizzi tornano in ERP, MES o stampa etichette. Il download richiede l’accesso.

paesse_BX-48V.csv
Seriennummer;Pass-ID;Pass-URL;Herstelldatum;Charge;Herstellort;Status
SN-0001;7KM2XQ9RTA;https://app.batterypass2027.eu/p/7KM2XQ9RTA;2027-03-01;L2027-03;Essen;Original

Indirizzo del passaporto e codice QR

Disponibile

Ogni passaporto ha un indirizzo fisso. A un codice QR, a un link nel manuale o a una voce dell’ERP non serve altro.

URL
https://app.batterypass2027.eu/p/{PASS-ID}
https://app.batterypass2027.eu/p/{PASS-ID}?lang=en
  • L’ID ha 10 caratteri ed evita quelli confondibili come 0, O, 1, I e L.
  • Il codice QR contiene solo questo indirizzo. Se i dati cambiano, resta valido.
  • Nell’app il codice è disponibile per passaporto in SVG e PNG, oltre a fogli di etichette da stampare.
  • Senza accesso, la pagina del passaporto mostra solo i dati pubblici. Ai motori di ricerca si chiede di non indicizzarla.
  • Con un GTIN c’è anche un link GS1 Digital Link.

Creare etichette proprie dall’esportazione

etiketten.py
# pip install "qrcode[pil]"
import csv
import qrcode

with open("paesse_BX-48V.csv", encoding="utf-8-sig", newline="") as f:
    for row in csv.DictReader(f, delimiter=";"):
        qrcode.make(row["Pass-URL"]).save(f'{row["Pass-ID"]}.png')

Campi dati

Disponibile

Questi 38 campi esistono oggi nell’app, in forma semplificata secondo l’allegato XIII. Si gestiscono nel modulo del modello. Le categorie sono lmt, industrie, ev, sli e geraet.

Dati generali6
CampoNome tecnicoTipoVisibile perObbligatorio
Produttore (nome)manufacturer_nametextPubblicoTutte le categorie con passaporto
Produttore (indirizzo)manufacturer_addresstextPubblicoTutte le categorie con passaporto
Contatto (e-mail o sito web)manufacturer_contacttextPubblicoTutte le categorie con passaporto
Luogo di produzione (predefinito)manufacturing_placetextPubblicoTutte le categorie con passaporto
Pesoweight_kgnumber · kgPubblicoTutte le categorie con passaporto
GaranziawarrantytextPubblicoFacoltativo
Materiali e sostanze6
CampoNome tecnicoTipoVisibile perObbligatorio
Chimica della batteriachemistrytextPubblicoTutte le categorie con passaporto
Sostanze pericolosehazardous_substancestextPubblicoTutte le categorie con passaporto
Materie prime critichecritical_raw_materialstextPubblicoTutte le categorie con passaporto
Composizione del catodocomposition_cathodetextInteresse legittimoTutte le categorie con passaporto
Composizione dell'anodocomposition_anodetextInteresse legittimoTutte le categorie con passaporto
Composizione dell'elettrolitacomposition_electrolytetextInteresse legittimoTutte le categorie con passaporto
Prestazioni e durata11
CampoNome tecnicoTipoVisibile perObbligatorio
Capacità nominalerated_capacity_ahnumber · AhPubblicoTutte le categorie con passaporto
Tensione nominalenominal_voltage_vnumber · VPubblicoTutte le categorie con passaporto
Tensione minimamin_voltage_vnumber · VPubblicoTutte le categorie con passaporto
Tensione massimamax_voltage_vnumber · VPubblicoTutte le categorie con passaporto
Energia nominalerated_energy_kwhnumber · kWhPubblicoTutte le categorie con passaporto
Potenza (originale)rated_power_wnumber · WPubblicoindustrie, ev
Durata previstaexpected_lifetime_cyclesnumber · ZyklenPubblicoTutte le categorie con passaporto
Intervallo di temperatura datemp_min_cnumber · °CPubblicoTutte le categorie con passaporto
Intervallo di temperatura atemp_max_cnumber · °CPubblicoTutte le categorie con passaporto
Efficienza energetica (andata e ritorno)round_trip_efficiency_pctnumber · %Pubblicoindustrie, ev
Resistenza internainternal_resistance_mohmnumber · mΩPubblicoFacoltativo
Impronta di carbonio e contenuto riciclato6
CampoNome tecnicoTipoVisibile perObbligatorio
Impronta di carboniocarbon_footprintnumber · kg CO₂e/kWhPubblicoObbligo successivo
Contenuto di cobalto riciclatorecycled_cobalt_pctnumber · %PubblicoObbligo successivo
Contenuto di litio riciclatorecycled_lithium_pctnumber · %PubblicoObbligo successivo
Contenuto di nichel riciclatorecycled_nickel_pctnumber · %PubblicoObbligo successivo
Contenuto di piombo riciclatorecycled_lead_pctnumber · %PubblicoObbligo successivo
Quota di contenuto rinnovabilerenewable_content_pctnumber · %PubblicoFacoltativo
Conformità ed etichettatura4
CampoNome tecnicoTipoVisibile perObbligatorio
Dichiarazione UE di conformità (link)doc_urlurlPubblicoTutte le categorie con passaporto
Etichettatura e simbolilabels_symbolstextPubblicoTutte le categorie con passaporto
Relazione sulla dovuta diligenza (link)due_diligence_urlurlPubblicoObbligo successivo
Restituzione e smaltimentoend_of_life_infotextPubblicoTutte le categorie con passaporto
Smontaggio, riparazione e ricambi4
CampoNome tecnicoTipoVisibile perObbligatorio
Istruzioni di smontaggiodismantling_infotextInteresse legittimoTutte le categorie con passaporto
Codici dei componentipart_numberstextInteresse legittimoTutte le categorie con passaporto
Fonte dei ricambispare_parts_contacttextInteresse legittimoTutte le categorie con passaporto
Misure di sicurezzasafety_measurestextInteresse legittimoTutte le categorie con passaporto
Rapporti di prova1
CampoNome tecnicoTipoVisibile perObbligatorio
Rapporti di prova (link o riferimenti)test_reportstextAutorità e organismi di controlloTutte le categorie con passaporto

API REST

Disponibile

Crei modelli e passaporti direttamente da ERP, MES o BMS e segnali eventi. JSON su HTTPS, autenticazione con chiave. Indirizzo di base: https://app.batterypass2027.eu/api/v1

Inizi in tre passi

  1. Acceda come amministratore e apra Impostazioni, poi Chiavi API.
  2. Crei una chiave di prova. Viene mostrata una sola volta; la conservi come una password.
  3. Verifichi la connessione con GET /me. Se l’API risponde, chiave e percorso di rete sono corretti.
cURL
export BATTERYPASS_KEY="bp_test_..."

curl -s https://app.batterypass2027.eu/api/v1/me \
  -H "Authorization: Bearer $BATTERYPASS_KEY"

Una chiave, un’azienda

La chiave stabilisce quali dati sono raggiungibili. Si crea nell’app e viene mostrata una sola volta.

Le chiavi di prova non salvano nulla

Una chiave di prova verifica ogni richiesta come in produzione, senza modificare dati né consumare quota.

Ripetizione sicura

Con la stessa chiave di idempotenza non nasce un secondo record, nemmeno dopo un’interruzione. Il numero di documento dell’ERP è adatto.

I passaporti non vengono eliminati

L’API non prevede DELETE per i passaporti. La fine vita di una batteria viene segnalata come evento.

Le chiavi di prova rispondono con stato 200 e dry_run: true. Leggono dati reali ma non modificano nulla.

Endpoint

MetodoPercorsoA cosa serve
GET/meTest di connessione: azienda, piano, diritti e quota residua
GET/fieldsCatalogo dei campi con obblighi per categoria
GET/modelsElencare i modelli, anche per codice
POST/modelsCreare un modello
GET/models/{id}Leggere un modello con dati e campi obbligatori mancanti
PATCH/models/{id}Modificare i dati anagrafici
GET/passportsElencare i passaporti, anche per numero di serie o data di modifica
POST/passports/batchCreare fino a 1.000 passaporti in una chiamata
GET/passports/{id}Leggere un passaporto con indirizzo e stato
GET/passports/{id}/eventsLeggere gli eventi di un passaporto
POST/passports/{id}/eventsSegnalare un evento, ad es. riparazione o rifiuto
POST/models/validateVerificare una bozza senza salvare
POST/passportsCreare un passaporto
PATCH/passports/{id}Modificare data, lotto o luogo
GET/passports/{id}/componentsLeggere i componenti
POST/passports/{id}/componentsInstallare un componente
PATCH/passports/{id}/components/{cid}Modificare o rimuovere un componente
POST/passports/{id}/components/{cid}/replaceSostituire un componente
GET/passports/{id}/telemetryLeggere la serie di misurazioni
POST/passports/{id}/telemetrySegnalare misurazioni
GET/certificatesElencare i documenti
GET/certificates/{id}Documento con link di download
GET/suppliersElencare i fornitori
GET/supplier-requestsElencare le richieste
POST/supplier-requestsInviare una richiesta
GET/supplier-requests/{id}Leggere una richiesta con i valori
POST/supplier-requests/{id}/acceptAccettare i valori nel modello
GET/auditLeggere il registro di audit

Esempio: creare passaporti dall’ERP

curl -X POST https://app.batterypass2027.eu/api/v1/passports/batch \
  -H "Authorization: Bearer $BATTERYPASS_KEY" \
  -H "Idempotency-Key: erp-4711" \
  -H "Content-Type: application/json" \
  -d '{
  "model_code": "BX-48V",
  "on_conflict": "skip",
  "items": [
    { "serial": "SN-0001", "manufactured_at": "2027-03-01", "batch": "L2027-03" },
    { "serial": "SN-0002", "manufactured_at": "2027-03-01", "batch": "L2027-03" }
  ]
}'

Risposta

201 Created
HTTP/1.1 201 Created
X-Request-Id: req_4f7a91c2d03e8b56

{
  "created": 1,
  "skipped": 1,
  "skipped_serials": ["SN-0002"],
  "items": [
    {
      "id": "7KM2XQ9RTA",
      "serial": "SN-0001",
      "status": "original",
      "url": "https://app.batterypass2027.eu/p/7KM2XQ9RTA"
    }
  ]
}

Errori

422
HTTP/1.1 422 Unprocessable Entity

{
  "error": {
    "code": "invalid_serial",
    "message": "Serial number is missing or contains invalid characters.",
    "field": "items[3].serial",
    "request_id": "req_a03c5e17b92d4f68"
  }
}
HTTPCodeSignificato
400invalid_requestLa richiesta non è JSON valido o contiene campi sconosciuti
401unauthorizedChiave mancante o non valida
403insufficient_scopeAlla chiave manca il diritto necessario
403plan_requiredLe chiavi live richiedono il piano Pro o Enterprise
403email_not_verifiedL’indirizzo e-mail dell’azienda non è ancora confermato
403quota_exceededLa quota del piano è esaurita
404not_foundL’oggetto non esiste o appartiene a un’altra azienda
409duplicate_serialIl numero di serie esiste già in questo modello (con on_conflict: fail)
409duplicate_modelIl codice del modello è già in uso
409idempotency_conflictLa chiave di idempotenza è stata usata per un’altra richiesta
413payload_too_largeLa richiesta supera 2 MB
422invalid_serialUn numero di serie non è valido; la risposta indica il campo. Non viene salvato nulla.
422invalid_dateUna data non rispetta il formato AAAA-MM-GG
422out_of_rangeUna misurazione è fuori dall’intervallo consentito
422invalid_gtinIl GTIN ha lunghezza o cifra di controllo errate
422validation_failedUn altro valore viola le regole
429rate_limitedTroppe richieste; riprovare dopo Retry-After
500internal_errorErrore da parte nostra. Si può ripetere con la stessa chiave di idempotenza.

Limiti

Richieste al minuto per chiaveLive 300, prova 60
Passaporti per chiamata1.000
Dimensione di una richiesta2 MB
Voci per pagina di elenco100, massimo 500
Chiavi attive per azienda10
Chiavi livePro ed Enterprise. Le chiavi di prova sono in tutti i piani.

Prevede più di 100.000 passaporti all’anno? Ne parli prima con noi.

Autorizzazioni

Ogni chiave riceve solo i diritti necessari. Se ne manca uno, l’API risponde 403 e insufficient_scope. Nell’app si sceglie un modello: Tutti i diritti, ERP, BMS o Sola lettura.

DirittoConsente
models:readLeggere modelli e verificare bozze
models:writeCreare e modificare modelli
passports:readLeggere passaporti, eventi e componenti
passports:writeCreare e modificare passaporti, segnalare eventi, installare e sostituire componenti
telemetry:read telemetry:writeLeggere e segnalare misurazioni
certificates:readLeggere e scaricare documenti
suppliers:read suppliers:writeLeggere fornitori e richieste, inviare e accettare richieste
audit:readLeggere il registro di audit

Richieste e risposte

Gli elenchi arrivano a pagine con data, has_more e next_cursor. Passi next_cursor come cursor. I campi sconosciuti vengono rifiutati per rivelare subito gli errori. Con PATCH un campo assente non cambia e null lo svuota.

IntestazioneSignificato
Idempotency-KeyRipetizione senza secondo record, valida 7 giorni. Il numero di documento ERP è adatto.
X-Batterypass-Dry-Run: trueAnche una chiave live si limita a verificare questa richiesta senza salvare nulla.
X-Request-IdID della chiamata, anche negli errori e nel registro
X-RateLimit-Limit X-RateLimit-RemainingQuota del minuto corrente
Idempotent-Replayedtrue se è stata ripetuta una risposta salvata

SDK e console API

Disponibile

Due client leggeri senza dipendenze: ripetono le richieste in sicurezza, scorrono gli elenchi e dividono grandi volumi in chiamate da 1.000 passaporti. Sono file singoli da copiare nel progetto. La console API è nell’app in Impostazioni, Chiavi API.

from batterypass import Batterypass

bp = Batterypass("bp_test_...")
print(bp.me()["organization"]["plan"])

items = [{"serial": f"SN-{i:06}"} for i in range(5000)]
print(bp.create_passports_all("BX-48V", items))

for passport in bp.list_all("/passports", model_code="BX-48V"):
    print(passport["serial"], passport["url"])

Componenti

Disponibile

Registri quali moduli, celle o BMS sono installati. Un numero di serie può essere installato una sola volta per passaporto. In caso di sostituzione, il vecchio pezzo resta registrato con la data di rimozione.

cURL
curl -X POST https://app.batterypass2027.eu/api/v1/passports/7KM2XQ9RTA/components \
  -H "Authorization: Bearer $BATTERYPASS_KEY" -H "Content-Type: application/json" \
  -d '{"kind": "module", "label": "Modul 1", "serial": "M-0001", "supplier": "Zellwerk GmbH"}'

curl -X POST https://app.batterypass2027.eu/api/v1/passports/7KM2XQ9RTA/components/12/replace \
  -H "Authorization: Bearer $BATTERYPASS_KEY" -H "Content-Type: application/json" \
  -d '{"serial": "M-0002", "note": "Modul nach Defekt getauscht"}'

I tipi consentiti sono pack, rack, module, cell, bms e other.

Misurazioni

Disponibile

Segnali dati dal BMS, singolarmente o fino a 1.000 misurazioni con items. Legga la serie con since e until. Le misurazioni sono disponibili dal piano Pro. Compaiono nell’app, non nella pagina pubblica.

cURL
curl -X POST https://app.batterypass2027.eu/api/v1/passports/7KM2XQ9RTA/telemetry \
  -H "Authorization: Bearer $BATTERYPASS_KEY" -H "Content-Type: application/json" \
  -d '{"recorded_at": "2027-03-01T10:00:00Z", "soh_pct": 94.5, "cycle_count": 120}'
CampoIntervallo
recorded_atISO 8601
soh_pct0–100
soc_pct0–100
capacity_kwh≥ 0
remaining_capacity_ah≥ 0
internal_resistance_mohm≥ 0
cycle_count≥ 0, integer
temp_min_c temp_max_c≥ −273
energy_throughput_kwh≥ 0
negative_eventdeep_discharge, overheat, accident
notemax. 500

Documenti

Disponibile

Carichi rapporti di prova, dichiarazioni di conformità e documenti simili nel modello: PDF, PNG o JPG fino a 10 MB. Tramite API legge l’elenco e ottiene un link di download valido 15 minuti. Ogni file ha una somma SHA-256.

cURL
curl -s "https://app.batterypass2027.eu/api/v1/certificates?model_code=BX-48V" -H "Authorization: Bearer $BATTERYPASS_KEY"
curl -s https://app.batterypass2027.eu/api/v1/certificates/42 -H "Authorization: Bearer $BATTERYPASS_KEY"

Fornitori e richieste di dati

Disponibile

Richieda valori ai fornitori. Ricevono un’e-mail con un link valido 30 giorni e inseriscono solo i campi richiesti, senza account. I valori arrivano nel modello solo dopo la Sua approvazione. Disponibile dal piano Starter, massimo 20 richieste all’ora.

cURL
curl -X POST https://app.batterypass2027.eu/api/v1/supplier-requests \
  -H "Authorization: Bearer $BATTERYPASS_KEY" -H "Content-Type: application/json" \
  -d '{"model_code": "BX-48V", "supplier_name": "Zellwerk GmbH", "supplier_email": "daten@zellwerk.example",
       "fields": ["chemistry", "composition_cathode"], "message": "Bitte bis Monatsende"}'

curl -s "https://app.batterypass2027.eu/api/v1/supplier-requests?status=submitted" -H "Authorization: Bearer $BATTERYPASS_KEY"
curl -X POST https://app.batterypass2027.eu/api/v1/supplier-requests/7/accept -H "Authorization: Bearer $BATTERYPASS_KEY"

GS1 Digital Link

Disponibile

Imposti nel modello un GTIN con cifra di controllo valida. L’indirizzo GS1 da GTIN e numero di serie porta alla pagina del passaporto e compare nell’API come gs1_link. I codici QR contengono sempre l’indirizzo fisso, ma può creare i propri dal link GS1. Il GTIN si ottiene da GS1.

URL
https://app.batterypass2027.eu/01/{GTIN}/21/{SERIENNUMMER}
https://app.batterypass2027.eu/01/04012345678901/21/SN-0001

Registro di audit

Disponibile

GET /audit restituisce tutte le modifiche registrate, a pagine e facoltativamente da un momento con since. Le modifiche via API riportano il nome della chiave. Nell’app gli amministratori vedono anche le ultime chiamate.

Versioni

La versione principale è nel percorso. In v1 si aggiungono solo campi ed endpoint. Previsti ma non ancora disponibili: webhook, accesso per autorità e riciclatori e una catena di modifiche verificabile.

VersionDataModifica
1.1.02026-11-06Componenti, misurazioni, documenti, fornitori, audit, passaporto singolo, GS1, diritti granulari, intestazione dry-run, OpenAPI ed endpoint di stato
1.0.02026-11-06Modelli, passaporti, eventi, chiavi, modalità di prova, idempotenza

Domande frequenti

Risposte brevi per l’integrazione.

Come provo senza creare passaporti reali?

Con una chiave di prova. Verifica tutto come in produzione e non salva nulla.

Cosa fare dopo un timeout?

Invii di nuovo la stessa richiesta con la stessa chiave di idempotenza. Non nasce un secondo record.

Come trovo il passaporto di un numero di serie?

Con GET /passports?serial=… e se serve model_code.

Posso eliminare passaporti via API?

No. Segnali la fine vita come evento con lo stato waste.

Quanti passaporti sono possibili?

1.000 per chiamata, 300 chiamate al minuto. Anche il piano e il nostro hosting pongono limiti. Oltre 100.000 passaporti all’anno, ne parli prima con noi.

Provi l’importazione con il Suo file.

Il piano Pilot è gratuito e comprende un modello e 25 passaporti all’anno.