Aggiornare un campo su un passaporto

Applica una patch a un singolo campo su un passaporto. Il valore viene convalidato rispetto alla chiave del campo (deve esistere nel template del passaporto) e persistito con una voce di traccia di controllo che indica la credenziale (via API key <prefix> o via OAuth app <client>) e, quando l'header X-Source è impostato, il client chiamante, ad es. (mcp). Preferite questo alla scrittura dell'intera mappa fields quando dovete aggiornare un solo numero — è una scrittura più piccola e la voce di controllo per campo è ciò che vedono i revisori della dashboard.

Lo stato dipende da chi scrive, non dal canale. Una chiave API scrive status: "approved" (è un account di servizio a livello aziendale). Un token OAuth scrive con i diritti di dashboard del proprio utente, quindi un ruolo inferiore ad admin finisce in pending_review. Un valore inviato con source: "ai_suggested" finisce sempre in pending_review ed è rifiutato con 400 su un campo che solo l'operatore economico può dichiarare o che deve essere misurato (ad es. stateOfHealth di una batteria); inviatelo con un'altra fonte se è la vostra organizzazione a fare quella dichiarazione. ai_approved e system sono impostati da TracePass e vengono rifiutati come valori della richiesta.

Esiste una forma di indirizzamento alternativa su PATCH /api/v1/passports/by-serial/{serial}/fields/{key} — stesso corpo, stessa risposta, utile quando il vostro ERP conosce solo il numero di serie lato cliente. Conta come una scrittura v1. Rispetta Idempotency-Key.

No-op (200 unchanged: true): quando il valore in entrata, lo stato calcolato e il locale di origine sono tutti identici allo stato memorizzato, l'endpoint salta interamente la scrittura — nessun incremento di versione, nessuna voce di audit, nessuno snapshot — e restituisce 200 con unchanged: true insieme al campo e alla versione correnti. La struttura del corpo della risposta è la stessa di una scrittura reale; controllate la chiave unchanged per distinguere i due casi.

Protezione dei campi obbligatori (400): una volta pubblicato un passaporto, inviare null o una stringa vuota per un campo che il regolamento richiede per la categoria del passaporto viene rifiutato con required_field_empty (HTTP 400). L'array fields nel corpo della risposta indica ogni chiave interessata. Le bozze rimangono liberamente modificabili.

Limiti di dimensione (400 / 413): un valore può contenere al massimo 1.000 elementi di array (inclusi quelli annidati), 20.000 caratteri in ciascuna stringa (ogni lingua di un valore traducibile conta a sé) e 256 KB in totale, con al massimo 8 livelli di annidamento. Un valore più grande viene rifiutato con field_value_too_large, indicando il campo, il tipo di limite (items, characters, bytes o depth) e il limite. Un corpo della richiesta dichiarato superiore a 1 MB viene rifiutato con 413 payload_too_large.

Blocco di scrittura (409): una volta pubblicato un passaporto, i campi di identità (gtin, serialNumber, uniqueProductIdentifier, globalUniqueProductIdentifier, productIdentifier, identifierStandard, batteryUniqueIdentifier, batteryIdDmcCode, batteryPassportIdentifier) non possono più cambiare se contengono già un valore approved — la risposta è 409 identifier_locked con i nomi dei campi in keys. Un valore pending_review può essere corretto; un campo vuoto può essere compilato. Riscrivere lo stesso valore (incluso un GTIN con o senza zero iniziale di riempimento a 14 cifre, o corrispondenza dopo rimozione degli spazi) è accettato quando la scrittura mantiene il valore approvato, come fa una chiave API. Una scrittura con source: "ai_suggested", o da un utente OAuth sotto il livello admin, arriva come pending_review e viene rifiutata. Una scrittura su un passaporto archiviato restituisce 409 passport_archived. Una race di scrittura concorrente restituisce 409 concurrent_update — ricaricare e riprovare. I passaporti sospesi e scaduti rimangono modificabili.