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" } id: identificativo univoco dell'item all'interno dell'anagrafica (es: 44672d4c-4dea-4cf9-af6d-1c3a01cb742e) identifier: insieme di informazioni che identificano univocamente l'item. Vedi Identifier per maggiori dettagli. details: dettagli anagrafici dell'item. Vedi Details per maggiori dettagli. status: stato d'attivazione e metadati legati all'item. Vedi Status per maggiori dettagli. ncsId: identificativo univoco dell'item all'interno del Notification Center. hierarchyId: proprietà deprecata parentId: proprietà deprecata holdingId: proprietà deprecata 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" } govCode: identificativo univoco di un ufficio all'interno della Pubblica Amministrazione. Utilizzato per poter registrare come item separati entità governative che hanno la stessa coppia taxId/vatNumber. taxId: codice fiscale dell'item vatNumber: partita IVA dell'item taxRegion: identificativo della nazione alla quale appartiene l'item (es: IT) 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" } classifier: identificativo della tipologia di item, può assumere i seguenti valori: COMPANY: azienda generica STUDIO: azienda che effettua operazioni per altre aziende (es: studio commercialista) PERSON: persona fisica BUILDING: condominio description: nome/ragione sociale (es: Mondora srl sb) firstName: nome proprio (solo per classifier PERSON) lastName: cognome (solo per classifier PERSON) gender: sesso (solo per classifier PERSON). Valori possibili: M, F legalClass: ??? birthDate: data di nascita (solo per classifier PERSON) addresses: array di indirizzi. Vedi Address per maggiori dettagli sul singolo indirizzo economics: dati economici dell'item. Vedi Economics per maggiori dettagli contacts: contatti relativi all'item (es: numero di telefono). Vedi Contacts per maggiori dettagli professionalRegister: informazioni sulla registrazione dell'item al proprio albo di riferimento. Vedi ProfessionalRegister per maggiori dettagli legalForm: forma legale dell'azienda, suddivisa in code: codice di due lettere identificativo della forma legale (es: AA) description: descrizione della forma legale (es: Società in accomandita per azioni) logoUrl: url dal quale recuperare il logo aziendale 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" } streetName: nome della via streetNumber: numero civico city: nome della città province: nome della provincia zipCode: CAP country: nome della nazione fullAddress:    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 } active: indica se l'item è attivo su Digital activatedAt: timestamp in millisecondi dell'attivazione dell'item activatedBy: identificativo dell'utenza che ha effettuato l'attivazione dell'item createdAt: timestamp in millisecondi della creazione dell'item createdBy: identificativo dell'utenza che ha creato l'item modifiedAt: timestamp in millisecondi dell'ultima modifica effettuata sull'item modifiedBy: identificativo dell'utenza che ha effettuato l'ultima modifica sull'item status: status di validazione corrente dell'item. Può assumere uno dei seguenti valori: UNVERIFIABLE: l'azienda non ha mai caricato il contratto di TSDigital UNVERIFIABLE_PENDING_VALIDATE: l'utente ha caricato il contratto TSDigital ed è in attesa di risposta REJECTED: il contratto di TSDigital caricato dall'utente è invalido e ne deve quindi caricare uno corretto REJECTED_PENDING_VALIDATE: l'utente ha ricaricato il contratto dopo il rifiuto ed è in attesa di risposta VALIDATED: il contratto caricato è stato convalidato certificationStatus: status di certificazione corrente dell'item. Può assumere uno dei seguenti valori  null: l'azienda non ha ancora caricato il contratto TSDigital AWAITING_UPLOAD: l'utente deve ricaricare il contratto TSDigital AWAITING_APPROVAL: l'utente ha caricato il contratto TSDigital ed è in attesa di risposta CERTIFIED: il contratto è stato certificato deleted: indica se l'item è stato eliminato da Digital deletedAt: timestamp in millisecondi della cancellazione dell'item deletedBy: identificativo dell'utenza che ha eliminato l'item ownership: externallyValidated: indica se l'item è considerato essere valido anche in assenza di un contratto TSDigital in quanto validato da un'entità esterna Preferences Preferenze globali dell'item { "enableConsole": true, "invoiceRecipient": true, "language": "string", "hidden": true } enableConsole: deprecata invoiceRecipient: deprecata language: deprecata hidden: indica se l'azienda non può essere trovata tramite API di ricerca globali all'interno di digital. I suoi dati possono essere letti solo da utenti che hanno almeno un permesso sull'item stesso. 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 } item: contiene tutti i dati anagrafici e le preferenze dell'azienda. Per dettagli sui singoli campi, vedi Struttura di un item. noKeys: se true, non verrà automaticamente generata una chiave tecnica con accesso all'azienda. Nella maggioranza dei casi, è preferibile non far creare la chiave tecnica noOwnership: se true, l'utente che sta effettuando la creazione dell'azienda non verrà indicato come utente owner della stessa e non riceverà alcun ruolo su di essa ownerIds: elenco di utenti da impostare come owner per l'azienda. Non può essere combinato con  noOwnership=true. Questo campo è utilizzabile solo da backoffice. studioId: identificativo univoco dello studio per il conto del quale sta venendo creata l'azienda. Questo parametro è utilizzato per la creazione delle aziende gestite contestualmente ad una connessione. Non è possibile creare un item per conto di uno studio per il quale non si hanno permessi di scrittura validated: se true, l'item viene creato in stato VALIDATED certified: se true, l'item viene creato in stato CERTIFIED. È necessario specificare anche  validated=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" } id: identificativo dell'item creato 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" } code: corrisponde al codice d'errore HTTP ritornato (es:  500) message: messaggio d'errore (es:  Errore interno del server) status: descrizione a parole del codice d'errore HTTP (es:  Internal Server Error) subErrors: eventuali errori innestati in quello ritornato timestamp: data ed ora di ritorno dell'errore   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: dai soli utenti con ruolo WRITE globale sull'item se l'item ha almeno un utente amministratore da ogni utente con almeno ruolo WRITE su un'applicazione dell'item se non esiste nessun utente amministratore 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" } id: identificativo dell'item 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" } code: corrisponde al codice d'errore HTTP ritornato (es:  500) message: messaggio d'errore (es:  Errore interno del server) status: descrizione a parole del codice d'errore HTTP (es:  Internal Server Error) subErrors: eventuali errori innestati in quello ritornato timestamp: data ed ora di ritorno dell'errore