TracePass
Inizia ora
Passaporti

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 contrassegnata `via API key <prefix>`. 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.

PATCH/api/v1/passports/{id}/fields/{key}
Scarica OpenAPI 3.1
PATCH/api/v1/passports/{id}/fields/{key}

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 contrassegnata `via API key <prefix>`. 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.

Le scritture predefinite hanno `status: "approved"` — le integrazioni guidate da chiave API sono affidabili per convenzione (a differenza degli editor della dashboard, dove i non amministratori scrivono `pending_review`). Sovrascrivete con `source: "ai_suggested"` o `source: "supplier"` se volete che il valore finisca invece nella coda di revisione.

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

Parametri di percorso

  • idobbligatorio

    ObjectId

    ID del passaporto. Per indirizzare invece tramite numero di serie, usate PATCH /api/v1/passports/by-serial/{serial}/fields/{key}.

    e.g. 6650b2c3d4e5f6a7b8c9d0e1

  • keyobbligatorio

    string

    Chiave del campo (snake_case) come definita nel template del passaporto — es. `nominal_voltage`, `recycled_content_pct`, `country_of_origin`. 400 se la chiave non è nel template.

    e.g. rated_capacity_kwh

Header

  • Authorizationobbligatorio

    string

    `Bearer <api-key>`.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

  • Idempotency-Key

    string

    UUID v4 per operazione logica.

Campi del corpo

  • valueobbligatorio

    string | number | boolean | array | object

    Nuovo valore. La piattaforma non riformatta le stringhe in numeri — inviate il valore nel tipo che il campo del template si aspetta.

    e.g. 5.24

  • source

    enum

    Contrassegna l'origine del valore. Uno tra: `manual`, `ai_suggested`, `ai_approved`, `reference_db`, `supplier`, `system`. Predefinito `manual`. `ai_suggested` e `supplier` finiscono nella coda di revisione; tutto il resto viene scritto come approved.

  • sourceLocale

    string (ISO 639-1)

    Locale del valore (uno dei 24 locale dell'UE). Governa la direzione della traduzione + la risoluzione della lingua del visualizzatore pubblico. Per impostazione predefinita è il `sourceLocale` del passaporto quando omesso.

Richiesta

curl -sS -X PATCH \
  https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1/fields/rated_capacity_kwh \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "value": 5.24 }'

Risposta

{
  "field": {
    "value": 5.24,
    "source": "manual",
    "status": "approved",
    "accessLevel": "public",
    "sourceLocale": "en",
    "lastUpdatedAt": "2026-05-09T10:30:00.000Z",
    "lastUpdatedBy": "api_key:tp_89b2482d"
  },
  "version": 4
}

Endpoint correlati