• Autenticazione
• Le tre richieste
• La risposta
• Errori
• Il 503 notturno: quando sincronizzare
• Contate i record prima di sostituire la tabella
• Il 2 settembre
• Note pratiche
• Esempio in PHP

API tesserati UISP Bologna — documentazione per i client

Base URL: https://api.tex-uispbologna.app. Solo HTTPS, solo GET, solo JSON. Versione nel percorso: /v1.

Autenticazione

Ogni richiesta ai dati porta il token che vi è stato consegnato:

Authorization: Bearer tex_…

Il token identifica il vostro perimetro: quali tesserati vedete e con quali colonne. Non va mai in un browser né in un repository: è come una password. Senza token o con un token sbagliato la risposta è 401 in JSON.

Le tre richieste

L’unico parametro aggiuntivo è anno (vedi “Il 2 settembre”): qualunque altro parametro produce 400. I dati si filtrano in locale, dopo lo scarico.

Esempio:

curl -s -H "Authorization: Bearer $TOKEN" https://api.tex-uispbologna.app/v1/tesseramento
curl -s -H "Authorization: Bearer $TOKEN" "https://api.tex-uispbologna.app/v1/tesserato?tessera=270000000"

La risposta

{
  "anno_sportivo": 2027,
  "dati_aggiornati_al": "2026-09-03T02:31:37+02:00",
  "record_totali": 3328,
  "tesserati": [
    { "tessera": "270000000", "cf_socio": "…", "cognome": "…", "nome": "…", "data_nascita": "1972-08-20", "scad_certificato": null, "…": "…" }
  ]
}

• anno_sportivo: l’anno sportivo servito (2027 = dal 1° settembre 2026 al 31 agosto 2027).
• dati_aggiornati_al: quando i dati sono stati caricati l’ultima volta dalla UISP regionale. Cambia ogni notte; se non cambia da giorni, la regionale è ferma e i dati sono gli ultimi buoni.
• record_totali: quante righe ci sono in tesserati.
• Le colonne dipendono dal vostro perimetro. Ogni valore è una stringa oppure null; le date sono AAAA-MM-GG. Una riga è una tessera: la stessa persona con due tessere compare due volte, con lo stesso codice fiscale. tessera è univoca: è la chiave giusta per la vostra tabella.

Errori

Sempre JSON: {"errore": "…"}.

Il 503 notturno: quando sincronizzare

Ogni notte la UISP regionale svuota e ricarica i dati, di norma fra l’1:30 e le 3:10. Fra le 01:00 e le 04:00, finché il caricamento di oggi non è finito, l’API risponde 503 con l’header Retry-After (secondi) e un messaggio esplicito: non serve dati a metà. Quindi:

• pianificate il sync dopo le 05:00 (per esempio alle 05:15);
• su 503 riprovate più tardi e non svuotate mai la tabella locale: tenete i dati che avete.

Contate i record prima di sostituire la tabella

L’API non confronta i giorni fra loro: se un caricamento notturno della regionale fallisce a metà (raro, ma possibile), potreste ricevere 200 con molte meno righe del solito. Prima di sostituire la vostra tabella, confrontate record_totali con il numero di righe che avete già: se cala in modo anomalo, tenete i dati vecchi e riprovate il giorno dopo.

Il 2 settembre

Il 2 settembre l’API passa da sola all’anno sportivo nuovo, che quel giorno contiene poche decine di tesserati: quelli già rinnovati. Non è un errore, è l’anno nuovo. Se il vostro gestionale ha bisogno di vedere ancora l’anno vecchio durante la transizione, chiedete di essere abilitati al parametro anno:

curl -s -H "Authorization: Bearer $TOKEN" "https://api.tex-uispbologna.app/v1/tesseramento?anno=2026"

anno sceglie solo l’anno sportivo (quattro cifre, non oltre quello corrente); senza abilitazione risponde 403. Un anno precedente non ha la finestra notturna: si serve sempre.

Note pratiche

• Uno scarico completo al giorno basta: i dati cambiano solo di notte.
• Le risposte sono compresse se mandate Accept-Encoding: gzip (lo fa curl con CURLOPT_ENCODING): 2 MB diventano poche centinaia di KB.
• 5.000 righe decodificate in PHP occupano qualche decina di MB: con memory_limit a 128 MB siete tranquilli.
• GET /v1/health (senza token) dice se l’API è viva e a che data sono i dati.

Esempio in PHP

Tutto quello che serve per chiamare l’API e vedere i dati: curl e il token in una variabile d’ambiente. Cosa farne dopo, tabella locale compresa, è affar vostro.

<?php
// esempio.php — la chiamata all'API tesserati UISP Bologna e i dati che tornano.
// Uso:  TEX_API_TOKEN=tex_… php esempio.php
// Le altre due richieste cambiano solo l'URL: /v1/tesserato?cf=… e /v1/tesserato?tessera=…

$token = getenv('TEX_API_TOKEN');
if ($token === false || $token === '') { fwrite(STDERR, "manca TEX_API_TOKEN\n"); exit(1); }

$ch = curl_init('https://api.tex-uispbologna.app/v1/tesseramento');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING       => '',                                     // accetta gzip
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $token],
]);
$corpo = curl_exec($ch);
$stato = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($corpo === false || $stato !== 200) {                             // 401: token; 503: dati non pronti, riprovare
    fwrite(STDERR, "risposta $stato: " . ($corpo === false ? curl_error($ch) : rtrim($corpo)) . "\n");
    exit(1);
}

$dati = json_decode($corpo, true);
echo "anno sportivo {$dati['anno_sportivo']}, dati aggiornati al {$dati['dati_aggiornati_al']}, record {$dati['record_totali']}\n";
echo json_encode($dati['tesserati'][0] ?? null, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE), "\n";   // la prima riga, con tutte le colonne del vostro perimetro