Creazione ed aggiornamento item

Processi per creare e modificare item nell'anagrafica di TS Digital

Struttura di un Item

Pagina in costruzione, le informazioni riportate potrebbero essere inaccurate o incomplete

L'item è l'entità base fornita dall'anagrafica di TSDigital e contiene le informazioni necessarie a rappresentare aziende (compresi studi commercialisti), condomini e persone fisiche.

L'item è suddiviso in due sezioni principali: base e preferences.

Base

La sezione base di un item contiene tutte le informazioni anagrafiche, ed è a sua volta suddivisa nelle sottosezioni details, identifier e status. Ha il seguente formato:

{
  "id": "string",
  "identifier": {...},
  "details": {...},
  "status": {...},
  "hierarchyId": "string",
  "parentId": "string",
  "holdingId": "string",
  "ncsId": "string"
}

Identifier

L'identifier di un item contiene tutti i dati che lo identificano univocamente all'interno dell'anagrafica. Non possono quindi esistere due item che abbiano identifier interamente identici. Ha il seguente formato:

{
    "govCode": "string",
    "taxId": "string",
    "taxRegion": "string",
    "vatNumber": "string"
}

L'univocità di un item è data dall'intero insieme di elementi presenti nell'identifier. Due item possono, ad esempio, avere lo stesso taxId a patto di avere taxRegion differente.

Details

I details racchiudono tutte le informazioni anagrafiche dell'item che non siano necessarie per identificarlo univocamente. Ha il seguente formato:

{
  "classifier": "string",
  "description": "string",
  "firstName": "string",
  "lastName": "string",
  "gender": "string",
  "legalClass": "string",
  "birthDate": 0,
  "addresses": [{...}],
  "economics": {...},
  "contacts": [{...}],
  "professionalRegister": {...},
  "legalForm": {
     "code": "string",
     "description": "string"
   },
  "logoUrl": "string"
}

Descrizione di un indirizzo, ha la seguente forma:

{
  "streetName": "string",
  "streetNumber": "string",
  "city": "string",
  "province": "string",
  "zipCode": "string",
  "country": "string",
  "fullAddress": "string",
  "types": [
    "string"
  ],
  "id": "string"
}
Economics
{
  "rea": "string",
  "cciaa": "string",
  "capitalStock": "string",
  "liquidationState": "string",
  "registrationDate": 0,
  "taxRegime": "string",
  "soleShareholder": "string",
  "balanceSheetDate": 0,
  "economicActivities": {
    "mainActivity": {
      "code": "string",
      "rootCode": "string"
    }
  }
}
Contacts
{
  "type": "string",
  "value": "string",
  "label": "string",
  "id": "string"
}
ProfessionalRegister
{
  "description": "string",
  "province": "string",
  "code": "string",
  "registrationDate": 0
}

Status

Informazioni sullo stato dell'item quali stato d'attivazione/certificazione, data di creazione, data di ultima modifica, ecc.

{
  "active": true,
  "activatedAt": 0,
  "activatedBy": "string",
  "createdAt": 0,
  "createdBy": "string",
  "modifiedAt": 0,
  "modifiedBy": "string",
  "status": "string",
  "deleted": true,
  "deletedAt": 0,
  "deletedBy": "string",
  "ownership": "string",
  "certificationStatus": "string",
  "externallyValidated": true
}

Preferences

Preferenze globali dell'item

{
  "enableConsole": true,
  "invoiceRecipient": true,
  "language": "string",
  "hidden": true
}

Creazione di un item

Questa documentazione è riferita alla versione 3 delle API di scrittura dell'anagrafica. Le API V2 sono deprecate e non vanno utilizzate per nuove integrazioni.

L'invio di una richiesta di creazione item può essere effettuato utilizzando la seguente API:

[POST] /api/v3/item

Ogni utente personale registrato in TSDigital e le sue chiavi tecniche personali possiedono di default i permessi necessari per creare item. Una chiave tecnica applicativa non ha il permesso di creare nuovi item a meno che non sia esplicitamente richiesto.

Header

Gli header richiesti dalla chiamata sono gli header standard di TSDigital.

Il Content-Type deve essere application/json

Body

Il body della richiesta deve avere il seguente formato:

{
  "item": {
    "base": {
      "details": {
        "addresses": [
          {
            "city": "string",
            "country": "string",
            "province": "string",
            "streetName": "string",
            "streetNumber": "string",
            "types": [
              "REGISTERED_OFFICE"
            ],
            "zipCode": "string"
          }
        ],
        "birthDate": 0,
        "classifier": "INTERMEDIARY",
        "contacts": [
          {
            "label": "string",
            "type": "PHONE",
            "value": "string"
          }
        ],
        "description": "string",
        "economics": {
          "balanceSheetDate": 0,
          "capitalStock": "string",
          "cciaa": "string",
          "economicActivities": {
            "mainActivity": {
              "code": "string"
            }
          },
          "liquidationState": "LN",
          "rea": "string",
          "registrationDate": 0,
          "soleShareholder": "SM",
          "taxRegime": "string"
        },
        "firstName": "string",
        "gender": "string",
        "lastName": "string",
        "legalClass": "string",
        "legalForm": {
          "code": "string"
        },
        "professionalRegister": {
          "code": "string",
          "description": "string",
          "province": "string",
          "registrationDate": 0
        }
      },
      "identifier": {
        "govCode": "string",
        "taxId": "string",
        "taxRegion": "string",
        "vatNumber": "string"
      }
    },
    "preferences": {
      "hidden": true,
      "language": "string"
    }
  },
  "noKeys": true,
  "noOwnership": true,
  "ownerIds": [
    "string"
  ],
  "studioId": "string",
  "validated": true,
  "certified": true
}

