Anagrafica
- API
- Creazione ed aggiornamento item
- Lettura degli Item
- Lettura di un singolo item
- Lettura di una lista di items
- Lettura di una lista di items di un utente
- Ricerca items
- Verifica esistenza item
- Gestione del logo aziendale
API
Endpoint di lettura
API Base Url:
dev: https://registry-read-dev.agyo.io/api
test: https://registry-read-test.agyo.io/api
prod: https://registry-read.agyo.io/api
Swagger:
https://registry-read-test.agyo.io/swagger-ui/index.html
FindItem
https://registry-read-test.agyo.io/swagger-ui.html#/API/findItemsUsingGET
Impostando
- identifier.taxId o identifier.vatNumber
- identifier.taxRegion
- packageType: BASE
È possibile cercare per CF o PIVA
Esempio ricerca per partiva iva:
Esempio ricerca per codice fiscale:
Regole di salvataggio / cache
Una volta recuperato l’id per una determinata azienda sarà possibile salvarlo localmente solo in caso sia un UUIDv4 perchè non verrà più modificato a differenza dell’attuale codice fiscale che può subire variazioni dovuti ad eventi di rettifica.
Inizialmente la situazione sarà mista per questioni di migrazione.
In caso l’identificativo sia uguale al CF il comportamento consigliato è quello di avere una cache di alcune ore (consigliate 24/48) per evitare carico inutile verso le API di anagrafica, ma di continuare a chiederlo ogni volta che scade la cache.
Se l’identificativo risulta invece essere un UUIDv4 (o comunque lunghezza > 20 quindi oltre il formato CF italiano (16) + i caratteri “-XXX” dell’ufficio (4)) è possibile salvarlo consapevoli del fatto che non cambierà più.
Endpoint di scrittura
API Base Url:
dev: https://registry-write-dev.agyo.io/api
test: https://registry-write-test.agyo.io/api
prod: https://registry-write.agyo.io/api
Swagger:
https://registry-write-test.agyo.io/swagger-ui.html
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:
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:
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
Lettura degli Item
Descrizione delle API messe a disposizione per consultare gli item presenti nell'anagrafica TSDigital.
Lettura di un singolo item
Dato l'identificativo di un item è possibile recuperarne tutte le informazioni invocando la seguente API:
Questa documentazione è riferita alla versione 3 delle API di lettura dell'anagrafica. Le API V2 sono deprecate e non vanno utilizzate per nuove integrazioni.
Header
Gli header richiesti dalla chiamata sono gli header standard di TSDigital.
Il Content-Type deve essere application/json
Query Parameters
- packageType: livello di dettaglio richiesto sull'item. Accetta due valori: BASE e FULL. Nella maggioranza dei casi è sufficiente e consigliato utilizzare BASE.
Risposte
L'operazione è avvenuta con successo se e solo se il codice HTTP della risposta è 200. Ogni altro codice di risposta indica uno stato di errore.
HTTP 200
L'item esiste e l'utente ha i permessi necessari a leggerne le informazioni.
Body della risposta:
{
"item": {
"base": {
"id": "string",
"identifier": {
"taxId": "string",
"taxRegion": "string",
"vatNumber": "string",
"govCode": "string"
},
"details": {
"classifier": "string",
"description": "string",
"firstName": "string",
"lastName": "string",
"gender": "string",
"legalClass": "string",
"birthDate": 0,
"addresses": [
{
"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
},
"legalForm": {
"code": "string",
"description": "string"
}
},
"status": {
"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
},
"hierarchyId": "string",
"parentId": "string",
"holdingId": "string",
"ncsId": "string"
},
"preferences": {
"enableConsole": true,
"invoiceRecipient": true,
"language": "string",
"hidden": true
},
"layers": [...],
"group": {
"businessGroups": [
{
"name": "string",
"foundedAt": 0,
"id": "string"
}
],
"holding": {...},
"companies": [{...}],
"companiesSize": 0,
"companiesIterator": {},
"businessGroupsSize": 0,
"businessGroupsIterator": {}
},
"layersSize": 0,
"layersIterator": {}
}
}
Per maggiori informazioni sui singoli campi, vedi Struttura di un 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 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
Lettura di una lista di items
Data una lista di identificativi di items è possibile recuperarne tutte le informazioni a loro relative invocando la seguente API:
Questa documentazione è riferita alla versione 3 delle API di lettura dell'anagrafica. Le API V2 sono deprecate e non vanno utilizzate per nuove integrazioni.
Header
Gli header richiesti dalla chiamata sono gli header standard di TSDigital.
Il Content-Type deve essere application/json
Query Parameters
- idList: lista di identificativi di items.
- packageType: livello di dettaglio richiesto sull'item. Accetta due valori: BASE e FULL. Nella maggioranza dei casi è sufficiente e consigliato utilizzare BASE.
- pagination.itemsPerPage: numero di items restituiti per pagina.
- pagination.pageNumber: numero della pagina del risultato.
- pagination.Unpaged: di default è false, questo parametro permette di visualizzare il risultato senza paginazione.
Risposte
L'operazione è avvenuta con successo se e solo se il codice HTTP della risposta è 200. Ogni altro codice di risposta indica uno stato di errore.
HTTP 200
L'item esiste e l'utente ha i permessi necessari a leggerne le informazioni.
Body della risposta:
{
"items": [
{
"item": {
"base": {
"id": "string",
"identifier": {
"taxId": "string",
"taxRegion": "string",
"vatNumber": "string",
"govCode": "string"
},
"details": {
"classifier": "string",
"description": "string",
"firstName": "string",
"lastName": "string",
"gender": "string",
"legalClass": "string",
"birthDate": 0,
"addresses": [
{
"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
},
"legalForm": {
"code": "string",
"description": "string"
}
},
"status": {
"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
},
"hierarchyId": "string",
"parentId": "string",
"holdingId": "string",
"ncsId": "string"
},
"preferences": {
"enableConsole": true,
"invoiceRecipient": true,
"language": "string",
"hidden": true
},
"layers": [...],
"group": {
"businessGroups": [
{
"name": "string",
"foundedAt": 0,
"id": "string"
}
],
"holding": {...},
"companies": [{...}],
"companiesSize": 0,
"companiesIterator": {},
"businessGroupsSize": 0,
"businessGroupsIterator": {}
},
"layersSize": 0,
"layersIterator": {}
}
]
}
Per maggiori informazioni sui singoli campi, vedi Struttura di un 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 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
Lettura di una lista di items di un utente
Dato un identificativo utente è possibile recuperarne tutte le informazioni relative ai suoi items invocando la seguente API:
Questa documentazione è riferita alla versione 3 delle API di lettura dell'anagrafica. Le API V2 sono deprecate e non vanno utilizzate per nuove integrazioni.
Header
Gli header richiesti dalla chiamata sono gli header standard di TSDigital.
Il Content-Type deve essere application/json
Query Parameters
- userId: identificativo utente.
- fullText: testo libero.
- packageType: livello di dettaglio richiesto sull'item. Accetta due valori: BASE e FULL. Nella maggioranza dei casi è sufficiente e consigliato utilizzare BASE.
- pagination.itemsPerPage: numero di items restituiti per pagina.
- pagination.pageNumber: numero della pagina del risultato.
- pagination.Unpaged: di default è false, questo parametro permette di visualizzare il risultato senza paginazione.
Risposte
L'operazione è avvenuta con successo se e solo se il codice HTTP della risposta è 200. Ogni altro codice di risposta indica uno stato di errore.
HTTP 200
L'item esiste e l'utente ha i permessi necessari a leggerne le informazioni.
Body della risposta:
{
"items": [
{
"item": {
"base": {
"id": "string",
"identifier": {
"taxId": "string",
"taxRegion": "string",
"vatNumber": "string",
"govCode": "string"
},
"details": {
"classifier": "string",
"description": "string",
"firstName": "string",
"lastName": "string",
"gender": "string",
"legalClass": "string",
"birthDate": 0,
"addresses": [
{
"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
},
"legalForm": {
"code": "string",
"description": "string"
}
},
"status": {
"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
},
"hierarchyId": "string",
"parentId": "string",
"holdingId": "string",
"ncsId": "string"
},
"preferences": {
"enableConsole": true,
"invoiceRecipient": true,
"language": "string",
"hidden": true
},
"layers": [...],
"group": {
"businessGroups": [
{
"name": "string",
"foundedAt": 0,
"id": "string"
}
],
"holding": {...},
"companies": [{...}],
"companiesSize": 0,
"companiesIterator": {},
"businessGroupsSize": 0,
"businessGroupsIterator": {}
},
"layersSize": 0,
"layersIterator": {}
}
]
}
Per maggiori informazioni sui singoli campi, vedi Struttura di un 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 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
Ricerca items
Dato un taxId, vatNumber o un testo libero è possibile recuperarne tutte le informazioni relative agli items con queste caratteristiche invocando la seguente API:
Questa documentazione è riferita alla versione 3 delle API di lettura dell'anagrafica. Le API V2 sono deprecate e non vanno utilizzate per nuove integrazioni.
Header
Gli header richiesti dalla chiamata sono gli header standard di TSDigital.
Il Content-Type deve essere application/json
Query Parameters
- identifier.taxId: taxId(codice fiscale) dell'item.
- identifier.varNumber: vatNumber(partita iva) dell'item.
- identifier.taxRegion: taxRegion dell'item.
- fullText: testo libero.
- packageType: livello di dettaglio richiesto sull'item. Accetta due valori: BASE e FULL. Nella maggioranza dei casi è sufficiente e consigliato utilizzare BASE.
- pagination.itemsPerPage: numero di items restituiti per pagina.
- pagination.pageNumber: numero della pagina del risultato.
- pagination.Unpaged: di default è false, questo parametro permette di visualizzare il risultato senza paginazione.
Risposte
L'operazione è avvenuta con successo se e solo se il codice HTTP della risposta è 200. Ogni altro codice di risposta indica uno stato di errore.
HTTP 200
L'item esiste e l'utente ha i permessi necessari a leggerne le informazioni.
Body della risposta:
{
"items": [
{
"item": {
"base": {
"id": "string",
"identifier": {
"taxId": "string",
"taxRegion": "string",
"vatNumber": "string",
"govCode": "string"
},
"details": {
"classifier": "string",
"description": "string",
"firstName": "string",
"lastName": "string",
"gender": "string",
"legalClass": "string",
"birthDate": 0,
"addresses": [
{
"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
},
"legalForm": {
"code": "string",
"description": "string"
}
},
"status": {
"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
},
"hierarchyId": "string",
"parentId": "string",
"holdingId": "string",
"ncsId": "string"
},
"preferences": {
"enableConsole": true,
"invoiceRecipient": true,
"language": "string",
"hidden": true
},
"layers": [...],
"group": {
"businessGroups": [
{
"name": "string",
"foundedAt": 0,
"id": "string"
}
],
"holding": {...},
"companies": [{...}],
"companiesSize": 0,
"companiesIterator": {},
"businessGroupsSize": 0,
"businessGroupsIterator": {}
},
"layersSize": 0,
"layersIterator": {}
}
]
}
Per maggiori informazioni sui singoli campi, vedi Struttura di un 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 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
Verifica esistenza item
Dato un taxId, vatNumber è un taxRegion è possibile verificare l'esistenza di un item con queste caratteristiche invocando la seguente API:
Questa documentazione è riferita alla versione 3 delle API di lettura dell'anagrafica. Le API V2 sono deprecate e non vanno utilizzate per nuove integrazioni.
Header
Gli header richiesti dalla chiamata sono gli header standard di TSDigital.
Il Content-Type deve essere application/json
Query Parameters
- identifier.taxId: taxId(codice fiscale) dell'item.
- identifier.varNumber: vatNumber(partita iva) dell'item.
- identifier.taxRegion: taxRegion dell'item.
Risposte
L'operazione è avvenuta con successo se e solo se il codice HTTP della risposta è 200. Ogni altro codice di risposta indica uno stato di errore.
HTTP 200
L'item esiste.
Body della risposta:
{}
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 404
L'item non è stato trovato
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
Gestione del logo aziendale
Api di lettura e cancellazione del logo aziendale
Lettura del logo aziendale
Per recuperare le informazioni relative al logo aziendale sarà sufficiente recuperare le informazioni dell'azienda desiderata tramite le api di lettura anagrafica:
ref: https://digital-docs.ts-paas.com/books/anagrafica/page/endpoint-di-lettura
API Base Url:
dev: https://registry-read-dev.agyo.io/api
test: https://registry-read-test.agyo.io/api
prod: https://registry-read.agyo.io/api
Swagger:
https://registry-read-test.agyo.io/swagger-ui.html
Le informazioni relative al logo si troveranno dei "details", ref: https://digital-docs.ts-paas.com/books/anagrafica/page/struttura-di-un-item
{
"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"
}- logoUrl: url relativo allo storage di riferimento all'ambiente al quale stiamo chiamando, dal quale recuperare il logo aziendale
Scrittura del logo aziendale
Gli endpoint di scrittura e cancellazione per il logo aziendale si trovano nella "write" dell'anagrafica:
ref: https://digital-docs.ts-paas.com/books/anagrafica/page/endpoint-di-scrittura
API Base Url:
dev: https://registry-write-dev.agyo.io/api
test: https://registry-write-test.agyo.io/api
prod: https://registry-write.agyo.io/api
Swagger:
https://registry-write-test.agyo.io/swagger-ui.html
In particolare:
Per il CARICAMENTO del logo, è neccesario chiamare la POST:
Essendo una API V3, nel path andrà inserito l'UUID dell'azienda per la quale caricare il logo.
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:
{
"base64": "string"
}- Il logo può essere di qualsiasi estensione purchè sia di tipo immagine.
- La dimensione del logo dovrà essere inferiore a 1MB.
- Nel caso in cui l'azienda abbia già caricato un logo, andando ad eseguire un nuovo caricamento, quello vecchio verrà sovrascritto.
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.
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
Per la CANCELLAZIONE del logo, è neccesario chiamare la DELETE:
In questo caso basterà indicare l'UUID dell'azienda nel path per procedere alla cancellazione del logo.
Header
Gli header richiesti dalla chiamata sono gli header standard di TSDigital.
Il Content-Type deve essere application/json
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.
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