Skip to main content

Ricerca items

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

Dato un taxId, vatNumber o un testo libero è possibile recuperarne tutte le informazioni relative agli items con queste caratteristiche  invocando la seguente API:

[GET] /api/v3/items

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
  •  
Back to top