The Active Shareholders Report ("Soci attivi") service allows obtaining, based on a single parameter (fiscal code, VAT number, or ID) of the company:

• information about the company such as Chamber of Commerce (CCIAA), REA, legal nature, ATECO code, activity status, registered office, share capital
• information about individual partners such as name, fiscal code, place and date of birth, residence, shares

On Openapi, you can request these Reports through 2 different APIs:

1) Visure Camerali
2) Visengine

REQUEST ACTIVE SHAREHOLDERS REPORT WITH VISURE CAMERALI API

The advantage of using the Visure Camerali API is that it allows direct requests. No additional requests are needed to obtain hashes or parameters.

1) Request report POST /soci-attivi

With a single request, for example, to the endpoint POST /soci-attivi, it will be possible to complete the report request, starting from one of the following data:

• VAT of the Company
• Fiscal Code of the Company
• Company ID

EXAMPLE REQUEST POST /soci-attivi

In our case, we have chosen to pass the fiscal code in the body of the request

{
  "cf_piva_id": "12485671007",
  "callback": {
    "url": "https://www.your_url.it/callback",
    "method": "POST",
    "field": "data"
  }
}

The company ID can be obtained through the two commercial search services starting from the name (or some criteria like ATECO code and turnover) or from the VAT / fiscal code.

You can also choose to set a callback to be updated when the document is available, without having to call the GET /soci-attivi/{id} endpoint to check its status.

EXAMPLE RESPONSE POST /soci-attivi

The response returns the status, the request timestamp, any set callback URL, and the request ID that will be necessary for subsequent requests and to obtain the data.

{
  "data": {
    "cf_piva_id": "12485671007",
    "tipo": "soci-attivi",
    "stato_richiesta": "In erogazione",
    "timestamp_creation": 1703852089,
    "timestamp_last_update": 1703852236,
    "allegati": [
      "65671d1c207bbf56a50aa122.pdf"
    ],
    "callback": {
      "url": "https://www.your_url.it/callback",
      "method": "POST",
      "field": "data",
      "data": {}
    },
    "owner": "[email protected]",
    "id": "658eb839e5a329399f6bffb2"
  },
  "success": true,
  "message": "",
  "error":  
}

2) Check the status of the request GET /soci-attivi/{id}

It is possible to check the status of an Active shareholders request using the endpoint GET /soci-attivi/{id}. As indicated earlier, we suggest setting the callback during the request to be updated when the document is available and can be downloaded.

EXAMPLE REQUEST GET /soci-attivi/{id}

The ID is the one obtained and available in the response after the request to the endpoint POST /soci-attivi:

https://visurecamerali.openapi.it/soci-attivi/{id}/allegati

EXAMPLE RESPONSE GET /soci-attivi/{id}

The response includes all the data previously indicated on the company and partners with the request timestamp and last update timestamp, any callback URL.

{
  "data": {
    "cf_piva_id": "12485671007",
    "tipo": "soci-attivi",
    "stato_richiesta": "In erogazione",
    "timestamp_creation": 1703852089,
    "timestamp_last_update": 1703852236,
    "allegati": [
      "65671d1c207bbf56a50aa122.pdf"
    ],
    "callback": {
      "url": "https://www.your_url.it/callback",
      "method": "POST",
      "field": "data",
      "data": {}
    },
    "owner": "[email protected]",
    "id": "658eb839e5a329399f6bffb2"
  }
}


3) Download Active Shareholders Report GET /soci-attivi/{id}/allegati

It is also possible to obtain all the data in XML, JSON and PDF formats through the endpoint GET /soci-attivi/{id}/allegati

EXAMPLE REQUEST GET /soci-attivi/{id}/allegati

The request must be made with the ID obtained in the response of the endpoint POST /soci-attivi.

https://visurecamerali.openapi.it/soci-attivi/5f2829ce065afc21cc60ad0e/attachments/

EXAMPLE RESPONSE GET /soci-attivi/{id}/allegati

The response will indicate the filename, size, and file content.

{ "data": 
    {
    "name": "6564a673ccfa313352066377.zip",
    "size": 1728,
    "file": "UEsDBBQAAAAlNnVTBs6lJ1vIIAJthCQAcABwANjI2OTFjNGY5N2UwOTQ0NzU0MDI3ADU/HOUbc+WLQqnnTtt27Zt27Zt25k7bdu2bdvcadv5fnXOqapz655qt9p93x/vW62tFjHnGmv2HiMiZvQxY7RJIi8sSsNAywxFcnA4uwjFgE+Pb2doCcXNTSdqYe1s4kgnam3gbCJsYmRnbEInbWJr5"
      }

REQUEST ACTIVE SHAREHOLDERS REPORT WITH VISENGINE API

1) Request Report Hash (GET /richiesta)

