Formato dell'Evento di Sottoscrizione

Per la referenza canonica dello schema compatibile con AI, vedere Subscription Event Schema.

Le sottoscrizioni GraphQL restituiscono un involucro di consegna sottile e una busta evento codificata in JSON.

Involucro di Consegna

Le risposte del feed utente appaiono così:

{
  "data": "{\"version\":\"1.0\",\"eventId\":\"evt...\",\"timestamp\":\"2026-04-24T10:38:36.822Z\",\"level\":\"INFO\",\"event\":\"recipientVisiting\",\"category\":\"recipientLifecycle\",\"groupId\":\"grp...\",\"userId\":\"usr...\",\"requestId\":null,\"batchId\":null,\"error\":null,\"data\":{\"id\":\"rec...\",\"documentId\":\"doc...\",\"documentName\":\"Example document\",\"firstName\":\"Ada\",\"lastName\":\"Lovelace\"}}",
  "userId": "..."
}

Le risposte del feed di gruppo usano groupId invece di userId nell'involucro esterno.

L'involucro identifica il canale di sottoscrizione. La stringa interna data è il payload evento canonico.

Busta Evento

Dopo aver analizzato data, ricevi:

{
  "version": "1.0",
  "eventId": "evt...",
  "timestamp": "2026-04-24T10:38:36.822Z",
  "level": "INFO",
  "event": "recipientVisiting",
  "category": "recipientLifecycle",
  "groupId": "grp...",
  "userId": "usr...",
  "requestId": null,
  "batchId": null,
  "error": null,
  "data": {
    "id": "rec...",
    "documentId": "doc...",
    "documentName": "Example document",
    "firstName": "Ada",
    "lastName": "Lovelace"
  }
}

Campi della Busta

Campo	Descrizione
version	Versione della busta evento. Attualmente 1.0.
eventId	ID evento logico stabile. Le copie fanout dello stesso evento condividono lo stesso valore.
timestamp	Timestamp evento in formato ISO-8601.
level	Severità dell'evento. Attualmente solitamente INFO.
event	Nome evento canonico come documentArchived o uploadCompleted.
category	Famiglia dell'evento. Descrive come interpretare data.
groupId	Contesto del gruppo quando applicabile.
userId	Contesto utente quando applicabile.
requestId	ID di correlazione della richiesta quando disponibile.
batchId	Contesto batch quando disponibile.
error	Payload dell'errore quando applicabile, altrimenti null.
data	Payload specifico per categoria.

Categorie

Categorie attuali:

• document
• recipient
• documentLifecycle
• recipientLifecycle
• template
• task
• upload
• credit

category indica a quale oggetto o flusso di lavoro si riferisce l'evento. event indica cosa è successo.

Strutture dei Dati

data è specifico per categoria e estendibile in avanti:

• I produttori possono aggiungere campi nel tempo.
• I produttori non devono rimuovere campi esistenti in modo incompatibile.
• I consumatori devono ignorare i campi che non riconoscono.

Forme base attuali:

// document
{ "id": "doc..." }

// recipient
{ "id": "rec...", "documentId": "doc..." }

// documentLifecycle
{ "id": "doc...", "documentName": "Example document" }

// recipientLifecycle
{
  "id": "rec...",
  "documentId": "doc...",
  "documentName": "Example document",
  "firstName": "Ada",
  "lastName": "Lovelace"
}

// template
{ "id": "tpl..." }

// task
{ "id": "tsk...", "code": "TSKPROCESSOK", "documents": [] }

// upload
{ "id": "tmp...", "key": "upload/usr.../tmp....pdf", "code": "UPLOADOK" }

// credit
{ "credit": 172 }

I dati di lifecycle più ricchi sono attualmente popolati in modo più consistente per gli eventi documentLifecycle e recipientLifecycle.