Risposta rapida

L’API REST pubblica di 123 Consulenza ti permette di leggere dati su enti competenti, calcolare la scadenza degli attestati di formazione e monitorare lo stato del servizio. Endpoint sotto /api/v1/, risposte JSON con envelope { data, meta }, errori con envelope { error: { code, message } }. Nessuna chiave necessaria.

Quick start

Cinque chiamate per iniziare. Copia, incolla, sostituisci la provincia o il ruolo che ti interessa.

1. Health check

curl https://www.123consulenza.com/api/v1/health

2. Tutti gli enti

curl https://www.123consulenza.com/api/v1/enti?limit=10

3. Enti di una regione

curl "https://www.123consulenza.com/api/v1/enti?regione=lazio"

4. Ente competente per provincia

curl https://www.123consulenza.com/api/v1/enti/milano

5. Calcolo scadenza formazione

curl -X POST https://www.123consulenza.com/api/v1/scadenza-formazione \
  -H "Content-Type: application/json" \
  -d '{"ruolo":"preposto","tipo":"iniziale","dataRilascio":"2024-04-10"}'

Autenticazione

La versione v1 non richiede autenticazione. Non esistono API key, OAuth o header di firma. Puoi chiamare gli endpoint sia lato server sia direttamente dal browser (CORS aperto).

Per scenari ad alto volume o esigenze SLA, contattaci: valutiamo l’assegnazione di una key dedicata con limiti più alti e supporto prioritario.

Rate limiting

Nessun rate limit strutturale al momento. Applichiamo politiche best-effort a livello di CDN per proteggere il servizio. Linee guida:

Cache lato client almeno 5 minuti sulle risposte di /api/v1/enti.
Identificati con un User-Agent riconoscibile (nome software + versione + URL).
Evita chiamate parallele oltre 10 req/s: usa coda + retry esponenziale.
Risposte già contengono header Cache-Control: public, max-age=300, s-maxage=600, stale-while-revalidate=86400.

Versioning

La versione corrente è v1. Il numero di versione è incluso nel path (/api/v1/...). Cambi non retrocompatibili comporteranno una nuova major (/api/v2/...) con periodo di overlap di almeno 12 mesi. Le aggiunte non-breaking (nuovi campi opzionali, nuovi endpoint) sono pubblicate sotto la stessa major.

La versione viene esposta anche nell’oggetto meta.version di ogni risposta e nell’endpoint /api/v1/health.

Errori

Tutti gli errori restituiscono JSON con la forma:

{ "error": { "code": "invalid_input", "message": "Descrizione leggibile dell'errore" } }

code	HTTP status	Descrizione
invalid_json	400	Body JSON malformato o non parseabile.
invalid_input	400	Parametri non validi: il messaggio contiene il dettaglio dei campi.
unknown_role	400	Ruolo non riconosciuto dal motore scadenze.
not_found	404	Risorsa non trovata (provincia o regione inesistente).
method_not_allowed	405	Metodo HTTP non supportato dall’endpoint.
internal_error	500	Errore interno del server. Riprovare.

Endpoints

Espandi ogni endpoint per parametri, schema di risposta ed esempi nei tre linguaggi più comuni.

GET/api/v1/enti

Elenco enti competenti

Restituisce l’elenco completo degli enti competenti per provincia (ASL/ATS/AUSL/ULSS/ASP + INL + VVF). Paginabile, filtrabile per regione.

Parametri

Nome	In	Tipo	Obbl.	Descrizione
regione	query	string	no	Slug regione (es. lazio, lombardia).
limit	query	number	no	Numero massimo risultati (1–200, default 100).
offset	query	number	no	Offset di paginazione (default 0).

Schema di risposta

{
  "data": [ { "provincia": "Milano", "regione": "Lombardia", "asl": { ... }, "inl": { ... }, "vvf": { ... } }, ... ],
  "meta": { "version": "1.0", "total": 107, "limit": 100, "offset": 0, "license": "CC BY 4.0", "source": "www.123consulenza.com" }
}

Esempi

cURL

curl "https://www.123consulenza.com/api/v1/enti?regione=lazio&limit=20"

JavaScript (fetch)

const res = await fetch('https://www.123consulenza.com/api/v1/enti?regione=lazio');
const { data, meta } = await res.json();
console.log(data.length, meta.total);

Python (requests)

import requests
r = requests.get('https://www.123consulenza.com/api/v1/enti', params={'regione': 'lazio'})
payload = r.json()
print(len(payload['data']))

GET/api/v1/enti/{provincia}

Dettaglio ente per provincia

Restituisce ASL/INL/VVF competenti per la provincia indicata (slug, es. milano, roma, napoli).

Parametri

Nome	In	Tipo	Obbl.	Descrizione
provincia	path	string	sì	Slug provincia (es. milano).

Schema di risposta

{
  "data": { "provincia": "Milano", "regione": "Lombardia", "asl": { "nome": "...", "telefono": "...", "indirizzo": "...", "url": "..." }, "inl": { ... }, "vvf": { ... } },
  "meta": { "version": "1.0", "license": "CC BY 4.0", "source": "www.123consulenza.com" }
}