To request reports with Visengine, you first need to identify the hash that uniquely identifies each document.

https://visengine2.altravia.com/visure/

This can be done through the GET /visure endpoint, which does not require parameters and will return the complete list of documents and records that can be requested through Visengine along with their hashes.

2) Check Report Request Data and Costs (GET /richiesta/{hash_visure})

If you want to verify information, required documents, and costs of the report, you need to make a request through the GET /visure/{hash_visure} endpoint and pass the hash of the report previously obtained.

EXAMPLE REQUEST GET /reports/{hash_visure}

To check fields and costs to complete the request successfully, use the hash obtained in the previous request.

https://visengine2.altravia.com/visure/fab482bf67a418f00d596b7296750a9a

EXAMPLE RESPONSE GET /visure/{hash_visure}

The response will contain all the necessary information to complete the request, such as mandatory fields.

{
  "data": {
    "nome_visura": "Soci Attivi Azienda",
    "ricerca": false,
    "nome_categoria": "Camerali",
    "json_struttura": {
      "campi": {
        "$0": {
          "nome": "Codice Fiscale",
          "tipo": "codice_fiscale",
          "null": false,
          "istruzioni": "Inserire il Codice Fiscale dell`Azienda",
          "ordine": "1"
        }
      },
      "validazione": "$0  ",
      "istruzioni": "",
      "istruzioni_ricerca": ""
    },
    "hash_visura": "70a1b5d29d8efaae6ef9616841fd6f72",
    "prezzo_visura": 2.1,
    "prezzo_ricerca": 0,
    "sincrona": false,
    "opzioni": null,
    "fornitori": []
  },
  "success": true,
  "message": "",
  "error": null
}

In the validation, mandatory data for successful request completion will be indicated.

3) Request Report POST /richiesta

To make a report request, the subject's tax code is passed.

EXAMPLE REQUEST POST /richiesta

{
    "hash_report": "70a1b5d29d8efaae6ef9616841fd6f72",
    "json_report": {
      "$1": 12485671007
      }
  }

EXAMPLE RESPONSE POST /richiesta

The response provides various information, including the status, callback (if set), and the ID of the request, which will be needed later to download the document.

{ "data": 
    {
      "_id": "5f2829ce065afc21cc60ad0e",
    "state": 1,
    "hash_report": "70a1b5d29d8efaae6ef9616841fd6f72",
    "name": "Soci Attivi",
    "search": false,
    "search_id": null,
    "price_report": 2.3,
    "price_search": 0,
    "search_index": null,
    "request_status": "In progress",
    "email_target": null,
    "attachments": [],
    "timestamp_creation": 1596467662,
    "timestamp_last_update": 1596467663,
    "timestamp_statuses": {
      "in_search": 1596467663,
      "in_progress": 1596467663
    },
    "callback_data": false,
    "options": null,
    "owner": "[email protected]",
    "synchronous": false,
    "searches": [
      {
        "search_id": "5f2829ce065afc21cc60ad0e_0",
        "search_status": "Search completed",
        "json_search": "{\"$1\":\"12485671007\"}",
        "json_mapped": {
          "TaxNumber": "1378273",
          "ChamberOfCommerce": "RM"
        },
        "json_result": null
      }
    ],
    "result": {
      "code": "0",
      "info": "OK"
    }

4) Download Report GET /documento/{id}

Once the request status is "evasa" ("completed"), it will be possible to download the data in JSON, PDF, and XML formats using the GET method on /documento/{_id}.

EXAMPLE REQUEST GET /documento/{id}

This is an example request made using the ID previously obtained

https://visengine2.altravia.com/visure/documento/5f2829ce065afc21cc60ad0e

EXAMPLE RESPONSE GET /documento/{id}

The response will contain the name, size, and the file.

{
  data{
    "name":"5f22f5b5065afc21cc60a27a.zip",
    "size"10206",
    "file":"++6+47433njVP9ZcX1XNtWUsKrTya9FGhwiXgdp5j5OPh0FpaKWVpjP8CUEjFjYzYwYTI3YS5wZGZVVAUAAwhDKF91eAsAAQQhAAAABCEAAABQSwUGAAAAAAEAAQBiAAAAZicAAAAA"
    },
    "success": true,
    "message": "",
    "error": null
  }

All formats (JSON, PDF, XML) will be available inside a zip file.