> For the complete documentation index, see [llms.txt](https://docs.opencityitalia.it/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opencityitalia.it/sito-web/moduli-integrativi-della-piattaforma/utilizzare-le-api-del-sito/effettuare-una-chiamata-api.md). # Effettuare una chiamata API ## Accedi alla documentazione All'interno del sito web, [accedi alla documentazione](/sito-web/moduli-integrativi-della-piattaforma/utilizzare-le-api-del-sito.md#documentazione-api) dedicata alle API del sito web.
Una volta qui, seleziona dall'elenco il tipo di API che vuoi utilizzare in base alle sezioni o ai contenuti del sito.
## Fai la chiamata Clicca sull'icona di espansione/collaso per aprire il dettaglio della chiamata API (1) e, una volta espanso, sulla voce "Try it out" a destra (2).
Compila i parametri di ricerca previsti dalla API (1) e clicca su "Execute" in basso (2).
Se i parametri sono validi, l'API restituirà una risposta con codice 200, come nell'esempio riportato qui sotto: ```json { "items": [ { "id": "609cab52a36fcaecc959671f46e0d1ca", "uri": "https://www.comune.bugliano.pi.it/api/openapi/amministrazione/documenti-e-dati/609cab52a36fcaecc959671f46e0d1ca#Modulo-di-richiesta-Bonus-Famiglia", "published_at": "2024-03-21T00:00:00+01:00", "modified_at": "2024-05-31T11:34:59+02:00", "is_public": true, "name": "Modulo di richiesta \"Bonus Famiglia\"", "has_code": "", "protocollo": "", "data_protocollazione": null, "image": [], "document_type": [ "Modulistica" ], "topics": [ { "id": "topic_1_economia_e_finanze", "uri": "https://www.comune.bugliano.pi.it/api/openapi/argomenti/topic_1_economia_e_finanze#Economia", "priority": 1 } ], "abstract": "Modulo di richiesta del bonus famiglia", "full_description": "", "file": null, "link": null, "attachments": [ { "filename": "File di test 1 (1).pdf", "uri": "http://www.comune.bugliano.pi.it/ocmultibinary/download/1454/33281/4/e9eefe956e4b029333899ea9dd948450.pdf/file/File+di+test+1+%281%29.pdf" }, { "filename": "File+di+test+1+%5B.pdf", "uri": "http://www.comune.bugliano.pi.it/ocmultibinary/download/1454/33281/4/e0580da203969a34b47427de4817b80f.pdf/file/File%2Bdi%2Btest%2B1%2B%255B.pdf" }, { "filename": "File+di+test+2+%5D.pdf", "uri": "http://www.comune.bugliano.pi.it/ocmultibinary/download/1454/33281/4/9a01048ccdef9d3f98bd7951d3429349.pdf/file/File%2Bdi%2Btest%2B2%2B%255D.pdf" }, { "filename": "File+di+test+4.pdf+%5D", "uri": "http://www.comune.bugliano.pi.it/ocmultibinary/download/1454/33281/4/cfbbc7452a501415eb912d1affd594a0.pdf+%5D/file/File%2Bdi%2Btest%2B4.pdf%2B%255D" } ], "has_organization": [ { "id": "84418d711e6f2bdc5fb6abea7372237a", "uri": "https://www.comune.bugliano.pi.it/api/openapi/amministrazione/uffici/84418d711e6f2bdc5fb6abea7372237a#Ufficio-Tributi", "priority": 1 } ], "license": [ "Creative Commons Attribution 4.0 International (CC BY 4.0)" ], "format": [ "PDF" ], "start_time": "2024-03-21T00:00:00+01:00", "end_time": null, "publication_start_time": "2024-03-21T00:00:00+01:00", "publication_end_time": null, "expiration_time": null, "data_di_firma": null, "has_dataset": [], "other_information": "", "legal_notes": "", "reference_doc": [], "keyword": [], "life_event": [], "business_event": [], "author": "", "tipo_di_risposta": [ "Orale" ], "interroganti": [], "gruppo_politico": [], "data_invio_uffici": null, "data_giunta": null, "data_risposta_consigliere": null, "giorni_interrogazione": 0, "data_consiglio": null, "giorni_adozione": 0, "announcement_type": [], "data_di_scadenza_delle_iscrizioni": null, "data_di_conclusione": null } ], "self": "https://www.comune.bugliano.pi.it/api/openapi/amministrazione/documenti-e-dati?offset=0&limit=50&searchTerm=Bonus+famiglia&sort=published&order=desc", "prev": null, "next": null, "count": 1 } ``` ### Esempi di utilizzo delle API I seguenti esempi mostrano come creare un'Unità organizzativa e pubblicare un atto nell'Albo pretorio tramite API. {% tabs %} {% tab title="Unità organizzativa" %} Creare un'Unità organizzativa non si riduce a una singola chiamata. La classe Unità organizzativa richiede alcuni campi obbligatori che sono relazioni verso altri contenuti: il sito accetta la creazione dell'unità solo se questi contenuti collegati esistono già ed è quindi possibile referenziarli tramite il loro URI. Per questo motivo occorre seguire un percorso ordinato, creando prima le classi di contenuto associate (l'Orario, il Punto di contatto e la Sede) e solo alla fine l'Unità organizzativa vera e propria. In particolare, la creazione dell'Unità organizzativa (POST /amministrazione/uffici) prevede due campi obbligatori di tipo relazione, ciascuno con almeno un elemento: has\_spatial\_coverage (la Sede, cioè un Luogo) e has\_online\_contact\_point (il Punto di contatto). A loro volta, sia il Punto di contatto sia la Sede possono richiamare un Orario. Di conseguenza l'Orario è il primo contenuto da creare. #### Il percorso in sintesi 1. Crea l'Orario (classe orari-uffici-e-strutture). 2. Crea il Punto di contatto (classe punti-di-contatto) e, se serve, collega l'Orario alla disponibilità telefonica. 3. Crea la Sede (classe luoghi) e collega l'Orario di apertura al pubblico. 4. Crea l'Unità organizzativa (classe uffici) referenziando via URI il Punto di contatto e la Sede. Tutte le chiamate che seguono sono richieste POST verso la base URL delle API del sito (nell'esempio ) e richiedono l'autenticazione con le credenziali di un redattore abilitato. Ogni creazione restituisce una risposta con l'id e l'URI del contenuto appena creato: l'URI è il valore che userai per collegare i contenuti tra loro nei passaggi successivi. #### 1. Crea l'Orario L'Orario descrive le fasce di apertura e si crea con una POST sulla classe orari-uffici-e-strutture. I campi obbligatori sono name, valid\_from e stagionalita (valori ammessi: Unico, Invernale, Estivo). Le singole fasce orarie si aggiungono poi come righe della tabella opening\_hours. ``` POST /api/openapi/classificazioni/orari-uffici-e-strutture Content-Type: application/json { "name": "Orari Ufficio Anagrafe", "valid_from": "2025-01-01", "stagionalita": "Unico" } ``` Dalla risposta ottieni l'URI dell'Orario (ad esempio .../classificazioni/orari-uffici-e-strutture/ORARIO\_ID): ti servirà nei passaggi successivi. A questo punto aggiungi le fasce orarie come righe della tabella opening\_hours dell'Orario appena creato, indicando per ogni giorno della settimana l'orario di apertura. ``` POST /api/openapi/classificazioni/orari-uffici-e-strutture/ORARIO_ID/opening_hours Content-Type: application/json { "monday": "09:00-13:00", "tuesday": "09:00-13:00", "wednesday": "09:00-13:00", "thursday": "09:00-13:00", "friday": "09:00-13:00", "saturday": "", "sunday": "" } ``` #### 2. Crea il Punto di contatto Il Punto di contatto raccoglie i recapiti dell'unità e si crea con una POST sulla classe punti-di-contatto. I campi obbligatori sono name e contact. Ogni recapito è una riga della tabella contact, con type (ad esempio email, telefono, pec), value (il recapito vero e proprio) e contact (l'etichetta mostrata). ``` POST /api/openapi/classificazioni/punti-di-contatto Content-Type: application/json { "name": "Contatti Ufficio Anagrafe", "contact": [ { "type": "email", "value": "anagrafe@comune.bugliano.pi.it", "contact": "Email" }, { "type": "telefono", "value": "050 000000", "contact": "Centralino" } ] } ``` #### 3. Crea la Sede (Luogo) La Sede è un contenuto della classe luoghi e rappresenta il luogo fisico dell'unità. Si crea con una POST su luoghi. I campi obbligatori sono name, type, abstract, image, accessibility, has\_address e help. Nel campo opening\_hours\_specification puoi collegare, tramite il suo URI, l'Orario creato al passo 1, così da mostrare gli orari di apertura al pubblico della sede. ``` POST /api/openapi/vivere-il-comune/luoghi Content-Type: application/json { "name": "Sede Municipale - Ufficio Anagrafe", "type": ["Sede municipale"], "abstract": "Sede dell'Ufficio Anagrafe", "accessibility": "accessibile", "has_address": [{ "address": "Piazza del Comune 1, Bugliano" }], "opening_hours_specification": [{ "uri": ".../classificazioni/orari-uffici-e-strutture/ORARIO_ID" }] } ``` #### 4. Crea l'Unità organizzativa Ora che Punto di contatto e Sede esistono, puoi creare l'Unità organizzativa con una POST sulla classe uffici. I campi obbligatori sono legal\_name, abstract, main\_function, type, has\_spatial\_coverage e has\_online\_contact\_point. Gli ultimi due sono relazioni con almeno un elemento: in has\_spatial\_coverage inserisci l'URI della Sede creata al passo 3, in has\_online\_contact\_point l'URI del Punto di contatto creato al passo 2. 
POST /api/openapi/amministrazione/uffici
Content-Type: application/json

{
"legal_name": "Ufficio Anagrafe",
"abstract": "Ufficio responsabile dei servizi anagrafici",
"main_function": "Gestione dell'anagrafe della popolazione residente",
"type": ["Ufficio"],
"has_spatial_coverage": [{ "uri": ".../vivere-il-comune/luoghi/LUOGO_ID" }],
"has_online_contact_point": [{ "uri": ".../classificazioni/punti-di-contatto/CONTATTO_ID" }]
}
Al termine dei quattro passaggi l'Unità organizzativa è pubblicata e mostra automaticamente i contatti, la sede e gli orari collegati. Se hai bisogno di rappresentare la gerarchia interna (ad esempio un Ufficio che dipende da un'Area), puoi valorizzare anche il campo hold\_employment con l'URI dell'unità di livello superiore, seguendo lo stesso principio: la struttura superiore deve esistere prima di essere referenziata. {% endtab %} {% tab title="Albo pretorio" %} {% hint style="warning" %} Questo caso d'uso consente di pubblicare gli atti nella sezione Documenti albo pretorio del sito in modo automatico, evitando l'editing manuale dei contenuti. Il beneficio è automatizzare la pubblicazione degli atti prodotti dal software di gestione documentale dell'Ente. Il requisito tecnico è disporre di un microservizio o di un middleware dedicato alla sincronizzazione tra il gestionale degli atti e il sito. {% endhint %} La documentazione delle API per la gestione dei contenuti del sito è raggiungibile dal percorso /openapi/doc del proprio sito. Le richieste vengono autenticate tramite Authorization Basic, usando le credenziali degli utenti redattori. L'accesso alle operazioni esposte dalle API è regolato dagli stessi permessi di lettura e scrittura visibili per quell'utente nel pannello "Gestione accessi redazione". Il payload del documento contiene riferimenti ad altre entità già presenti sul sito, in particolare gli argomenti (topics) e l'unità organizzativa responsabile (has\_organization). Come per l'Unità organizzativa, questi riferimenti vanno reperiti PRIMA della chiamata POST tramite apposite GET, copiando dalla risposta l'URI di ogni risorsa da collegare. Recupera prima gli argomenti con una GET sull'archivio argomenti, dal quale ottieni l'URI da usare nel campo topics: ``` curl -X GET "https://www.comune.bugliano.pi.it/api/openapi/argomenti" \ -H "accept: application/json" \ -H "Accept-Language: it-IT" \ -H "Authorization: Basic Y2ljY2lvOmJhbGVuYQ==" ``` Allo stesso modo recupera l'unità organizzativa responsabile con una GET sull'archivio uffici, dal quale ottieni l'URI da usare nel campo has\_organization: ``` curl -X GET "https://www.comune.bugliano.pi.it/api/openapi/amministrazione/uffici" \ -H "accept: application/json" \ -H "Accept-Language: it-IT" \ -H "Authorization: Basic Y2ljY2lvOmJhbGVuYQ==" ``` Se l'atto è collegato ad altre entità, recupera prima anche i relativi URI con le stesse modalità: gruppo\_politico dagli organi di governo, has\_dataset dai dataset, image dalle immagini, interroganti dai politici e reference\_doc dai documenti tecnici di supporto. ``` curl -X GET "https://www.comune.bugliano.pi.it/api/openapi/amministrazione/organi-di-governo" curl -X GET "https://www.comune.bugliano.pi.it/api/openapi/amministrazione/documenti-e-dati/dataset" curl -X GET "https://www.comune.bugliano.pi.it/api/openapi/media/immagini" curl -X GET "https://www.comune.bugliano.pi.it/api/openapi/amministrazione/politici" curl -X GET "https://www.comune.bugliano.pi.it/api/openapi/amministrazione/documenti-e-dati/documenti-tecnici-di-supporto" ``` L'utente redattore usa le proprie credenziali per creare un documento pubblico con una chiamata POST all'endpoint dei documenti albo pretorio. Di seguito un esempio di creazione di un documento: ``` curl -X POST "https://www.comune.bugliano.pi.it/api/openapi/amministrazione/documenti-e-dati/documenti-albo-pretorio" \ -H "accept: application/json" \ -H "Accept-Language: it-IT" \ -H "Authorization: Basic Y2ljY2lvOmJhbGVuYQ==" \ -H "Content-Type: application/json" \ -d "[payload]" ``` Un esempio di documentazione delle API è consultabile all'indirizzo . Di seguito un esempio di payload per la creazione di un documento dell'albo pretorio: 
{
  "id": "del_giu_2023_163",
    "is_public": true,
      "name": "Deliberazione della giunta comunale numero 163 del 2023",
        "has_code": "2295/2023",
          "protocollo": "2295/2023",
            "data_protocollazione": "2023-09-25",
              "document_type": ["Deliberazione della Giunta comunale"],
                "topics": [
                    {
                          "uri": "https://www.comune.bugliano.pi.it/api/openapi/argomenti/18e6e1013c2999465c05b2ad41b364cf#Questioni-sociali",
                                "priority": 0
                                    }
                                      ],
                                        "abstract": "PIANO NAZIONALE DI RIPRESA E RESILIENZA (PNRR)",
                                          "file": {
                                              "filename": "dlg 00163 13 09 2023.pdf",
                                                  "url": "https://www.comune.bugliano.pi.it/web/trasparenza/papca-ap?..."
                                                    },
                                                      "attachments": [
                                                          {
                                                                "filename": "Delibera di Giunta n. 00163/2023",
                                                                      "file": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQgMCBvYmoKPDwgL0xlbmd..."
                                                                          }
                                                                            ],
                                                                              "has_organization": [
                                                                                  {
                                                                                        "uri": "https://www.comune.bugliano.pi.it/api/openapi/amministrazione/uffici/settore_edilizia_privata#Settore-edilizia-privata",
                                                                                              "priority": 0
                                                                                                  }
                                                                                                    ],
                                                                                                      "license": ["Creative Commons Attribution 4.0 International (CC BY 4.0)"],
                                                                                                        "format": ["PDF"],
                                                                                                          "start_time": "2023-09-25",
                                                                                                            "end_time": "2023-10-10",
                                                                                                              "publication_start_time": "2023-09-25",
                                                                                                                "publication_end_time": "2023-10-10",
                                                                                                                  "expiration_time": "2023-10-10",
                                                                                                                    "data_di_firma": "2023-09-13",
                                                                                                                      "keyword": "pnrr, INVESTIMENTO 1.1.2",
                                                                                                                        "author": []
                                                                                                                        }
Riguardo al corpo della chiamata: * Il valore dell'identificativo `id` è una stringa definita dall'utente o generata automaticamente. * Le relazioni tra contenuti sono espresse come link tra risorse API, ad esempio `topics` e `has_organization`. * Il documento principale si indica nel campo `file`. * Gli eventuali allegati si indicano invece nel campo `attachments`, con le stesse modalità (URL esterno o base64). * I valori dei vocabolari corrispondono a quelli visibili nell'editor del sito. Lo stesso approccio vale per tutte le entità previste dall'architettura. Nel definire la procedura di pubblicazione occorre fornire payload consistenti con la definizione delle entità: per le entità più complesse va tenuto conto dei collegamenti con le altre entità di base. {% endtab %} {% endtabs %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.opencityitalia.it/sito-web/moduli-integrativi-della-piattaforma/utilizzare-le-api-del-sito/effettuare-una-chiamata-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.