noOwnership, validated e certified sono utilizzabili solo da chiavi tecniche applicative con ruoli speciali

Risposte

L'operazione è avvenuta con successo se e solo se il codice HTTP della risposta è 202. Ogni altro codice di risposta indica uno stato di errore.

HTTP 202

L'operazione è avvenuta con successo e il processo di creazione è stato preso in carico.

Body della risposta:

{
  "id": "string"
}
HTTP 400

Uno o più parametri forniti nella richiesta sono errati, o mancano dei parametri obbligatori.

HTTP 401

Il token autorizzativo è scaduto, invalido o non è stato specificato.

HTTP 403

Il token autorizzativo fornito è valido, ma l'utente non ha i permessi necessari a creare un item

HTTP 500

Il server ha riscontrato un errore inaspettato nell'esecuzione della richiesta di creazione item

HTTP 502

Il server ha riscontrato un errore inaspettato nel comunicare con un servizio dal quale dipende per poter completare il processo (ad esempio, il servizio di auth non risulta essere disponibile)

Tutte le risposte d'errore condividono il seguente formato per il body di risposta:

{
  "code": "string",
  "message": "string",
  "status": "string",
  "subErrors": [
    {}
  ],
  "timestamp": "dd-MM-yyyy HH:mm:ss"
}

Aggiornamento di un item

Questa documentazione è riferita alla versione 3 delle API di scrittura dell'anagrafica. Le API V2 sono deprecate e non vanno utilizzate per nuove integrazioni.

L'invio di una richiesta di aggiornamento item può essere effettuato utilizzando la seguente API, dove id è il suo identificativo univoco:

[PUT] /api/v3/items/{id}

L'operazione di aggiornamento di un item può essere effettuata:

Header

Gli header richiesti dalla chiamata sono gli header standard di TSDigital.

Il Content-Type deve essere application/json

Body

L'operazione di aggiornamento sostituisce interamente i vecchi dati dell'item con quelli specificati. Ogni campo che deve mantenere il proprio valore corrente deve essere necessariamente valorizzato con tale valore.

Il body della richiesta deve contenere base e preferences dell'item (Struttura di un Item).

{
  "base": {
    "details": {
      "addresses": [
        {
          "city": "string",
          "country": "string",
          "province": "string",
          "streetName": "string",
          "streetNumber": "string",
          "types": [
            "REGISTERED_OFFICE"
          ],
          "zipCode": "string"
        }
      ],
      "birthDate": 0,
      "classifier": "INTERMEDIARY",
      "contacts": [
        {
          "label": "string",
          "type": "PHONE",
          "value": "string"
        }
      ],
      "description": "string",
      "economics": {
        "balanceSheetDate": 0,
        "capitalStock": "string",
        "cciaa": "string",
        "economicActivities": {
          "mainActivity": {
            "code": "string"
          }
        },
        "liquidationState": "LN",
        "rea": "string",
        "registrationDate": 0,
        "soleShareholder": "SM",
        "taxRegime": "string"
      },
      "firstName": "string",
      "gender": "string",
      "lastName": "string",
      "legalClass": "string",
      "legalForm": {
        "code": "string"
      },
      "professionalRegister": {
        "code": "string",
        "description": "string",
        "province": "string",
        "registrationDate": 0
      }
    },
    "identifier": {
      "govCode": "string",
      "taxId": "string",
      "taxRegion": "string",
      "vatNumber": "string"
    }
  },
  "preferences": {
    "enableConsole": true,
    "hidden": true,
    "invoiceRecipient": true,
    "language": "string"
  }
}

Risposte

L'operazione è avvenuta con successo se e solo se il codice HTTP della risposta è 202. Ogni altro codice di risposta indica uno stato di errore.

HTTP 202

L'operazione è avvenuta con successo e il processo di aggiornamento è stato preso in carico.

Body della risposta:

{
  "id": "string"
}
HTTP 400

Uno o più parametri forniti nella richiesta sono errati, o mancano dei parametri obbligatori.

HTTP 401

Il token autorizzativo è scaduto, invalido o non è stato specificato.

HTTP 403

Il token autorizzativo fornito è valido, ma l'utente non ha i permessi necessari ad aggiornare l'item

HTTP 500

Il server ha riscontrato un errore inaspettato nella creazione della richiesta di aggiornamento item

HTTP 502

Il server ha riscontrato un errore inaspettato nel comunicare con un servizio dal quale dipende per poter completare il processo (ad esempio, il servizio di auth non risulta essere disponibile)

Tutte le risposte d'errore condividono il seguente formato per il body di risposta:

{
  "code": "string",
  "message": "string",
  "status": "string",
  "subErrors": [
    {}
  ],
  "timestamp": "dd-MM-yyyy HH:mm:ss"
}