Esempi

cURL

curl https://www.123consulenza.com/api/v1/enti/milano

JavaScript (fetch)

const res = await fetch('https://www.123consulenza.com/api/v1/enti/milano');
const { data } = await res.json();

Python (requests)

import requests
r = requests.get('https://www.123consulenza.com/api/v1/enti/milano')
print(r.json()['data']['asl'])

POST/api/v1/scadenza-formazione

Calcolo scadenza formazione

Calcola la scadenza dell’attestato dato il ruolo, il tipo (iniziale/aggiornamento) e la data di rilascio. Risultato indicativo: la durata effettiva dipende dal caso specifico.

Parametri

Nome	In	Tipo	Obbl.	Descrizione
ruolo	body	string	sì	Identificativo ruolo (es. lavoratore-basso, preposto, rls).
tipo	body	string	no	"iniziale" (default) o "aggiornamento".
dataRilascio	body	string (YYYY-MM-DD)	sì	Data del rilascio dell’attestato.

Schema di risposta

{
  "data": { "ruolo": "preposto", "tipo": "iniziale", "dataRilascio": "2024-04-10", "scadenza": "2026-04-10", "giorniMancanti": 480, "stato": "valido" },
  "meta": { "version": "1.0" }
}

Esempi

cURL

curl -X POST https://www.123consulenza.com/api/v1/scadenza-formazione \
  -H "Content-Type: application/json" \
  -d '{"ruolo":"preposto","tipo":"iniziale","dataRilascio":"2024-04-10"}'

JavaScript (fetch)

const res = await fetch('https://www.123consulenza.com/api/v1/scadenza-formazione', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ ruolo: 'preposto', tipo: 'iniziale', dataRilascio: '2024-04-10' }),
});
const { data } = await res.json();

Python (requests)

import requests
r = requests.post(
  'https://www.123consulenza.com/api/v1/scadenza-formazione',
  json={'ruolo': 'preposto', 'tipo': 'iniziale', 'dataRilascio': '2024-04-10'},
)
print(r.json()['data'])

GET/api/v1/health

Health check

Restituisce lo stato del servizio e la versione corrente. Utile per monitoring lato integratore.

Schema di risposta

{
  "data": { "status": "ok", "version": "1.0", "timestamp": "2026-06-20T10:00:00.000Z" },
  "meta": { "version": "1.0" }
}

Esempi

cURL

curl https://www.123consulenza.com/api/v1/health

JavaScript (fetch)

const ok = (await (await fetch('https://www.123consulenza.com/api/v1/health')).json()).data.status === 'ok';

Python (requests)

import requests
print(requests.get('https://www.123consulenza.com/api/v1/health').json())

OpenAPI Spec

Specifica completa in formato OpenAPI 3.1 (JSON). Importabile in Postman, Insomnia, Swagger UI, Stoplight, Redocly e qualsiasi generator di SDK.

Scarica openapi.json Apri in Swagger Editor

Use cases

Software HR & payroll

Notifica automatica delle scadenze attestati per ogni lavoratore: chiami /api/v1/scadenza-formazione al variare di ruolo o data corso.

Gestionali consulenza del lavoro

Associazione automatica dell’attività cliente al corretto ente competente via lookup provincia (/api/v1/enti/{provincia}).

ERP food & HoReCa

Pannello multi-sede con riferimento ASL competente per ciascun punto vendita; integrazione nei flussi controlli sanitari.

Dashboard compliance

Monitor multi-aziendale per gruppi e holding: stato attestati e contatti ente competente in un solo posto.

Termini d’uso

I dati sono rilasciati in licenza Creative Commons Attribution 4.0 International (CC BY 4.0): puoi usarli, ridistribuirli e modificarli anche per scopi commerciali, a condizione di citare la fonte.

Citazione richiesta

«Dati: 123 Consulenza — licenza CC BY 4.0.»

I contenuti restituiti dall’API hanno finalità informativa e non sostituiscono la valutazione tecnica o legale del caso specifico. Per scelte operative consulta un professionista abilitato.

Contact sviluppatori

Ti serve un endpoint che ancora non esiste, un dataset aggiuntivo o una chiave dedicata per alto volume? Scrivici descrivendo il caso d’uso: rispondiamo entro 2 giorni lavorativi.

Apri ticket sviluppatori Email diretta

Vuoi integrare i nostri dati nel tuo prodotto?

Aiutiamo software gestionali, ERP e portali HR a integrare l’API e i widget 123 Consulenza in modo nativo.

Parla con il team oppure scrivi a info@123consulenza.it

Documentazione API — 123 Consulenza Open Data

Quick start

Autenticazione

Rate limiting

Versioning

Errori

Endpoints

Parametri

Schema di risposta

Esempi

Parametri

Schema di risposta

Esempi

Parametri

Schema di risposta

Esempi

Schema di risposta

Esempi

OpenAPI Spec

Use cases

Software HR & payroll

Gestionali consulenza del lavoro

ERP food & HoReCa

Dashboard compliance

Termini d’uso

Contact sviluppatori

Vuoi integrare i nostri dati nel tuo prodotto?