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.
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.
- AziendaIl Suo account con utenti e piano
- ModelloDati anagrafici, una volta per modello
- PassaportoUna batteria con numero di serie e indirizzo proprio
- EventoRiparazione, riconversione o rifiuto
| Via | A cosa serve | Stato |
|---|---|---|
| Importazione CSV | Riprendere i numeri di serie da ERP, MES o Excel | Disponibile |
| Esportazione CSV | Riportare ID e indirizzi nei Suoi sistemi | Disponibile |
| Indirizzo del passaporto e codice QR | Creare etichette proprie o collegare i passaporti | Disponibile |
| API REST | Creare modelli e passaporti automaticamente, senza caricamenti manuali | Disponibile |
Importazione CSV
DisponibileLa via abituale dall’ERP: esportare un elenco e caricarlo in un modello. Ogni nuovo numero di serie riceve un passaporto.
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
| Regola | Specifica |
|---|---|
| Codifica | UTF-8 con o senza BOM. Windows-1252 viene rilevato e convertito. |
| Separatore | Punto e virgola, virgola o tabulazione. Decide la prima riga. |
| Dimensione | Massimo 8 MB e 50.000 righe per file. |
| Struttura | Una batteria per riga, senza interruzioni di riga in un campo. |
| Intestazione | Facoltativa. Con l’intestazione le colonne possono avere qualsiasi ordine e quelle aggiuntive vengono ignorate. Senza, vale l’ordine della tabella qui sotto. |
| Colonna | Campo | Nomi di colonna riconosciuti | Obbligatorio | Regola |
|---|---|---|---|---|
| 1 | Numero di serie | seriennummer, serialnummer, serial, serial number, serialnumber, serial no, sn, serien-nr, seriennr, sernr | Sì | Massimo 120 caratteri: lettere, cifre, spazi e - _ . / : |
| 2 | Data di produzione | herstelldatum, produktionsdatum, fertigungsdatum, manufacturing date, production date, date, datum | Facoltativo | 2027-03-01, 01.03.2027, 1.3.2027, 01/03/2027, 1/3/2027 o 2027/03/01 |
| 3 | Lotto | charge, chargennummer, batch, lot, los | Facoltativo | Massimo 120 caratteri |
| 4 | Luogo di produzione | herstellort, produktionsort, werk, place, plant, manufacturing place | Facoltativo | Massimo 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
DisponibileVerifichi 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.
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;freiEsportazione CSV
DisponibilePer 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.
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
DisponibileOgni passaporto ha un indirizzo fisso. A un codice QR, a un link nel manuale o a una voce dell’ERP non serve altro.
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
# 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
DisponibileQuesti 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
| Campo | Nome tecnico | Tipo | Visibile per | Obbligatorio |
|---|---|---|---|---|
| Produttore (nome) | manufacturer_name | text | Pubblico | Tutte le categorie con passaporto |
| Produttore (indirizzo) | manufacturer_address | text | Pubblico | Tutte le categorie con passaporto |
| Contatto (e-mail o sito web) | manufacturer_contact | text | Pubblico | Tutte le categorie con passaporto |
| Luogo di produzione (predefinito) | manufacturing_place | text | Pubblico | Tutte le categorie con passaporto |
| Peso | weight_kg | number · kg | Pubblico | Tutte le categorie con passaporto |
| Garanzia | warranty | text | Pubblico | Facoltativo |
Materiali e sostanze6
| Campo | Nome tecnico | Tipo | Visibile per | Obbligatorio |
|---|---|---|---|---|
| Chimica della batteria | chemistry | text | Pubblico | Tutte le categorie con passaporto |
| Sostanze pericolose | hazardous_substances | text | Pubblico | Tutte le categorie con passaporto |
| Materie prime critiche | critical_raw_materials | text | Pubblico | Tutte le categorie con passaporto |
| Composizione del catodo | composition_cathode | text | Interesse legittimo | Tutte le categorie con passaporto |
| Composizione dell'anodo | composition_anode | text | Interesse legittimo | Tutte le categorie con passaporto |
| Composizione dell'elettrolita | composition_electrolyte | text | Interesse legittimo | Tutte le categorie con passaporto |
Prestazioni e durata11
| Campo | Nome tecnico | Tipo | Visibile per | Obbligatorio |
|---|---|---|---|---|
| Capacità nominale | rated_capacity_ah | number · Ah | Pubblico | Tutte le categorie con passaporto |
| Tensione nominale | nominal_voltage_v | number · V | Pubblico | Tutte le categorie con passaporto |
| Tensione minima | min_voltage_v | number · V | Pubblico | Tutte le categorie con passaporto |
| Tensione massima | max_voltage_v | number · V | Pubblico | Tutte le categorie con passaporto |
| Energia nominale | rated_energy_kwh | number · kWh | Pubblico | Tutte le categorie con passaporto |
| Potenza (originale) | rated_power_w | number · W | Pubblico | industrie, ev |
| Durata prevista | expected_lifetime_cycles | number · Zyklen | Pubblico | Tutte le categorie con passaporto |
| Intervallo di temperatura da | temp_min_c | number · °C | Pubblico | Tutte le categorie con passaporto |
| Intervallo di temperatura a | temp_max_c | number · °C | Pubblico | Tutte le categorie con passaporto |
| Efficienza energetica (andata e ritorno) | round_trip_efficiency_pct | number · % | Pubblico | industrie, ev |
| Resistenza interna | internal_resistance_mohm | number · mΩ | Pubblico | Facoltativo |
Impronta di carbonio e contenuto riciclato6
| Campo | Nome tecnico | Tipo | Visibile per | Obbligatorio |
|---|---|---|---|---|
| Impronta di carbonio | carbon_footprint | number · kg CO₂e/kWh | Pubblico | Obbligo successivo |
| Contenuto di cobalto riciclato | recycled_cobalt_pct | number · % | Pubblico | Obbligo successivo |
| Contenuto di litio riciclato | recycled_lithium_pct | number · % | Pubblico | Obbligo successivo |
| Contenuto di nichel riciclato | recycled_nickel_pct | number · % | Pubblico | Obbligo successivo |
| Contenuto di piombo riciclato | recycled_lead_pct | number · % | Pubblico | Obbligo successivo |
| Quota di contenuto rinnovabile | renewable_content_pct | number · % | Pubblico | Facoltativo |
Conformità ed etichettatura4
| Campo | Nome tecnico | Tipo | Visibile per | Obbligatorio |
|---|---|---|---|---|
| Dichiarazione UE di conformità (link) | doc_url | url | Pubblico | Tutte le categorie con passaporto |
| Etichettatura e simboli | labels_symbols | text | Pubblico | Tutte le categorie con passaporto |
| Relazione sulla dovuta diligenza (link) | due_diligence_url | url | Pubblico | Obbligo successivo |
| Restituzione e smaltimento | end_of_life_info | text | Pubblico | Tutte le categorie con passaporto |
Smontaggio, riparazione e ricambi4
| Campo | Nome tecnico | Tipo | Visibile per | Obbligatorio |
|---|---|---|---|---|
| Istruzioni di smontaggio | dismantling_info | text | Interesse legittimo | Tutte le categorie con passaporto |
| Codici dei componenti | part_numbers | text | Interesse legittimo | Tutte le categorie con passaporto |
| Fonte dei ricambi | spare_parts_contact | text | Interesse legittimo | Tutte le categorie con passaporto |
| Misure di sicurezza | safety_measures | text | Interesse legittimo | Tutte le categorie con passaporto |
Rapporti di prova1
| Campo | Nome tecnico | Tipo | Visibile per | Obbligatorio |
|---|---|---|---|---|
| Rapporti di prova (link o riferimenti) | test_reports | text | Autorità e organismi di controllo | Tutte le categorie con passaporto |
API REST
DisponibileCrei 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
- Acceda come amministratore e apra Impostazioni, poi Chiavi API.
- Crei una chiave di prova. Viene mostrata una sola volta; la conservi come una password.
- Verifichi la connessione con GET /me. Se l’API risponde, chiave e percorso di rete sono corretti.
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
| Metodo | Percorso | A cosa serve |
|---|---|---|
| GET | /me | Test di connessione: azienda, piano, diritti e quota residua |
| GET | /fields | Catalogo dei campi con obblighi per categoria |
| GET | /models | Elencare i modelli, anche per codice |
| POST | /models | Creare un modello |
| GET | /models/{id} | Leggere un modello con dati e campi obbligatori mancanti |
| PATCH | /models/{id} | Modificare i dati anagrafici |
| GET | /passports | Elencare i passaporti, anche per numero di serie o data di modifica |
| POST | /passports/batch | Creare fino a 1.000 passaporti in una chiamata |
| GET | /passports/{id} | Leggere un passaporto con indirizzo e stato |
| GET | /passports/{id}/events | Leggere gli eventi di un passaporto |
| POST | /passports/{id}/events | Segnalare un evento, ad es. riparazione o rifiuto |
| POST | /models/validate | Verificare una bozza senza salvare |
| POST | /passports | Creare un passaporto |
| PATCH | /passports/{id} | Modificare data, lotto o luogo |
| GET | /passports/{id}/components | Leggere i componenti |
| POST | /passports/{id}/components | Installare un componente |
| PATCH | /passports/{id}/components/{cid} | Modificare o rimuovere un componente |
| POST | /passports/{id}/components/{cid}/replace | Sostituire un componente |
| GET | /passports/{id}/telemetry | Leggere la serie di misurazioni |
| POST | /passports/{id}/telemetry | Segnalare misurazioni |
| GET | /certificates | Elencare i documenti |
| GET | /certificates/{id} | Documento con link di download |
| GET | /suppliers | Elencare i fornitori |
| GET | /supplier-requests | Elencare le richieste |
| POST | /supplier-requests | Inviare una richiesta |
| GET | /supplier-requests/{id} | Leggere una richiesta con i valori |
| POST | /supplier-requests/{id}/accept | Accettare i valori nel modello |
| GET | /audit | Leggere 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" }
]
}'
import os
import requests
res = requests.post(
"https://app.batterypass2027.eu/api/v1/passports/batch",
headers={
"Authorization": f"Bearer {os.environ['BATTERYPASS_KEY']}",
"Idempotency-Key": "erp-4711",
},
json={
"model_code": "BX-48V",
"on_conflict": "skip",
"items": [{"serial": "SN-0001", "manufactured_at": "2027-03-01"}],
},
timeout=30,
)
res.raise_for_status()
print(res.json()["created"])
const res = await fetch("https://app.batterypass2027.eu/api/v1/passports/batch", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.BATTERYPASS_KEY}`,
"Idempotency-Key": "erp-4711",
"Content-Type": "application/json",
},
body: JSON.stringify({
model_code: "BX-48V",
on_conflict: "skip",
items: [{ serial: "SN-0001", manufactured_at: "2027-03-01" }],
}),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log((await res.json()).created);
<?php
$ch = curl_init("https://app.batterypass2027.eu/api/v1/passports/batch");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("BATTERYPASS_KEY"),
"Idempotency-Key: erp-4711",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"model_code" => "BX-48V",
"on_conflict" => "skip",
"items" => [["serial" => "SN-0001", "manufactured_at" => "2027-03-01"]],
]),
]);
echo curl_exec($ch);
Risposta
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
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"
}
}
| HTTP | Code | Significato |
|---|---|---|
400 | invalid_request | La richiesta non è JSON valido o contiene campi sconosciuti |
401 | unauthorized | Chiave mancante o non valida |
403 | insufficient_scope | Alla chiave manca il diritto necessario |
403 | plan_required | Le chiavi live richiedono il piano Pro o Enterprise |
403 | email_not_verified | L’indirizzo e-mail dell’azienda non è ancora confermato |
403 | quota_exceeded | La quota del piano è esaurita |
404 | not_found | L’oggetto non esiste o appartiene a un’altra azienda |
409 | duplicate_serial | Il numero di serie esiste già in questo modello (con on_conflict: fail) |
409 | duplicate_model | Il codice del modello è già in uso |
409 | idempotency_conflict | La chiave di idempotenza è stata usata per un’altra richiesta |
413 | payload_too_large | La richiesta supera 2 MB |
422 | invalid_serial | Un numero di serie non è valido; la risposta indica il campo. Non viene salvato nulla. |
422 | invalid_date | Una data non rispetta il formato AAAA-MM-GG |
422 | out_of_range | Una misurazione è fuori dall’intervallo consentito |
422 | invalid_gtin | Il GTIN ha lunghezza o cifra di controllo errate |
422 | validation_failed | Un altro valore viola le regole |
429 | rate_limited | Troppe richieste; riprovare dopo Retry-After |
500 | internal_error | Errore da parte nostra. Si può ripetere con la stessa chiave di idempotenza. |
Limiti
| Richieste al minuto per chiave | Live 300, prova 60 |
| Passaporti per chiamata | 1.000 |
| Dimensione di una richiesta | 2 MB |
| Voci per pagina di elenco | 100, massimo 500 |
| Chiavi attive per azienda | 10 |
| Chiavi live | Pro 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.
| Diritto | Consente |
|---|---|
models:read | Leggere modelli e verificare bozze |
models:write | Creare e modificare modelli |
passports:read | Leggere passaporti, eventi e componenti |
passports:write | Creare e modificare passaporti, segnalare eventi, installare e sostituire componenti |
telemetry:read telemetry:write | Leggere e segnalare misurazioni |
certificates:read | Leggere e scaricare documenti |
suppliers:read suppliers:write | Leggere fornitori e richieste, inviare e accettare richieste |
audit:read | Leggere 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.
| Intestazione | Significato |
|---|---|
Idempotency-Key | Ripetizione senza secondo record, valida 7 giorni. Il numero di documento ERP è adatto. |
X-Batterypass-Dry-Run: true | Anche una chiave live si limita a verificare questa richiesta senza salvare nulla. |
X-Request-Id | ID della chiamata, anche negli errori e nel registro |
X-RateLimit-Limit X-RateLimit-Remaining | Quota del minuto corrente |
Idempotent-Replayed | true se è stata ripetuta una risposta salvata |
SDK e console API
DisponibileDue 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"])
import { Batterypass } from "./batterypass.mjs";
const bp = new Batterypass({ apiKey: process.env.BATTERYPASS_KEY });
console.log((await bp.me()).organization.plan);
const items = Array.from({ length: 5000 }, (_, i) => ({ serial: `SN-${i}` }));
console.log(await bp.createPassportsAll("BX-48V", items));
for await (const passport of bp.listAll("/passports", { model_code: "BX-48V" })) {
console.log(passport.serial, passport.url);
}
Componenti
DisponibileRegistri 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 -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
DisponibileSegnali 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 -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}'
| Campo | Intervallo |
|---|---|
recorded_at | ISO 8601 |
soh_pct | 0–100 |
soc_pct | 0–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_event | deep_discharge, overheat, accident |
note | max. 500 |
Documenti
DisponibileCarichi 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 -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
DisponibileRichieda 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 -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
DisponibileImposti 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.
https://app.batterypass2027.eu/01/{GTIN}/21/{SERIENNUMMER}
https://app.batterypass2027.eu/01/04012345678901/21/SN-0001
Registro di audit
DisponibileGET /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.
| Version | Data | Modifica |
|---|---|---|
1.1.0 | 2026-11-06 | Componenti, misurazioni, documenti, fornitori, audit, passaporto singolo, GS1, diritti granulari, intestazione dry-run, OpenAPI ed endpoint di stato |
1.0.0 | 2026-11-06 | Modelli, 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.