Full payload description

Below is an example of a complete payload for the deposit of a document class.

The payload for the deposit of any document class of Archive follows the same structure. The minimum payload contains only the mandatory information, while the complete payload allows a much more detailed deposit that enables precise indexing of documents.

AGID compliance and metadata requirements

The payload structure supports the metadata requirements defined by the Italian AgID Guidelines on Document Formation, Management, and Preservation – Allegato 5 (Metadata). These guidelines establish the metadata framework for documents subject to long-term preservation.

Some fields are always mandatory according to AgID requirements. The Archive service enforces these mandatory rules and will immediately reject any deposit request that does not include all required core metadata fields.

Multi-type document support

Archive supports over 100 document types (documentTypeCode), each with specific metadata requirements and validation rules. Beyond the structural information provided by Swagger, Archive provides an additional description system through the Document Tags service that defines type-specific behaviors, field requirements, validation rules, and subject constraints for each document type.

Service specification reference

Always refer to the latest updated TS Archive service specification sheet to understand any additional constraints or requirements that go beyond technical implementation details. The service specification may include organizational policies, administrative rules, or operational constraints that complement the technical API documentation.

Understanding the payload structure

Swagger describes the payload structure (field names and nesting). To understand which fields are required and what they mean for a specific document type, you must use the Document Tags service for that documentTypeCode (tag list, required flags, validation rules, defaults and subject constraints).

Refer to: Document API - Document tags

File metadata

"fileMetadata": {
  "externalApplicationId": "externalApplicationId",
  "hash_256": "3a6261d40bb0c8a46df3d6a03989d3f551c978937c5ef8ab1a4152c75fbc6663",
  "name": "nome-file.xml",
  "segnatura": "protocol_segnatura"
}

Meaning

• externalApplicationId: Identifier of the external system/application that is performing the deposit (used for traceability).
• hash_256: SHA-256 hash of the file content (integrity check).
• name: Original file name (including extension).
• segnatura (optional but mandatory in some cases for Public Administration): The field population is not validated by the Service. The document producer is required to populate it in cases where current regulations require it (mandatory for protocolled administrative documents).

Document holder and submitter identifiers

"holderUuid": "holder_id",
"submitterUuid": "submitter_id"

Meaning

• holderUuid: Identifier of the document holder (entity on which the document is archived).
• submitterUuid: Identifier of the user/system submitting the deposit.

Note: These UUIDs are position-specific identifiers that correspond to the unique company identifier in the TS One Platform company registry. Each UUID uniquely identifies an organization within the platform's master data registry.

Single-company vs. Multi-company scenarios:

