Vai al contenuto

API di Ricerca Persone

L'API di ricerca persone permette di cercare individui nel database formativo in base a criteri di ricerca specifici, con possibilità di filtrare i risultati per visualizzare solo i formatori.

Endpoint

1
GET https://bc.formedil.it/api/ricerca-persone/

Autenticazione

Richiede autenticazione tramite API token.

Parametri Query

Parametro Tipo Descrizione Obbligatorio
q string Termine di ricerca (nome, cognome, codice fiscale) Sì
formatore boolean Filtra solo i formatori (default: false) No

Nota: Il parametro formatore può essere passato come true, 1, o on per filtrare solo i formatori.

Risposta

Proprietà della risposta

Campo Tipo Descrizione
q string Termine di ricerca utilizzato nella richiesta
formatore boolean Flag di filtro formatore utilizzato nella richiesta
error object o null Dettagli dell'errore, se presente
result array o null Array dei risultati della ricerca

Struttura degli oggetti nell'array result

Ogni oggetto nell'array result rappresenta una persona e contiene i seguenti campi:

Campo Tipo Descrizione
id string ID univoco della persona
persona_id string ID della persona con hash SHA-1
nome string Nome della persona
cognome string Cognome della persona
codice_fiscale string Codice fiscale della persona
nascita_data string Data di nascita in formato ISO
nascita_data_formatted string Data di nascita formattata in formato italiano (GG/MM/AAAA)
nascita_luogo string Luogo di nascita
nascita_provincia string Provincia di nascita
nascita_stato string Stato di nascita
residenza_indirizzo string Indirizzo di residenza
residenza_civico string Numero civico di residenza
residenza_cap string CAP di residenza
residenza_comune string Comune di residenza
residenza_provincia string Provincia di residenza
residenza_stato string Stato di residenza
telefono string Numero di telefono
email string Indirizzo email
formatore boolean Flag che indica se la persona è un formatore

Esempi di risposta

Ricerca con risultati

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
  "q": "Rossi",
  "formatore": false,
  "error": null,
  "result": [
    {
      "id": "12345",
      "persona_id": "7a89f023cbd4e7a59378ceba27f8654a12f8b987",
      "nome": "Mario",
      "cognome": "Rossi",
      "codice_fiscale": "RSSMRA80A01H501U",
      "nascita_data": "1980-01-01T00:00:00.000Z",
      "nascita_data_formatted": "01/01/1980",
      "nascita_luogo": "Roma",
      "nascita_provincia": "RM",
      "nascita_stato": "Italia",
      "residenza_indirizzo": "Via Roma",
      "residenza_civico": "123",
      "residenza_cap": "00100",
      "residenza_comune": "Roma",
      "residenza_provincia": "RM",
      "residenza_stato": "Italia",
      "telefono": "3331234567",
      "email": "mario.rossi@example.com",
      "formatore": false
    },
    {
      "id": "67890",
      "persona_id": "5d41402abc4b2a76b9719d911017c592eb5b435e",
      "nome": "Laura",
      "cognome": "Rossi",
      "codice_fiscale": "RSSLRA85E44H501Y",
      "nascita_data": "1985-05-04T00:00:00.000Z",
      "nascita_data_formatted": "04/05/1985",
      "nascita_luogo": "Milano",
      "nascita_provincia": "MI",
      "nascita_stato": "Italia",
      "residenza_indirizzo": "Via Milano",
      "residenza_civico": "456",
      "residenza_cap": "20100",
      "residenza_comune": "Milano",
      "residenza_provincia": "MI",
      "residenza_stato": "Italia",
      "telefono": "3397654321",
      "email": "laura.rossi@example.com",
      "formatore": true
    }
  ]
}

Ricerca solo formatori

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "q": "Rossi",
  "formatore": true,
  "error": null,
  "result": [
    {
      "id": "67890",
      "persona_id": "5d41402abc4b2a76b9719d911017c592eb5b435e",
      "nome": "Laura",
      "cognome": "Rossi",
      "codice_fiscale": "RSSLRA85E44H501Y",
      "nascita_data": "1985-05-04T00:00:00.000Z",
      "nascita_data_formatted": "04/05/1985",
      "nascita_luogo": "Milano",
      "nascita_provincia": "MI",
      "nascita_stato": "Italia",
      "residenza_indirizzo": "Via Milano",
      "residenza_civico": "456",
      "residenza_cap": "20100",
      "residenza_comune": "Milano",
      "residenza_provincia": "MI",
      "residenza_stato": "Italia",
      "telefono": "3397654321",
      "email": "laura.rossi@example.com",
      "formatore": true
    }
  ]
}

Nessun risultato

1
2
3
4
5
6
{
  "q": "NonEsistente",
  "formatore": false,
  "error": null,
  "result": []
}

Errore - Nessun termine di ricerca

1
2
3
4
5
6
7
8
{
  "q": "",
  "formatore": false,
  "error": {
    "message": "Nessun termine di ricerca fornito."
  },
  "result": null
}

Codici di stato HTTP

Codice Descrizione
200 Richiesta completata con successo
400 Richiesta non valida
401 Autenticazione fallita
500 Errore del server

Limitazioni

  • La ricerca restituisce un massimo di 20 risultati
  • Il termine di ricerca deve essere lungo almeno 1 carattere

Implementazione di esempio

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
async function ricercaPersone(searchTerm, soloFormatori = false) {
  const url = new URL('https://bc.formedil.it/api/ricerca-persone/');
  url.searchParams.append('q', searchTerm);

  if (soloFormatori) {
    url.searchParams.append('formatore', 'true');
  }

  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    }
  });

  return await response.json();
}

Per ulteriori esempi di implementazione, consultare la guida agli esempi.