michele/netgescon-day0
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
9d8e412c49
netgescon-day0/directives/SISTER_MANUALE_SORGENTE.txt

549 lines
51 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

😄 Quick start:
- per conoscere gli immobili di una persona (output JSON): metodo consigliato mashImmobili.php
- per conoscere gli intestati di un immobile (output JSON): metodo mashIntestati.php
- per acquistare una visura ufficiale di un immobile (pdf o xml firmati digitalmente da Agenzia delle Entrate): metodo mashVisureI.php
Nota: Ad ogni chiamata va aggiunto il parametro passwordScript=demo, corrispondente alla vostra chiave di test valida per 15 gg, o la chiave di licenza che vi è stata comunicata.
Nota: se si passano le proprie credenziali (parametri “u” e “p”), queste vanno specificate in tutte le chiamate.
Ricerca immobili di Codice Fiscale
⭐ (metodo consigliato)
NB: per effettuare la ricerca inversa (conoscere gli intestati di un immobile, vedere il metodo consigliato a pag. 5)
Ricerca per Persona Fisica
Esempio:
https://thenetworksolution.it/sister/mashImmobili.php?cf=RSSBNM48B14D969T&tipoCatasto=E&uffprovinciale=GENOVA%20Territorio-GE
La risposta è contenuta in un array di oggetti in formato JSON, così fatto:
{
"soggetti": [
{
"cognome": "ROSSI",
"nome": "BRUNO MARIO",
"datanascita": "14/02/1948",
"luogonascita": "GENOVA (GE)",
"sesso": "M",
"cf": "RSSBNM48B14D969T",
"immobili": {
"catasto": "F",
"titolarita": "Proprieta' per 1/1",
"ubicazione": "GENOVA (GE) Sez.Q VIA MARSILIO DA PADOVA, 6R Piano S1 int. 17",
"foglio": "GEB/72",
"particella": "580",
"subalterno": "28",
"classamento": "zona1 cat. C/6",
"classe": "6",
"consistenza": "26 mq",
"rendita": "Euro:187,99 "
}
}
],
}
Nota: tutti i metodi accettano i parametri sia in GET che POST. Negli esempi seguenti i parametri sono indicati in GET. Dovrebbero essere sempre passati in POST almeno i parametri contenenti credenziali o dati personali. E’ inoltre necessario gestire i cookie eventualmente restituiti dalle chiamate.
Il parametro tipoCatasto indica in quale catasto effettuare la ricerca e assume uno dei seguenti valori: T = Terreni, F = Fabbricati, E = entrambi.
Il parametro uffprovinciale indica la provincia in cui effettuare la ricerca e deve essere valorizzato esattamente con una delle seguenti stringhe:
NAZIONALE
AGRIGENTO Territorio
ALESSANDRIA Territorio
ANCONA Territorio
...segue...
L'elenco completo degli uffici provinciali è disponibile con il metodo ausiliario https://thenetworksolution.it/sister/uffprovinciali.php. La ricerca può essere effettuata per provincia. Per cercare gli immobili su tutto il territorio nazionale, è necessario effettuare più ricerche. Vedere più sotto il metodo di utilità ricercaNazionale.php&idSoggetto= che permette di sapere in quali province un soggetto possiede immobili (vedere paragrafo Ricerca Nazionale)
I 5 campi [catasto, comune, sezione*, foglio, particella, subalterno] costituiscono l'identificativo univoco dell'immobile, necessario per l'utilizzo dei metodi successivi (vedi Ricerca Intestati di Immobile per visualizzare eventuali altri intestatari dell'immobile).
NB: Il subalterno è assente per i terreni.
* Alcuni comuni non sono divisi in sezioni in tali casi il campo non è ritornato ne richiesto.
Ricerca per Persona Giuridica
Per effettuare la ricerca tramite il Codice Fiscale di una Persona Giuridica, sostituire il parametro ?cf= con ?pg= cosi:
https://thenetworksolution.it/sister/mashImmobili.php?pg=00349850099&tipoCatasto=E&uffprovinciale=SAVONA%20Territorio-GE
Se non si conoscono i dati del soggetto da cercare, o si vuole solo verificare la presenza di immobili intestati (senza bisogno di vederne i relativi dati), è possibile utilizzare i seguenti metodi da pag. 4 in poi, denominati ricerca* più efficienti (il presente metodo mash* ne è solo la concatenazione in sequenza).
Per conoscere eventuali cointestati degli immobili restituiti, effettuare una ricerca per immobile con i metodi ultimaVariazione.php o mashIntestati.php
Ricerca Intestati di Immobile
⭐ (metodo consigliato)
Esempio:
https://thenetworksolution.it/sister/mashIntestati.php?tipoCatasto=F&uffprovinciale=GENOVA%20Territorio-GE&denomComune=D969%23GENOVA%2310%233&sezione=Q&sezUrb=GEB&foglio=72&particella=520&subalterno=15
Se è necessario specificare due particelle (in uso solo nelle province di Trieste, Gorizia, Trento, Bolzano e in alcuni Comuni delle Province di Udine, Vicenza, Brescia e Belluno, dove è in uso il catasto tavolare), utilizzare i parametri &particella1= e &particella2= in luogo di &particella=.
Il valore del parametro denomComune, composto, tra l'altro, dall'identificativo catastale del comune e dal numero di sezioni presenti, rispettivamente per i catasti terreni e fabbricati, deve essere recuperato tramite il seguente metodo ausiliario:
https://thenetworksolution.it/sister/comuni.php?uffprovinciale=GENOVA%20Territorio-GE
Se non si conosce la sezione (da non confondere con la sezione urbana, campo sezUrb, sempre facoltativa), è possibile recuperare la lista delle sezioni di un comune (sono sempre poche o nessuna) con il seguente metodo ausiliario:
https://thenetworksolution.it/sister/sezioni.php?tipoCatasto=F&uffprovinciale=GENOVA%20Territorio-GE&denomComune=D969%23GENOVA%2310%233
dove denomComune si recupera anche questa volta con il metodo precedente.
Se si conosce la sezione urbana (campo facoltativo, raramente presente negli input) dell’immobile, è possibile (consigliato) utilizzare il seguente metodo alternativo a mashIntestati.php, più performante e per tale motivo da preferire per l’uso in batch o in contesti multiutente per ottenere gli intestati di immobili:
https://thenetworksolution.it/Territorio/ultimaVariazione.php?comuneCatastale=L024&sezioneAmministrativa=&sezioneUrbana=&foglio=16&particella=336&subalterno=2 (solo se non si intende acquistare visura)
Tale metodo ritorna anche la data e gli estremi dell’atto con cui l’intestato ha acquisito il diritto (proprietà, etc..) sull’immobile. Se si desidera conoscere tale dato ma non si conosce della sezione amministrativa, si può effettuare una ricerca con il metodo seguente, ricercaImmobile.php, per scoprire la sezione amministrativa e ripetere la ricerca con ultimaVariazione.php
Visura catastale di immobile (documenti ufficiali Agenzia delle Entrate)
⭐ (metodo consigliato)
Esempio:
https://thenetworksolution.it/sister/mashVisuraI.php?uffprovinciale=MILANO%20Territorio-MI&tipoCatasto=F&denomComune=F797%23MUGGIO%27%230%230&sezione=&sezUrb=&foglio=1&particella=3&subalterno=701&formato=XML
che restituisce in output:
{"url":"acquistate\/220293354#141863#F#GEB-72#520#D969#20720#15#Q#GENOVA.pdf"}
L'output dei metodi acquista* è un JSON, pertanto l'URL è encodato secondo le regole di tale formato (pes es. la slash). Per poter navigare l'URL (una volta json decoded) ne va fatto l'URL encode per i path. Il path restituito è un URL e deve essere appeso all’URL dello script, quindi nell’esempio sopra per scaricare la visura bisognerà navigare a https://thenetworksolution.it/sister/acquistate/678278784%234045%23F%23BI-2%232582%23L682%23%234%23%23VARESE_completa.pdf
L'acquisto viene effettuato tramite il proprio account specificato tramite i parametri &u e &p, che deve avere credito sufficiente. Il campo formato può assumere valori "PDF" e "XML" (maiuscolo).
E’ possibile acquistare anche le visure storiche aggiungendo il parametro tipoVisura che può assumere valori: completa (default), analitica, storica.
Le visure vengono salvate sul server nella cartella "acquistate". Se si richiede una visura già acquistata, nello stesso formato (PDF/XML), tramite questo metodo nelle ultime 24 ore, viene restituita la copia memorizzata sul server (in tal caso l'output riporta anche data e ora - fuso orario italiano - dell'acquisto nel campo cache). E' possibile modificare il comportamento descritto aggiungendo alla chiamata il parametro &cache=0 o il diverso numero di ore desiderato. Ciò è necessario anche qualora si desideri acquistare una visura storica entro 24 ore dall’acquisto di una visura completa e viceversa.
{"url":"acquistate\/220293354#141863#F#GEB-72#520#D969#20720#15#Q#GENOVA.pdf","cache":"2021-04-23T09:28:37+02:00"}
Sono disponibili analoghi metodi per l’acquisto delle visure per soggetto, note catastali, elenchi catastali di immobili, ispezioni ipotecarie.
Aggiungendo il parametro &download il servizio effettua redirect al file del documento acquistato se l’acquisto è andato a buon fine (altrimenti si riceve output JSON come sopra). Nel raro caso di omoimmobili, saranno presenti più file, restituiti come archivio ZIP.
In alcuni casi Sister non restituisce immediatamente il documento richiesto, in tal caso i metodi di acquisto restituiscono in output l’idRichiesta:
{idRichiesta: 1555611493}
da utilizzare per il recupero successivo del documento tramite il metodo elencoRichieste.php:
https://thenetworksolution.it/sister/elencoRichieste.php
{
"richieste":[
{
"data":"16\/09\/2022\u00a008:01:10",
"oggetto":"VISURA FG. 10 PART. 79 SUB. 5 DI CASTROLIBERO",
"formato":"PDF",
"importo":0.9,
"id":1555611493
},
…
}
Vengono visualizzati i documenti prodotti oggi e non ancora scaricati. Tramite i parametri opzionali &data=gg/mm/aaaa e &tipo= che può assumere valori: espletate, nonEspletabili, inEvasione, prelevate, è possibile cercare per una data specifica o i documenti già scaricati, in produzione o in errore:
https://thenetworksolution.it/sister/elencoRichieste.php?data=14/09/2022&tipo=prelevate
Il download di un documento può essere eseguito aggiungendo il parametro &download=___ valorizzato con l’idRichiesta desiderata:
https://thenetworksolution.it/sister/elencoRichieste.php?download=1555611493
oppure
https://thenetworksolution.it/sister/elencoRichieste.php?data=14/09/2022&tipo=prelevate&download=1555611493
I documenti già scaricati, possono essere prelevati nuovamente per una settimana senza costi aggiuntivi.
Ricerca di Persona Fisica proprietaria di immobili
Ricerca per cognome
Esempio:
https://thenetworksolution.it/sister/ricercaPersonaFisica.php?tiporicerca=cognome&tipoCatasto=E&nome=mario&cognome=rossi&datanascita=14/02/1948&uffprovinciale=GENOVA%20Territorio-GE
datanascita è opzionale, se presente deve avere il formato gg/mm/aaaa.
La risposta è contenuta in un array di oggetti in formato JSON, così fatto:
{
"soggetti": [
{
"cognome": "ROSSI",
"nome": "GIUSEPPE MARIO",
"datanascita": "20/02/1911",
"luogonascita": "SANT'OLCESE (GE)",
"sesso": "M",
"cf": "RSSGPP11B20I346W",
"idSoggetto": "MTI1NDAxMTU0NiMwI1JPU1NJI0dJVVNFUFBFIE1BUklPI1JTU0dQUDExQjIwSTM0NlcjU0FOVCdPTENFU0UjMjAvMDIvMTkxMSNHRQ=="
}
]
}
In particolare il campo idSoggetto, valido solo per questa chiamata, permette di proseguire nella ricerca degli immobili intestati attraverso i metodi successivi.
NB: La chiamata a questo metodo ritorna un cookie HTTP, da utilizzare per le chiamate successive. Il passaggio dei cookie avviene automaticamente se l'API è utilizzata all'interno di un browser; in caso di utilizzo da propri script, è necessario assicurarsi che le chiamate tengano traccia dei cookie. Se il linguaggio o la libreria utilizzata non permettono di gestire agevolmente i cookie, aggiungendo il parametro &easy=1 alla chiamata, il cookie viene ritornato come parametro SID nel JSON di risposta, cosi: https://thenetworksolution.it/sister/ricercaPersonaFisica.php?tiporicerca=cognome&tipoCatasto=E&nome=mario&cognome=rossi&&datanascita=14/02/1948&uffprovinciale=GENOVA%20Territorio-GE&easy=1
Ricerca per Codice Fiscale
Esempio:
https://thenetworksolution.it/sister/ricercaPersonaFisica.php?tiporicerca=CF_PF&tipoCatasto=E&cf=RSSBNM48B14D969T&uffprovinciale=GENOVA%20Territorio-GE
Praticamente, l'utilizzo è analogo. In questo caso l'array restituito contiene un solo oggetto in quanto il Codice Fiscale individua univocamente un soggetto.
Se viene specificato &uffprovinciale=NAZIONALE-IT è necessario visualizzare le province in cui il soggetto ha immobili con il metodo ricercaNazionale.php&idSoggetto= e ripetere la ricerca (vedere paragrafo Ricerca Nazionale).
Errori
{"err":"La ricerca restituisce troppi risultati."} Codice HTTP 500
{"err":"Parametri errati."} Codice HTTP 500
{"err":"Nessun risultato trovato."} Codice HTTP 404
Ricerca Immobili intestati a Persona Fisica
Per visualizzare gli immobili intestati a un soggetto, trovato tramite il metodo precedente, utilizzare il seguente metodo:
https://thenetworksolution.it/sister/immobili.php?idSoggetto=NTUwMjQ0OTc0NCMwI1JPU1NJI0JSVU5PIE1BUklPI1JTU0JOTTQ4QjE0RDk2OVQjR0VOT1ZBIzE0LzAyLzE5NDgjR0U=
dove idSoggetto è restituito dalla chiamata al metodo che precede, passando nella chiamata HTTP il cookie restituito dalle chiamate ai metodi precedenti *.
Risposta:
{
"immobili": {
"catasto": "F",
"titolarita": "Proprieta' per 1/1",
"ubicazione": "GENOVA (GE) Sez.Q VIA MARSILIO DA PADOVA, 6R Piano S1 int. 17",
"comune": "GENOVA",
"prov": "GE",
"sezione": "Q",
"foglio": "GEB/72",
"particella": "580",
"subalterno": "28",
"classamento": "zona1 cat. C/6",
"classe": "6",
"consistenza": "26 mq",
"rendita": "Euro:187,99 "
}
}
* In alternativa, è possibile passare il cookie come parametro &SID=, cosi:
https://thenetworksolution.it/sister/immobili.php?idSoggetto=...&SID=...
In presenza di porzioni (per terreni) o graffati (per immobili), vengono valorizzati i parametri altriDati=SI e idAltriDati, in tal caso è possibile visualizzare le ulteriori informazioni tramite il metodo https://thenetworksolution.it/sister/altriDati.php?id=…
Questi metodi sono utilizzabili su specifiche province, non su ricerca nazionale (vedere paragrafo Ricerca Nazionale).
Per conoscere eventuali cointestati degli immobili restituiti, effettuare una ricerca per immobile con i metodi ultimaVariazione.php o mashIntestati.php
Ricerca di Persona Giuridica proprietaria di immobili
Analogamente ai metodi precedenti:
https://thenetworksolution.it/sister/ricercaPersonaGiuridica.php?tiporicerca=denominazione&tipoCatasto=E&denominazione=fiat&uffprovinciale=GENOVA%20Territorio-GE
{
"soggetti": [
{
"denominazione": "AUTOCARROZZERIA AUTORIZZATA FIAT DI TOBIA BALDASSARRE E C. S.N.C.",
"sede": "AGROPOLI (SA)",
"cf": "00000000018",
"idSoggetto": "...omissis..."
}
]
}
Questa chiamata non richiede un cookie, ma ne restituisce uno da usare con il metodo successivo.
Ricerca Immobili intestati a Persona Giuridica
https://thenetworksolution.it/sister/immobiliPG.php?idSoggetto=MTI1NDY5NDM2NSMwI0ZJQVQgQVVUTyBTUEEgQ09OIFNFREUgSU4gVE9SSU5PI1RPUklOTyAoVE8pIw==
{
"immobili": {
"catasto": "F",
"titolarita": "Proprieta' per 1/1",
"ubicazione": "GENOVA (GE) Sez.Q VIA GIOVANNI MONLEONE, 6 Piano T",
"comune": "GENOVA",
"prov": "GE",
"sezione": "Q",
"foglio": "GEB/72",
"particella": "520",
"subalterno": "15",
"classamento": "zona1 cat. A/10",
"classe": "2",
"consistenza": "6 vani",
"rendita": "Euro:1.967,70 "
}
}
Questo metodo sono utilizzabili su specifiche province, non su ricerca nazionale (vedere paragrafo Ricerca Nazionale).
Ricerca Nazionale di soggetto (persona fisica/giudirica) proprietario di immobili
Per cercare le province in cui un soggetto ha immobili:
https://thenetworksolution.it/sister/ricercaNazionale.php?idSoggetto=
https://thenetworksolution.it/sister/ricercaNazionalePG.php?idSoggetto=
dove idSoggetto è restituito dai metodi ricercaPersona(Fisica|Giudirica).php con uffprovinciale=NAZIONALE-IT
Ricerca Immobile
Per cercare tutti i dati di immobili dei quali si conoscono gli identificativi catastali:
https://thenetworksolution.it/sister/ricercaImmobile.php?tipoCatasto=F&uffprovinciale=GENOVA%20Territorio-GE&denomComune=D969%23GENOVA%2310%233&sezione=Q&sezUrb=GEB&foglio=72&particella=520&subalterno=15
I campi &sezUrb= e &subalterno= sono opzionali. Se non si specifica il subalterno, vengono restituite tutte le unità immobiliari presenti alla particella specificata, per esempio: https://thenetworksolution.it/sister/ricercaImmobile.php?tipoCatasto=F&uffprovinciale=GENOVA%20Territorio-GE&denomComune=D969%23GENOVA%2310%233&sezione=Q&foglio=72&particella=520
Per visualizzare gli intestati di un immobile, trovato tramite il metodo precedente, utilizzare ilil seguente metodo:
https://thenetworksolution.it/sister/intestati.php?idImmobile=MjIwMjkzMzU0IzE0MTg2MyNGI0dFQi83MiM1MjAjRDk2OSMyMDcyMCMxNSNRI0dFTk9WQQ==
(dove idImmobile è restituito dalla chiamata ai metodi precedenti e valido solo per la chiamata in corso), passando nella chiamata HTTP il cookie restituito dalle chiamate ai metodi precedenti *.
* In alternativa, è possibile passare il cookie come parametro &SID=, cosi:
https://thenetworksolution.it/sister/intestati.php?idSoggetto=...&SID=...
oppure utilizzare il metodo ultimaVariazione.php sopra descritto
Ricerca Immobili per Indirizzo
Per cercare un indirizzo:
https://thenetworksolution.it/sister/indirizzi.php?uffprovinciale=GENOVA%20Territorio-GE&comuneCat=D969%23GENOVA%2310%233&indirizzo=PASSAGGI
Il metodo restituisce gli indirizzi che contengono la stringa specificata nel parametro indirizzo. Per limitare la ricerca a specifici numeri civici, aggiungere i parametri &numCivicoDal= e &numCivicoAl=
E’ possibile specificare il parametro opzionale sezione, se conosciuto.
Per visualizzare gli immobili ubicati a tale indirizzo:
https://thenetworksolution.it/sister/ricercaIndirizzo.php?idIndirizzo=MTY5MyMyMzYjVklBIEFOTklCQUxFIFBBU1NBR0dJ
Il valore del parametro idIndirizzo, valido solo per questa chiamata, deve essere recuperato tramite il metodo precedente.
Per ottenere maggiori dati su immobili specifici usare uno fra i seguenti metodi: ultimaVariazione (da preferire in contesto multiutente); mashIntestati.php; ricercaImmobile.php+intestati.php
Acquisto visure per immobile
Per acquistare una visura ufficiale per immobile in formato PDF o XML firmato, chiamare nella stessa sessione (identificata dal cookie e dall’username) in cui è stata effettuata la ricerca:
https://thenetworksolution.it/sister/acquistaI.php?u=USERNAME&p=PASSWORD&idImmobile=NzgxOTIwNjExIzg1MTc2I0YjR0VCLzUzIzE4NCNEOTY5IzAwNjc5MjgjMiMjR0VOT1ZB&formato=PDF
{"url":"acquistate\/220293354#141863#F#GEB-72#520#D969#20720#15#Q#GENOVA.pdf"}
(dove idImmobile è restituito dalla chiamata a uno dei metodi precedenti che restituiscono immobili (immobili.php, immobiliPG.php, ricercaImmobile.php, ricercaIndirizzo.php) e valido solo per la chiamata in corso, passando tramite header HTTP il cookie restituito dalle chiamate ai metodi precedenti *.
Vale quanto specificato per il metodo mashVisuraI.php che si consiglia di usare in tutti i casi in cui si conoscono le coordinate catastali dell’immobile.
Acquisto visure per soggetto
Analogamente al metodo precedente, passando l'id di un soggetto restituito dai metodi precedenti nella medesima sessione:
https://thenetworksolution.it/sister/acquistaS.php?u=USERNAME&p=PASSWORD&idSoggetto=NTUwMjQ0OTc0NCMwI1JPU1NJI0JSVU5PIE1BUklPI1JTU0JOTTQ4QjE0RDk2OVQjR0VOT1ZBIzE0LzAyLzE5NDgjR0U%3D&formato=PDF
Questo metodo è utilizzabile su specifiche province, non su ricerca nazionale (vedere paragrafo Ricerca Nazionale).
Se in fase di ricerca soggetto (metodi ricercaPersonaFisica.php o ricercaPersonaGiuridica.php) è stata passato in input un comune, la visura è limitata a quel comune, altrimenti si riferisce all’intera provincia.
Ricerca note catastali (voltura, variazione, accatastamento)
https://thenetworksolution.it/sister/ricercaNota.php?tipoCatasto=F&uffprovinciale=GENOVA%20Territorio-GE&comuneCat=D969%23GENOVA%2310%233&sezione=Q&numNota=1&anno=2016&tipoNota=accatastamento
{"note":{"tipo":"V","numero":"000001","progressivo":"2016","anno":"20160102","datevalidita":"","repertorio":"VCL","causale":"20160102","inAttiDal":"VARIAZIONE DI CLASSAMENTO","descrizione":"","idNota":"MDAwMDAxIyMyMDE2IzAwMSMyMDE2MDEwMiNWIzM5MzkwNjQ="}}
Il valore del parametro comuneCat, composto, tra l'altro, dall'identificativo catastale del comune e dal numero di sezioni presenti, deve essere recuperato tramite il seguente metodo ausiliario:
https://thenetworksolution.it/sister/comuni.php?uffprovinciale=GENOVA%20Territorio-GE
Sono inoltre supportati i seguenti campi aggiuntivi: progressivo, numRepertorio, dataEff=yyyy-mm-dd (data di effettività dell'atto).
tipoNota può assumere seguenti valori: voltura, variazione, accatastamento. Sul catasto terreni è possibile cercare solo per voltura e variazione; nelle ricerche contemporanee su catasto terreni e fabbricati è possibile cercare solo per voltura.
Per acquistare una nota, chiamare in sequenza:
https://thenetworksolution.it/sister/acquistaN.php?idNota=MDAwMDAxIyMyMDE2IzAwMSMyMDE2MDEwMiNWIzM5MzkwNjQ=
{"url":"acquistate\/000001##2016#001#20160102#V#3939064.pdf"}
Le note vengono salvate sul server nella cartella "acquistate", ma non si pagano; per tale motivo non è presente nemmeno il meccanismo di cache visto per i metodi precedenti.
Elenchi immobili
Sister prevede la funzionalità Elenchi immobili che, dato un foglio e una particella e/o una tipologia di immobile, restituisce l'elenco degli immobili presentandoli insieme ai relativi graffati (fabbricati) o porzioni (terreni). Nelle ricerche puntuali per particella, questa funzionalità costituisce semplicemente una visualizzazione alternativa alla ricerca per immobile, ma a differenza della prima, permette di cercare tutti gli immobili che insistono su un foglio, a condizione di limitare la ricerca a una specifica tipologia.
https://thenetworksolution.it/sister/elencoImmobili.php?tipoCatasto=F&uffprovinciale=GENOVA%20Territorio-GE&comuneCat=D969%23GENOVA%2310%233&sezione=Q&sezUrb=GEB&foglio=72&particella=53
{
"elencoImmobili":[
{
"idImmobile":140146,
"graffati":[
{
"foglio":"GEB\/72",
"particella":"52",
"subalterno":"8",
"zona":"",
"partita":"Unita' immobiliare soppressa",
"rendita":"",
"indirizzo":""
},
{
"foglio":"GEB\/72",
"particella":"53",
"subalterno":"1",
"zona":"",
"partita":"Unita' immobiliare soppressa",
"rendita":"",
"indirizzo":""
}
]
},
...
]
}
Come sopra, il valore del parametro comuneCat, composto, tra l'altro, dall'identificativo catastale del comune e dal numero di sezioni presenti, deve essere recuperato tramite il seguente metodo ausiliario:
https://thenetworksolution.it/sister/comuni.php?uffprovinciale=GENOVA%20Territorio-GE
Il campo &sezUrb= è opzionale.
E' possibile limitare la ricerca a uno specifico range di subalterni aggiungendo i parametri opzionali subDa e subA.
E' possibile limitare la ricerca ad una specifica tipologia di immobile aggiungendo i parametri opzionali partitaSpeciale e categoria, i cui possibili valori devono essere recuperati tramite i seguenti metodi ausiliari:
https://thenetworksolution.it/sister/partiteSpeciali.php?tipoCatasto=F
https://thenetworksolution.it/sister/partiteSpeciali.php?tipoCatasto=T
https://thenetworksolution.it/sister/categorie.php?tipoCatasto=F&uffprovinciale=GENOVA%20Territorio-GE&comuneCat=D969%23GENOVA%2310%233
https://thenetworksolution.it/sister/categorie.php?tipoCatasto=T&uffprovinciale=GENOVA%20Territorio-GE&comuneCat=D969%23GENOVA%2310%233
Il campo &particella= è opzionale se limita la ricerca ad una specifica tipologia tramite i due parametri appena indicati.
Ispezioni ipotecarie
NB: La ricerca di un soggetto o di un immobile su Sister, per conoscere l’elenco delle formalità associate, costa 6,40 euro, prezzo definito da Sister. Per ogni ricerca effettuata, è possibile acquistare massimo UNA formalità, al prezzo definito da Sister, di circa 3,60 € (per acquistare più formalità va ripetuta più volte la ricerca). L’acquisto dell’elenco sintetico delle note prodotto da Sister (in formato PDF su carta intestata dell’AdE) è invece gratuito.
Pertanto l’acquisto di ciascuna formalità costa di fatto 10 euro.
Ricerca ispezioni ipotecarie
Ricerca per Codice Fiscale - Persona fisica
Esempio:
https://thenetworksolution.it/sister/ispezioniPersonaFisica.php?u=USERNAME&p=PASSWORD&tiporicerca=CF_PF&conservatoria=GENOVA&cf=RSSMRA66M23B490W
che restituisce l'elenco degli omocodici:
{"soggetti":[{"cognome":"ROSSI","nome":"MARIO","datanascita":"23\/08\/1966","sesso":"M","luogonascita":"CAMOGLI (GE)","cf":"RSSMRA66M23B490W","idSoggetto":"OTgwNDA0MDc4Ny0w","ispezioneNum":"T188025"}]}
Ricerca per nome - persona fisica
https://thenetworksolution.it/sister/ispezioniPersonaFisica.php?u=USERNAME&p=PASSWORD&tiporicerca=Cognome&conservatoria=GENOVA&nome=mario&cognome=rossi&dataNascita=23%2F06%2F1966
NB: effettuare l'url encoding dei campi
Ricerca per codice fiscale - persona giuridica
https://thenetworksolution.it/sister/ispezioniPersonaGiuridica.php?u=USERNAME&p=PASSWORD&tiporicerca=CF&conservatoria=GENOVA&cf=...
Il parametro tipoRicerca può assumere valori ANAGRAFICA e CF.
Ricerca per denominazione - persona giuridica
https://thenetworksolution.it/sister/ispezioniPersonaGiuridica.php?u=USERNAME&p=PASSWORD&tiporicerca=denominazione&conservatoria=GENOVA&denominazione=...
Ricerca per immobile
http://thenetworksolution.it/ispezioniImmobile.php?u=USERNAME&p=PASSWORD&conservatoria=LATINA&denomComune=G698%23LTPRIVERNO%23%23&sezCens=&sezUrb=&foglio=31&particella=516&subalterno=19&tipoCatasto=F
che risponde:
{
"body": {
"ispezioneNum": "T1702",
"ispezioneDel": "01/03/2026",
"ispezioneUser": "DNGMVT93H22I330N",
"ispezioneConservatoria": "ROMA 1",
"soggetti": [
{
"identificativoDefinitivo": {
"sezione": "",
"sezioneUrb": "",
"foglio": "0669",
"particella": "03935",
"subalterno": "0020"
},
"identificativoProvvisorio": {
"tipoDenuncia": "",
"num": "",
"anno": ""
},
"idImmobile": "MTQ2MDMyODQy"
}
]
}
Il valore del parametro denomComune, composto, tra l'altro, dall'identificativo catastale del comune e dalla sigla della provincia, deve essere recuperato tramite il seguente metodo ausiliario:
http://thenetworksolution.it/comuniConservatorie.php?u=USERNAME&p=PASSWORD&conservatoria=LATINA
con URL-encoding dei caratteri speciali, per es # = %23
Quindi sarà necessario selezionare un soggetto o un immobile fra quelli proposti, tramite il metodo ispezione.php più sotto dettagliato.
I metodi ispezione*.php richiedono l'utilizzo delle proprie credenziali - con credito sufficiente per pagare le ispezioni come richiesto dal catasto - da specificare con gli appositi parametri u e p. L'importante parametro ispezioneNum consente di evitare addebiti multipli per la stessa chiamata a ispezioni(PersonaFisica|PersonaGiuridica|Immobili).php: aggiungendo il parametro &ispezioneNum= alla chiamata ai metodi ispezioni(PersonaFisica|PersonaGiuridica|Immobili).php, il sistema recupera la ricerca (“elenco omonimi”) precedentemente effettuata e già pagata (il cui costo è 6,30 € per le ricerche non nazionali ed oltre 18 euro per quelle nazionali) dagli elenchi contabilizzati di Sister della settimana:
E' possibile recuperare gli ID T___ degli elenchi omonimi, già pagati, tramite il metodo ausiliario:
https://thenetworksolution.it/sister/elenchiContabilizzati.php?u=USERNAME&p=PASSWORD&conservatoria=GENOVA&elencoCont=EO
dove il parametro elencoCont=EO indica che si vuole recuperare l’elenco omonimi.
Se non è specificato il parametro &data=dd/mm/yyyy vengono visualizzate le ispezioni dell’ultima settimana.
{"ispezioni":[{"ispezione":"T205845 del 2022-06-27 14:08:34","dati":"RICERCA PER PERSONA FISICA Codice Fiscale: ZNEFNC59M27A703Z","risultati":"Omonimi: 1 Omocodici: 0","disponibile":false},{"ispezione":"T238310 del 2022-06-28 14:03:16","dati":"RICERCA PER PERSONA FISICA Codice Fiscale: ZNEFNC59M27A703Z","risultati":"Omonimi: 1 Omocodici: 0","disponibile":false}]}
NB: Sister permette il recupero di elenchi omonimi già pagati fino a quando con l’apposito metodo ispezione.php non viene selezionato un soggetto specifico. Dopo la selezione di un soggetto o un immobile, non è più possibile accedere all’elenco omonimi o selezionare un altro soggetto o immobile, e bisogna effettuare una nuova ricerca a pagamento. Tale situazione è segnalata dal campo booleano “disponibile” riportato nell’output del metodo elenchiContabilizzati.php.
Selezione di un soggetto
Per selezionare un soggetto o un immobile, cioè per visualizzare l'elenco sintetico delle formalità di un soggetto o un immobile restituito dalle chiamate precedenti, utilizzare il seguente metodo:
https://thenetworksolution.it/sister/ispezione.php?u=USERNAME&p=PASSWORD&idSoggetto=OTgwNDA0MDc4Ny0w
{“ispezioneNum”: “T35395”, "note":[{"titolo":"...","idNota":"..."}]}
Nel caso di ricerche nazionali il metodo ritorna l'elenco delle conservatorie nelle quali sono presenti documenti, sulle quali conservatorie effettuare una nuova ispezione con uno dei metodi precedenti: ispezionePersonaFisica|PersonaGiuridica|Immobile.php
Nel caso di ricerche non nazionali, il metodo restituisce direttamente l’elenco delle formalità.
Per ciascuna ricerca può essere selezionato un solo soggetto o immobile, quindi è consentito un unico utilizzo del metodo ispezione.php per ciascun ispezioneNum restituito dai metodi di ricerca precedenti (ispezioniPersonaFisica.php, ispezioniPersonaGiuridica.php, ispezioniImmobile.php).
L'importante parametro ispezioneNum ritornato nell’output di ispezione.php è sempre diverso da quello restituito precedentemente dai metodi per la ricerca di soggetti o immobili, e consente di recuperare più volte l’elenco delle formalità del soggetto già selezionato. Aggiungendo il parametro &ispezioneNum=__ alla chiamata a ispezione.php, il sistema recupera le formalità del soggetto già selezionato dagli elenchi contabilizzati di Sister della settimana:
https://thenetworksolution.it/sister/ispezione.php?u=USERNAME&p=PASSWORD&conservatoria=BASSANO%20DEL%20GRAPPA&ispezioneNum=T118927&elencoCont=EF
E' possibile recuperare gli ID T___ degli elenchi formalità, già pagati, tramite il metodo ausiliario già visto poc’anzi, modificando l’apposito parametro in elencoCont=EF (Elenco Formalità):
https://thenetworksolution.it/sister/elenchiContabilizzati.php?u=USERNAME&p=PASSWORD&conservatoria=GENOVA&elencoCont=EF
Se non è specificato il parametro &data=dd/mm/yyyy vengono visualizzate le ispezioni dell’ultima settimana. Si ricorda che l’elenco delle formalità è disponibile solo per ricerche non nazionali.
Acquisto di una formalità
Per acquistare una delle formalità (nota, o titolo telematico se presente) restituite dal metodo ispezione.php utilizzare il seguente metodo:
https://thenetworksolution.it/sister/acquistaF.php?u=USERNAME&p=PASSWORD&idNota=...&formato=PDF&documento=nota
{"url":"acquistate\/ME0010124910002020-04-08-2020-2020-0-8-0-Trascrizione-12491-0-17119-TRASCRIZIONE A FAVORE del 04-08-2020 - Registro Particolare 12491 Registro Generale 17119-TIT0-1129--.pdf"}
Il parametro "documento" può assumere valori "nota", "titolo", “elenco”, quest’ultimo per acquisto degli elenchi sintetici prodotti da Sister (gratuiti).
Di seguito un esempio di acquisto di elenco sintetico:
https://thenetworksolution.it/sister/acquistaF.php?u=USERNAME&p=PASSWORD&documento=elenco
Il parametro "formato" può assumere valori "PDF" o "XML" (dove disponibile).
Al fine di evitare addebiti indesiderati, il sistema mantiene in cache per 24 ore i documenti già acquistati (il cui costo è di circa 3,60 € per le note ed oltre 7 € per titoli telematici). E' possibile specificare una diversa durata della cache tramite il parametro &cache=nn dove nn è il numero di ore, o disabilitare la cache con &cache=0.
Ricerca note ipotecarie (trascrizioni, iscrizioni, annotazioni, privilegi agrari, privilegi speciali, privilegi minerari)
E’ possibile verificare gratuitamente se una nota ipotecaria di cui si conoscono gli estremi (numero di registro generale o particolare e anno) insiste su uno specifico soggetto (persona fisica, persona giuridica, immobile) di cui si conoscono gli estremi (nome, cognome e/o data/luogo di nascita, o CF, per immobili, dati catastali).
su un immobile:
https://thenetworksolution.it/sister/notaIpotecaria.php?u=USERNAME&p=PASSWORD&conservatoria=NAPOLI%201&tiporicerca=particolare|generale &tiponota=iscrizioni&restrizione=IM&regn=1430&anno=2015&catasto=F&denomComune=NANAPOLI&foglio=21&particella=375&subalterno=27
su una persona fisica, per codice fiscale:
https://thenetworksolution.it/sister/notaIpotecaria.php?u=USERNAME&p=PASSWORD&conservatoria=NAPOLI%201&tiporicerca=particolare|generale &tiponota=iscrizioni&restrizione=PF&regn=1430&anno=2015&catasto=F &cf=RSSBNM48B14D969T
su una persona fisica, per dati anagrafici:
https://thenetworksolution.it/sister/notaIpotecaria.php?u=USERNAME&p=PASSWORD&conservatoria=NAPOLI%201&tiporicerca=particolare|generale &tiponota=iscrizioni&restrizione=PF&regn=1430&anno=2015&catasto=F &nome=Mario&cognome=Rossi
Sono obbligatori solo nome e cognome, è possibile aggiungere ulteriori filtri di ricerca per sesso, data e luogo di nascita, tramite i seguenti parametri: &gg=4&mm=6&aaaa=1986&sesso=M&siglaprov=GE&luogo=GENOVA
su una persona giuridica, per codice fiscale:
https://thenetworksolution.it/sister/notaIpotecaria.php?u=USERNAME&p=PASSWORD&conservatoria=NAPOLI%201&tiporicerca=particolare&tiponota=iscrizioni&restrizione=IM&regn=1430&anno=2015&catasto=F&cf=00000000018
su una persona giuridica, per dati anagrafici:
https://thenetworksolution.it/sister/notaIpotecaria.php?u=USERNAME&p=PASSWORD&conservatoria=NAPOLI%201&tiporicerca=particolare|generale&tiponota=iscrizioni&restrizione=IM&regn=1430&anno=2015&catasto=F&denom=fiat
E’ obbligatoria solo la denominazione, è possibile aggiungere ulteriori filtri di ricerca per provincia e comune sede legale, tramite i seguenti parametri: &siglaprov=GE&luogo=GENOVA
Le sigle province consentite sono elencate dal metodo provincia.php:
AG, AL, AN, AO, AP, AQ, AR, AT, AV, BA, BG, BI, BL, BN, BO, BR, BS, BZ, CA, CB, CE, CH, CL, CN, CO, CR, CS, CT, CZ, EE, EN, FC, FE, FG, FI, FM, FO, FR, FU, GE, GO, GR, IM, IS, KR, LC, LE, LI, LO, LT, LU, MC, ME, MI, MN, MO, MS, MT, NA, NO, NU, OR, PA, PC, PD, PE, PG, PI, PL, PN, PO, PR, PS, PT, PU, PV, PZ, RA, RC, RE, RG, RI, RM, RN, RO, SA, SI, SO, SP, SR, SS, SV, TA, TE, TN, TO, TP, TR, TS, TV, UD, VA, VB, VC, VE, VI, VR, VT, VV, ZA
Sono incluse le province soppresse (per es ZA), in quanto possono figurare negli atti più vecchi. Specificare prov=EE per estero.
Solo per questo metodo, il campo denomComune deve contenere provincia+comune, senza codice catastale, come restituiti dal metodo comuniConservatorie.php (es. comuniConservatorie.php restituisce F839#NANAPOLI##, in denomComune indicare NANAPOLI)
Il campo tiponota può assumere i seguenti valori: iscrizioni, annotazioni, trascrizioni, agrari, minerari, speciali.
Il campo tiporicerca può assumere i seguenti valori: particolare, generale.
Per ricerche per numero di registro particolare, è supportato anche il campo opzionale regn2 per specificare l’eventuale secondo identificativo.
Il campo restrizioni può assumere i seguenti valori: PF, PNF, IM.
Output positivo:
{"note":[{"titolo":"ISCRIZIONE del 19\/05\/2015 - Registro Particolare 1430 Registro Generale 10929 Nota disponibile in formato elettronico","idNota":"TkExMDIwMDE0MzAwMDAyMDE1LTE5LzA1LzIwMTUtMjAxNS0wLTgtMC1Jc2NyaXppb25lLTE0MzAtMC0xMDkyOS1USVQwLTE1NzE1LzIwMTQtLQ=="}]}
Output negativo:
{"err":"Nessun risultato trovato"}
Anche in questo caso è possibile procedere all’acquisto della nota o del titolo telematico, dove disponibile, tramite il metodo acquistaF.php.
Lo script è comprensivo di codice sorgente (PHP 5/7 senza dipendenze esterne). Richiede un’utenza Sister. Lo script è fruibile in modalità on-premise, cioè installabile su un vostro server, o in modalità SaaS, cioè utilizzabile tramite il nostro specificando nella chiamata le vs credenziali Sister con gli appositi parametri.
Note tecniche
Supporto per chiamate concorrenti
Lo script supporta ricerche concorrenti con lo stesso account. Sister da browser normalmente non permette la navigazione contemporanea (per es. su più schede del browser). Lo script implementa questo supporto ripetendo, ad ogni chiamata effettuata, le chiamate fatte precedentemente e che sarebbero necessarie su browser per arrivare a quel punto . La ripetizione delle chiamate è implementata nel file login.php dal metodo doRepeat(). Inoltre, chiamate contemporanee vengono soddisfatte in sequenza grazie a un meccanismo di locking implementato nel metodo login.php con la funzione flock(). A tal fine è possibile distinguere i metodi in diverse tipologie:
- metodi iniziali: sono i metodi che non prevedono alcuna ripetizione della “navigazione” precedente, come ricercaPersonaFisica.php, ricercaPersonaGiuridica.php, ricercaImmobile.php, ricercaIndirizzo.php, sezioni.php, comuni.php, e tutti i metodi senza credenziali come uffprovinciali.php.
- metodi intermedi: sono tutti i metodi chiamati successivamente ai metodi iniziali (per es immobili.php, che va chiamato a seguito di una ricerca per soggetto), memorizzano le operazioni fatte nel corso della stessa ricerca ed effettuano la ripetizione della “navigazione”. Quando viene chiamato un metodo iniziale sullo stesso account (parametro u), la ricerca eventualmente in corso su quello stesso account si interrompe e deve essere rifatta dall’inizio in quanto le informazioni sulle richieste da ripetere vengono eliminate (per es. se si cerca il soggetto Mario Rossi con ricercaPersonaFisica.php e poi si chiama comuni.php, metodo iniziale, poi non sarà più possibile chiamare immobili.php per proseguire la ricerca interrogando gli immobili di Mario Rossi: bisognerà ripetere la chiamata a ricercaPersonaFisica.php). Per tale motivo gli URL che contengono un ID non devono essere memorizzati (per esempio in un DB), in quanto funzioneranno se richiamati in seguito senza ripetere tutta la ricerca, anche se l’ID non cambia;
- metodi finali: sono i metodi che non prevedono una chiamata successiva, pertanto ripetono le operazioni precedenti ma non ne accodano di nuove.
La concorrenza comporta un overhead aggiuntivo. La concorrenza può essere disabilitata impostando CONCURRENCY=false nel file di configurazione (solo per installazioni on-premise) per ottenere un leggero guadagno di prestazioni, se si è in grado di garantire che il proprio applicativo effettuerà correttamente le chiamate in sequenza (metodo consigliato), cioè senza interleaving delle chiamate fra metodi intermedi, per es. script batch, cronjob.
Le prestazioni massime raggiungibili sono quelle riscontrabili sui metodi mashImmobili.php e mashIntestati.php in quanto tali metodi sono atomici, non richiedono concorrenza e non contengono ulteriori logiche applicative. I metodi mash* sono metodi speciali, sia iniziali che finali. Se si utilizzano soltanto metodi mash* e metodi iniziali, l’attivazione del supporto concorrente è indifferente.
Tramite lo script bench.php che non richiede parametri, è possibile misurare la velocità di scaricamento di una pagina Sister da parte dello script, normalmente inferiore a 0.05 secondi. Occasionalmente Sister può riscontrare rallentamenti su alcune richieste che possono impattare lo script. Quando accade, tali rallentamenti sono visibili anche richiamando più volte in loop tale script. Si consideri che con il supporto concorrente attivo, ogni chiamata allo script si traduce in anche 3/4 chiamate a Sister.
Tramite lo script session.php, che non richiede parametri, è possibile vedere le chiamate accodate per la ripetizione al prossimo metodo intermedio che verrà chiamato.
Tra la chiamata a metodi iniziali e intermedi, o tra metodi intermedi non devono trascorrere più di 24 minuti (default). Oltre tale limite, PHP non mantiene i dati della sessione (gestita tramite cookie restituiti da ogni chiamata). Tale limite è modificabile tramite la direttiva PHP session.gc_maxlifetime.
Se un metodo intermedio viene chiamato più volte (per es. ricercaImmobile.php senza subalterni, seguito da più chiamate a intestati.php per recuperare i proprietari di ciascun immobile restituito), non avvengono comunque ripetizioni superflue grazie ad un accurato controllo effettuato nel metodo doRepeat(), ma tale situazione viene registrata nel file log.txt in quanto l’utilizzo dello stesso metodo intermedio più volte nell’ambito di una stessa ricerca è inefficiente e sconsigliato, poiché la ricerca per immobili senza subalterno deve essere ripetuta ad ogni chiamata (procedura consigliata: recuperare gli intestati di ciascun immobile, di cui ora si conosce il subalterno, tramite il metodo atomico mashImmobile.php, o al limite con il metodo iniziale immobili.php + intestati.php, posto che una ricerca puntuale di un immobile specifico è più veloce rispetto a una ricerca per immobili senza subalterno)
Handy tools
https://www.urlencoder.org/
http://json.parser.online.fr/
Template di file config.php
<?php
define('MAIL', 'user@domain.ext');
define('CONCURRENCY', true); // auto-login + concurrency
define('STORED_CREDENTIALS', true); // false = richiede passaggio credenziali Sister dell'utente ad ogni chiamata; true = utilizza le credenziali specificate in config.php
define(‘CONNECTTIMEOUT_MS’, 20000);
$logins = array(
array('j_username' => 'username1', 'j_password' => 'password1'),
array('j_username' => 'username2', 'j_password' => 'password2')
);
?>
Se STORED_CREDENTIALS=true, il sistema si logga su Sister con le credenziali specificate nell’array login. Specificando più di una coppia di credenziali, in caso di problemi con il login (per es. Utente già in sessione, Password scaduta, …), il sistema passerà automaticamente a quella successiva (se CONCURRENCY=true). E’ possibile conoscere l’utenza attualmente in uso leggendo il file currentaccount.txt nella directory dello script, che contiene la posizione nell’array (0, 1, ..) dell’utenza in uso. E’ sempre possibile utilizzare credenziali differenti su specifiche chiamate passandole in GET o POST tramite i parametri u e p. Le chiamate che comportano un addebito da parte di Sister devono essere sempre eseguite passando vs credenziali.
Se STORED_CREDENTIALS=false, è necessario passare le credenziali ad ogni chiamata con i parametri u e p.
Se CONCURRENCY=false è inoltre necessario gestire manualmente il login tramite i metodi do_login.php?u=&p= e logout.php. In questo caso è inutile passare le credenziali ad ogni chiamata successiva, e si può impostare STORED_CREDENTIALS=true (anche mantene in modo che il sistema non le pretenda ad ogni chiamata.
Gestione del login con CONCURRENCY=true
1. Ad ogni chiamata lo script verifica se l’utenza in uso, cioè quella specificata nel file di configurazione in $logins e currentaccount.txt, o quella passata come parametri, è già loggata su Sister, caricando l’home page del servizio.
2. Se la sessione è scaduta o non è loggato, viene richiesto automaticamente ed in maniera trasparente all’utente un nuovo login con la stessa utenza (chiamata a goto login *);
3. Tentativo di login:
a. Se il login fallisce:
i. Se STORED_CREDENTIALS=true, si passa all’account successivo nell’array $logins, fino ad un numero di tentativi pari a RETRIES (default 2). Si raccomanda di predisporre almeno due utenze dedicate esclusivamente allo script. Se il numero di account è inferiore a RETRIES, verranno riprovati più volte gli stessi account.
ii. Se STORED_CREDENTIALS=false, si ritenta con l’account passato, per un numero di volte pari a RETRIES (default 1), se non ha successo l’errore viene restituito al chiamante. Si raccomanda di mantenere il valore RETRIES=1.
b. Se il login ha successo:
i. ripetizione delle chiamate.
I valori di RETRIES nei due casi sono configurabili all’interno del file login.php.
Sister non permette il login contemporaneo su più dispositivi (o da browser e script contemporaneamente) pertanto si consiglia di predisporre credenziali riservate esclusivamente allo script; in ogni caso è necessario effettuare il logout da browser prima di utilizzare lo script. E’ possibile effettuare il logout dall’account usato con lo script, al fine di poter accedere da browser o risolvere eventuali problemi, tramite il metodo https://thenetworksolution.it/sister/logout.php?u= __&p=___
Ovviamente, se STORED_CREDENTIALS=true, successive chiamate provocheranno immediatamente un nuovo login.
Il cambio password automatico non è supportato. E’ necessario cambiare autonomamente la password prima della scadenza per evitare interruzioni del servizio.
Logs
Per ogni chiamata, il file log-YYYYMMDD.html memorizza le pagine navigate dalla procedura di login (home page Sister + eventuale sequenza di relogin). Se alla chiamata sono passate credenziali, il file assume nome log-USERNAME.htm (non diviso in giorni), altrimenti il file è unico. Il file viene sempre visualizzato senza gli stylesheet di Sister.
Il file hits.txt è un contatore del numero di chiamate complessivamente effettuate ai metodi dello script. Se alla chiamata sono passate credenziali, il file è nominato con lo stesso formato di quello di log, altrimenti è unico.
Il file log.txt registra:
- i tentativi di login effettuati, e relativo esito, con data, ora e id univoco assegnato dallo script;
- il cambio di account (se si usano le STORED_CREDENTIALS) quando il login su un account fallisce;
- ogni volta che Sister propone l’informativa privacy;
- gli errori http
- le richieste ripetute uguali più volte in sequenza / refresh di pagina
E’ possibile abilitare la registrazione dell’intera sequenza di chiamate a Sister (home page Sister + eventuale sequenza di relogin + navigazione su Sister) impostando VERBOSE=true in config.php. In tal caso ogni richiesta e risposta scambiata con Sister e la risposta restituita dallo script al chiamante vengono accodati al file di log. Il log è strutturato con accordion per facilità di consultazione tramite browser. Tramite il parametro HOURLY_LOGS=true in config.php verrà creato un file per ogni ora log-YYYYMMDDHH.html per maggiore fruibilità con il browser dei log molto grandi. Per maggiore velocità di navigazione del log si consiglia di aprire il browser in modalità privata, soprattutto in presenza di plugin, come i password manager, che tentano di agganciarsi ai numerosi form presenti nelle pagine Sister loggate, peggiorando la fluidità della navigazione nel log.
Per ogni metodo dello script chiamato il log riporta:
• il metodo chiamato;
• data e ora;
• id univoco della richiesta assegnato dal sistema;
• id di sessione del chiamante (utile per correlare una sequenza di richieste effettuate dalla stessa applicazione o utente)
• i parametri passati in GET e POST ($_REQUEST);
• le chiamate HTTP effettuate a Sister, e per ciascuna di tali chiamate:
o l’URL chiamato;
o il codice HTTP di risposta *;
o la durata della chiamata espressa in secondi (maggiori dettagli sono resi disponibili con tooltip);
o la risposta HTML;
• la risposta restituita dal metodo al chiamante.
*L’URL /initPortale restituisce sempre il codice HTTP 501 e non si tratta di un errore.
Alle richieste e risposte generate dalla stessa chiamata a un metodo dello script è anteposto un id univoco nella forma di HTML anchor <a name=”…”></a>. E’ possibile linkare o navigare ad una specifica richiesta nel log utilizzando un URL come il seguente: https//thenetworksolution.it/sister/log-USERNAME.html#637b6f8bb6642. In caso di errori di login riportati in log.txt, utilizzando l’’id univoco apposto a fianco del messaggio, è possibile verificare il dettaglio dello specifico errore in /log.html#idunivoco.
Attenzione: i file di log possono contenere dati personali e non devono essere usati come strumento di log.
Note
Attenzione agli url con www. / senza www. Anche se c'è l'alias, va usato in modo uniforme su tutte le chiamate: sono due domini diversi e i cookie non sono condivisi.
Lo script (ovvero il processo che lo esegue, php CLI, php-fpm o Apache, a seconda della propria configurazione) necessita di permessi di scrittura nella directory in cui è installato e nelle sottodirectory errs/ e acquistate/. I file che vengono sempre creati dopo la prima chiamata sono almeno i seguenti: lastpage.htm, cookie.txt, hits.txt, log.txt, lock (se CONCURRENCY=true) tutti nominati come per lastpage, a seconda della configurazione scelta in config.php.
In produzione gli errori PHP devono essere disattivati (display_errors=Off). Si consiglia di disattivare le E_NOTICE anche in ambiente di test.
Alcune ricerche su Sister richiedono fino a 40 secondi (si effettui per esempio da browser ricerca nazionale per persona fisica con un nome molto comune, come Mario Rossi, o una ricerca immobili per indirizzo su una via molto lunga). Se lo script è invocato tramite URL, si raccomanda di impostare la direttiva PHP max_execution_time ad almeno 60 secondi (default 30) per evitare timeout. Si ricorda che in base alla propria configurazione php, può essere necessario aumentare i timeout dei front-end Apache / nginx (quest’ultimo di default pari a 45 secondi) / IIS.
La libreria cURL usata da PHP deve essere una versione aggiornata.
Il file login.php fa uso dell’istruzione goto per la gestione degli errori. Si precisa che, in questo caso, non si tratta di una cattiva pratica di programmazione, ma di un noto pattern per la gestione degli errori, usato anche nel kernel Linux, nonché uno dei pochi usi corretti e raccomandati di goto (more info https://stackoverflow.com/questions/245742/examples-of-good-gotos-in-c-or-c).
Se si condividono via e-mail link contenenti credenziali, molti client li navigheranno per mostrarne l’anteprima. Questo può causare login indesiderati o addebiti indesiderati nel caso delle ispezioni. Il fenomeno può essere evitato impostando FORCE_POST=true nel file config.php, opzione che obbliga a utilizzare HTTP POST in tutte le chiamate che includono credenziali. L’opzione è disabilitata nell’installazione demo.
Sister applica un rate limiting di nginx, IP-based. E’ frequente incontrare questo fenomeno nella fascia oraria 10.00-11.00. Durante tale fenomeno, Sister ritarda artificialmente le connessione HTTPS ai propri server fino a 18/20 secondi. Si consiglia di impostare il timeout di PHP e del web-server a 120 secondi, sufficienti a non far andare in timeout nessuna chiamata, considerato che nessun metodo dello script effettua più di 6 chiamate a Sister (6 * 20 <= 120 s).
Le chiamate vanno in timeout se la connessione HTTPS richiede più di 200ms di tempo di connessione (configurabile tramite opzione CONNECTTIMEOUT_MS nel file config.php) e lo script risponde con un messaggio di errore. In caso di chiamata API, vengono restituiti nei campi errno, err e uniqid, rispettivamente il codice di errore cURL, il testo descrittivo dell’errore e l’id univoco della richiesta assegnato dal sistema. L’ID univoco della richiesta assegnato dal sistema è utile per la consultazione del log. In alternativa è possibile mantenere un timeout basso e lasciare che il sistema effettui fino a RETRIES tentativi (default 2) in modo completamente trasparente al chiamante.
Riferimenti normativi
L’utilizzo dei dati è consentito dall’art. 5 c. 4-bis D.L. 70/2011 e l’Informativa privacy agli intestati non è necessaria ex art. 14 c. 5 GDPR.
Per approfondimenti: circ. 5/2011 Agenzia del Territorio
Reference in New Issue View Git Blame Copy Permalink