• Single-company scenario: When the submitter is the same entity as the document holder (typical for single companies managing their own documents), both holderUuid and submitterUuid contain the same value (the company's UUID).
• Studio/multi-company scenario: When a studio or professional firm is performing preservation activities on behalf of managed third-party companies, the two values are different:
  • submitterUuid: The UUID of the studio performing the preservation
  • holderUuid: The UUID of the managed company (the actual document holder)

Detailed information of the deposited document

The details object contains the descriptive information of the deposited document. Some fields are common to all document types, while others (especially details.custom_metadata and some specialized paths) depend on the documentTypeCode and must be derived from Document Tags through fullPath.

Common fields (present for all document types)

The metadata below are defined by the Italian "Linee Guida sulla formazione, gestione e conservazione dei documenti informatici – Allegato 5 (I metadati)". For more detailed information about metadata definitions, please refer to: https://www.agid.gov.it/sites/default/files/repository_files/allegato_5_metadati.pdf

details.tipologia_documentale (mandatory)

Document type/category code used for document management and indexing. This value must be one of the available documentTypeCode values supported by the Archive system. The complete list of supported document types (over 100) can be retrieved through the Document Tags service, which provides the full catalog of available document type codes along with their specific metadata requirements and validation rules.

Refer to: Document API - Document tags

details.modalita_formazione (mandatory)

Document formation mode: describes how the document was generated (created, acquired, produced from transactions, generated from data sources). Values follow the formation modes defined by the Guidelines.

Allowed values:

Code	Formation Mode	Description
A	Creazione tramite software	Creation through the use of software tools that ensure the production of documents in the formats specified in Annex 2 of the Guidelines
B	Digitalizzazione di documento cartaceo	Acquisition of an electronic document via telematic means or on computer media; acquisition of the image copy on computer media of an analog document; acquisition of the electronic copy of an analog document
C	Acquisizione tramite moduli o formulari	Storage on computer media in digital format of information resulting from IT transactions or processes, or from the online submission of data through forms or templates made available to the user
D	Generazione a partire da banche dati	Generation or grouping, even automatically, of a set of data or records from one or more databases, even belonging to multiple interoperating entities, according to a predetermined logical structure and stored in static form

details.dati_registrazione (mandatory)

Registration metadata: associates a registration date and number to the document (protocolled or non-protocolled) and supports indexing/search.

Fields of details.dati_registrazione:

• .data (mandatory): Registration date/time (ISO-8601 dateTime) eg. "2020-01-01T00:00:00.000Z".

• .numero (mandatory): Registration/document number (e.g., invoice number when not protocolled, protocol number when protocolled).

• .tipologia_flusso (mandatory): Flow type of the document. Available values:

  Code	Italian	English
  I	Interno	Internal
  U	Uscita	Outgoing
  E	Entrata	Incoming

• .tipo_registro (mandatory): Register type used for the registration. Available values:

  Code	Name	Description
  NESSUNO	None	Can be used for normal companies. Not allowed for Public Administrations (PA).
  PROTOCOLLO_ORDINARIO_EMERGENZA	Protocol	Protocol register.
  REPERTORIO_REGISTRO	Register/Repertory	Other types of registers or repertories.

  Important: Public Administrations must use either PROTOCOLLO_ORDINARIO_EMERGENZA or REPERTORIO_REGISTRO. When any value other than NESSUNO is selected, the id_registro field becomes mandatory.

• id_registro (conditional): Identifier of the register in which the document is registered. Mandatory when tipo_registro is not NESSUNO.

Note: The meaning of "registration" is broad: even when a specific register is not identifiable, the document still has a registration date and number.

details.chiave_descrittiva (optional)

Descriptive key that summarizes the document content and improves retrieval/search.

Fields:

• oggetto (mandatory): Subject/object line of the document (free text).
• parole_chiave (optional): Keywords list used to improve search. Keywords are free text and are optional.

details.soggetti (mandatory, repeatable)

Subjects involved in the document (author, sender, recipient, assignee, operator, etc.). This metadata is recursive/repeatable and can contain multiple subjects.

Minimal information:

• ruolo (mandatory): Role of the subject in relation to the document (e.g., MITTENTE (Sender), DESTINATARIO (Recipient), ASSEGNATARIO (Assignee)).
• tipo_soggetto (mandatory): Subject type

The platform provides a rich subject structure with additional structured fields (e.g., nome, cognome, codice_fiscale, partita_iva, id_paese, codice_sdi, indirizzi_digitali_riferimento, denominazione_ufficio, ipa_amm, ipa_aoo, ipa_uor, etc.).

These implementation-specific fields help to:

• Separate structured data (e.g., nome and cognome for Fisical Person or vat_number for companies)
• Support international subjects with country identifiers (id_paese)
• Enable electronic invoicing integration via SDI codes (codice_sdi)
• Link to IPA registries for Italian Public Administrations (codice_ipa, codice_ipa_aoo, codice_ipa_uor)
• Track organizational hierarchies (administration, office, organizational unit)
• Capture digital contact points (indirizzi_digitali_riferimento for email/PEC addresses)

For detailed information regarding subject structures, including complete field lists, validation rules, and examples for each subject type (AS, PF, PG, PAI, PAE, SW, RUP), refer to: Subject Structure

details.classificazione (optional, mandatory for the public administration holders)

Document classification according to the classification plan.

Important: This field is optional from the Archive service perspective and the service does not perform validation on its content or presence. However, Public Administrations (PA) are required by AgID Guidelines to populate this field with proper classification metadata according to their classification plan. While the Archive platform does not enforce this requirement technically, PA holders must comply with this obligation to meet regulatory requirements.

Fields:

• .indice (optional): Classification code/index.
• .descrizione (optional): Full description of the classification index.
• .piano (optional): URI/reference of the published classification plan.

details.riservato (mandatory)

Reserved/confidential flag. Represents the security level for document access:

• True: The document is considered confidential/reserved
• False: The document is not considered confidential/reserved

This flag is intended to manage access to the document, indicating that only authorized personnel should be able to view it according to organizational policies and document management regulations.

Important: This value is used for archival tracking purposes only and does not impact authorization or access control within the Archive platform itself. Access control and permissions within the platform are managed separately through the TS One Platform user and role management system.

details.prodotto_software (optional)

Software product information used to generate/create the document. This metadata is optional and should be provided only when the software information is detectable or known.

Fields:

• .nome_prodotto (optional): Name of the software product used to create the document (e.g. "Lynfa").
• .versione_prodotto (optional): Version number or identifier of the software product (e.g., "16.0", "2021", "7.2.5").
• .produttore (optional): Name of the software manufacturer/producer (e.g., "Teamsystem SpA.").

Note: This information helps track document provenance.

details.verifica (conditional / required depending on formation mode)

Verification flags describing the presence of: digital signature, electronic seal, time stamp, and image copy compliance. In the Guidelines these checks are mandatory in specific formation modes.

Fields:

• .firmato_digitalmente: True if the document is digitally signed.
• .sigillato_elettronicamente: True if an electronic seal is applied.
• .marcatura_temporale: True if a time stamp is applied.
• .conformita_copie_immagine: True if the image copy conformity is present (relevant for image copies).

details.id_agg (optional, repeatable)

Identifiers of aggregations (fascicolo/series/series of fascicoli) the document belongs to. Repeatable.

Fields:

• tipo_aggregazione: Aggregation type (e.g., Fascicolo / Serie Documentale / Serie di Fascicoli).
• id_aggregazione: Aggregation identifier.

details.versione (mandatory)

Document version number (e.g., 1, 2, 3…).

details.tracciature_modifiche (optional)

Modification traceability metadata. Used to trace operations performed on the document such as annulment, correction, integration, or annotation. This block becomes useful when the document version is greater than 1 or in case of annulment.

Fields:

• .tipo (mandatory): Type of modification. Available values:

  Code	Italian	English
  ANNULLAMENTO	Annullamento	Annulment/Cancellation
  RETTIFICA	Rettifica	Correction/Rectification
  INTEGRAZIONE	Integrazione	Integration/Addition
  ANNOTAZIONE	Annotazione	Annotation/Note

• .soggetto_autore (mandatory): Information about the operator/user who performed the modification:

  • .nome (mandatory): First name of the operator.
  • .cognome (mandatory): Last name of the operator.
  • .codice_fiscale (mandatory): Tax code (Italian fiscal code) of the operator.
  • .indirizzi_digitali_riferimento (optional): Array of digital contact addresses (email/PEC) of the operator.

• .data (mandatory): Date/time when the modification was performed (ISO-8601 dateTime format, e.g., "2020-01-01T00:00:00.000Z").

• .id_versione_precedente (mandatory): Identifier of the previous document version (using the IdDoc structure):

  • .impronta: Hash/fingerprint of the previous version file (base64 encoded SHA-256).
  • .algoritmo: Hash algorithm used (typically "SHA-256").
  • .identificativo: Unique identifier of the previous version.

Note: The operator performing the modification should also be represented among details.soggetti with role "OPERATORE" (Operator).

details.identificativo_documento_primario (conditional)

Identifier of the "main/primary" document to which the current document is conceptually linked. In Allegato 5, this concept is represented as "IdIdentificativoDocumentoPrincipale" and uses the same structure as IdDoc (hash + algorithm + identifier).

Campi / Fields:

• .impronta: Hash/fingerprint of the primary document file, encoded in base64 (SHA-256 of the file content).
• .algoritmo: Algorithm used to calculate the fingerprint (typically "SHA-256").
• .identificativo: Unique identifier of the primary document assigned by the source document management system (not Archive ID).

When to use this field: This field is useful only when managing digital document aggregations that require conceptually linking documents to each other. This assumes the existence of at least two preserved documents with a logical primary-secondary relationship.

Usage example:

1. The primary document (main) will have identificativo_documento_primario empty or not populated.
2. The secondary documents (attachments, integrations, or related documents) will have identificativo_documento_primario populated with the information (impronta, algoritmo, identificativo) of the primary document to which they are conceptually linked.

This mechanism allows creating a hierarchical document structure while maintaining traceability of relationships between documents.

Important: Archive does not perform consistency checks on the document chain during deposit. The responsibility for ensuring the correctness and coherence of the primary-secondary document relationships (e.g., verifying that the primary document exists, that the hash matches, that the chain is logically consistent) remains with the depositing software/system. The Archive platform accepts and stores the provided metadata without validating the actual existence or integrity of the referenced primary document.

details.allegati (mandatory)

Attachment indexing metadata. Indicates the number of attachments and, if greater than zero, provides an index list with an identifier and a title/description for each attachment.

Fields:

• numero_allegati (mandatory): Number of attachments (0..999).
• indice_allegati (conditional): Mandatory when numero_allegati > 0. Repeatable list of:
  • id_doc: Attachment document identifier (IdDoc structure).
  • descrizione: Attachment title/description.

details.note (optional)

Free-text additional information/notes.

details.custom_metadata (type-specific / platform-specific)

Custom metadata fields required by specific document types (documentTypeCode). These fields are not part of the canonical Allegato 5 list; they are defined by the platform via Document Tags and must be populated under details.custom_metadata using the provided fullPath mapping (for example: details.custom_metadata.sezionale).

Type-specific fields (Document Tags)

For each documentTypeCode, the Document Tags service returns:

• The full list of tags with fullPath, data type, required flag, and validation rules.
• Which tags must be provided as details.custom_metadata.*.
• Default values applied when a field is not provided.
• Subject constraints (allowed roles/types) and possible autofill rules.

Deposit procedure:

1. Select the documentTypeCode.
2. Call Document Tags for that type.
3. Use each tag fullPath as the authoritative mapping to the payload field to fill (including details.custom_metadata.*).
4. Respect required flags and validation rules (length, patterns, enums, etc.).
5. Apply defaults and subject constraints indicated by Document Tags.

Refer to: Document API - Document tags

---

Quick checklist (to avoid missing mandatory Allegato 5 metadata)

For every deposit, ensure you always provide:

• fileMetadata
• submitterUUid
• holderUUid
• details.modalita_formazione
• details.tipologia_documentale
• details.dati_registrazione
• details.chiave_descrittiva
• details.soggetti
• details.riservato
• details.allegati
• details.versione

Other blocks are optional/conditional based on scenario.

Example

"details": {
  "modalita_formazione": "A",
  "tipologia_documentale": "1001",
  "dati_registrazione": {
    "tipologia_flusso": "U",
    "tipo_registro": "NESSUNO",
    "data": "2020-01-01T00:00:00.000Z",
    "numero": "08399238740"
  },
  "chiave_descrittiva": {
    "oggetto": "oggetto",
    "parole_chiave": [
      "parola_chiave_1",
      "parola_chiave_2",
      "parola_chiave_3"
    ]
  },
  "soggetti": [
    {
      "ruolo": "ASSEGNATARIO",
      "tipo": "AS",
      "denominazione": "nominativo",
      "denominazione_ufficio": "denominazione_ufficio",
      "codice_fiscale": "AAAAAAAA0A00A000A",
      "indirizzi_digitali_riferimento": ["pec@mail.it"],
      "codice_sdi": "abc0123"
    },
    {
      "ruolo": "SER",
      "tipo": "PF",
      "cognome": "cognome",
      "nome": "nome",
      "matricola": "matricola",
      "codice_fiscale": "AAAAAAAA0A00A000A",
      "partita_iva": "00000000000",
      "indirizzi_digitali_riferimento": ["pec@mail.it"],
      "codice_sdi": "abc0123",
      "id_paese": "IT"
    }
  ],
  "classificazione": {
    "indice": "indice",
    "descrizione": "descrizione",
    "piano": "piano"
  },
  "riservato": true,
  "verifica": {
    "firmato_digitalmente": true,
    "sigillato_elettronicamente": true,
    "marcatura_temporale": true,
    "conformita_copie_immagine": true
  },
  "id_agg": [
    {
      "tipo_aggregazione": "FASCICOLO",
      "id_aggregazione": "id_aggregazione"
    }
  ],
  "identificativo_documento_primario": {
    "impronta": "N/w8pua3nHwlVGA7CGE/0b5O5Pwg0deyvmCm7/tzbok=",
    "algoritmo": "algoritmo",
    "identificativo": "identificativo"
  },
  "versione": "1",
  "tracciature_modifiche": {
    "tipo": "ANNULLAMENTO",
    "soggetto_autore": {
      "nome": "nome",
      "cognome": "cognome",
      "codice_fiscale": "AAAAAA84D07F712P",
      "indirizzi_digitali_riferimento": [
        "mail_1@mail.com",
        "mail_2@mail.com"
      ]
    },
    "data": "2020-01-01T00:00:00.000Z",
    "id_versione_precedente": {
      "impronta": "N/w8pua3nHwlVGA7CGE/0b5O5Pwg0deyvmCm7/tzbok=",
      "algoritmo": "algoritmo",
      "identificativo": "identificativo"
    }
  },
  "allegati": {
    "numero_allegati": 999,
    "indice_allegati": [
      {
        "id_doc": {
          "impronta": "stringstringstringstringstringstringstringst",
          "algoritmo": "string",
          "identificativo": "string"
        },
        "descrizione": "string"
      }
    ]
  },
  "prodotto_software": {
    "nome": "string",
    "versione": "string",
    "produttore": "string"
  },
  "anno_riferimento": 2019,
  "note": "note",
  "custom_metadata": {
    "sezionale": "sezionale",
    "pec_destinatario": "pec_destinatario"
  }
}