Questa pagina descrive l'API accessibile esternamente per ePublikation. L'API consente l'interazione programmata per la pubblicazione di comunicati nei bollettini ufficiali. Questa API RESTful è stata sviluppata secondo la specifica OpenAPI per un'integrazione fluida da parte di terzi e dispone di una documentazione interattiva fornita tramite Swagger UI.
Il tutorial "Primi passi" è progettato in modo da non richiedere conoscenze approfondite dei concetti dietro ePublikation né competenze di programmazione avanzate. Tuttavia, è consigliabile acquisire prima una panoramica del concetto e delle funzionalità della piattaforma per poter successivamente implementare i vari tipi di comunicati.
Il frontend dell'applicazione è accessibile all'indirizzo https://preview.epublication.ch.
In questa guida vi accompagneremo attraverso le basi dell'utilizzo dell'API di ePublikation. Ci sono diversi modi per familiarizzare con l'API.
- Il metodo più semplice: provare l'API con Swagger
- Inviare una richiesta tramite cURL nel CLI
- Utilizzare la raccolta predefinita Bruno fornita in questo repository
Swagger
Swagger è un set di strumenti open-source basato sulla specifica OpenAPI che aiuta gli sviluppatori a progettare, creare, documentare e utilizzare servizi web RESTful. Se volete fare qualche esperimento e familiarizzare con l'API, non è necessario installare software locale. Basta accedere ai punti di accesso pubblici di Swagger.
Recuperare comunicati pubblicati
Il recupero dei comunicati pubblicati avviene passo dopo passo come segue:
1. Per la richiesta dei comunicati pubblicati non è necessaria l'autenticazione (lo screenshot sottostante mostra tutti i punti di accesso che non richiedono autenticazione).
2. Attraverso il punto di accesso "../announcements" è possibile recuperare i comunicati in una lista. La lista contiene solo i metadati, come il titolo del comunicato e il numero di pubblicazione. Il codice di esempio seguente illustra le possibilità di filtro. Utilizzando i criteri di filtro indicati, vengono restituiti solo i comunicati pubblicati nella "Gazzetta A" che contengono il termine "Sample". Cliccate su "Try it out".
Inserite il codice seguente nel campo "Request Body".
{
"filter": {
"gazette": "GZA",
"term": "Sample"
},
"page": 0,
"pageSize": 20,
"sort": {
"field": "businessId",
"direction": "ASC"
}
}Cliccate su "Execute".
Se la richiesta ha successo (stato HTTP 200), la lista viene restituita in formato JSON.
3. Il valore di "publicationNumber" viene quindi utilizzato per recuperare i dati dettagliati di un comunicato. Per questo si utilizza il punto di accesso "../announcement/{publicationNumber}". Copiate il valore di "publicationNumber" nel campo "publication-number".
Questa procedura illustra come dovrebbe essere implementato essenzialmente il recupero dei dati.
Inviare un comunicato
Il punto di accesso per l'invio di comunicati potrebbe essere di particolare interesse. Procediamo passo dopo passo. Per alcune richieste (invio di comunicati, recupero di comunicati non pubblicati) è richiesta l'autenticazione. Vi preghiamo di contattarci per un accesso demo. Con le credenziali fornite potrete utilizzare i seguenti punti di accesso limitati.
1. Effettuate il login con le credenziali fornite.
2. Aprite il punto di accesso "../submission" e cliccate su "Try it out".
3. Ora vedrete un campo modificabile con sfondo bianco. Eliminate il codice presente nel campo.
4. Inserite il codice indicato di seguito nel campo.
Importante: il valore di "publicationDateTime" deve essere nel futuro e cadere in un giorno feriale.
{
"publishingEntity": "PEA",
"organizationUnit": "PEA-OE01",
"gazette": "GZA",
"announcementType": "000",
"publicationPeriod": 35,
"languages": [
"DE"
],
"primaryLanguage": "DE",
"secondaryGazettes": [
"GZB"
],
"primaryTopic": "debtEnforcementBankruptcy",
"allowedTopics": [
"debtEnforcementBankruptcy"
],
"primaryAffectedCanton": "ZH",
"affectedCantons": [
"ZH"
],
"primaryAffectedMunicipality": "Hausen am Albis",
"affectedMunicipalities": [
"Hausen am Albis"
],
"businessCase": "documentA",
"content": [
{
"language": "DE",
"elements": [
{
"key": "name",
"label": "Titolo del comunicato",
"type": "stringMultiLang",
"value": [
"Some Sample Title"
]
},
{
"key": "notice",
"label": "Contenuto",
"type": "textarea",
"value": [
"Some Sample Content: Lorem Ipsum è semplicemente un testo segnaposto dell'industria della stampa e della composizione tipografica. Lorem Ipsum è stato il testo segnaposto standard del settore sin dal 1500, quando un tipografo sconosciuto prese una composizione di caratteri e la mescolò per creare un libro di esempi di caratteri.<br /><br /><ul><li>Ha resistito non solo per cinque secoli</li><li>ma anche al salto nella composizione elettronica</li></ul>Rimanendo sostanzialmente invariato. È stato reso popolare negli anni '60 con il rilascio di fogli Letraset contenenti passaggi di Lorem Ipsum, e più recentemente con software di desktop publishing come Aldus PageMaker che include versioni di Lorem Ipsum."
]
}
]
}
],
"publicationDateTime": "2026-04-02",
"status": "PUBLISHED"
}
5. Dovreste quindi ricevere una risposta HTTP 201. Questo significa che il comunicato è stato importato con successo.
6. Il comunicato è ora pubblicato. Potete visualizzarlo nel frontend dell'applicazione all'indirizzo https://preview.epublication.ch.
CLI
Un altro modo semplice per stabilire una prima connessione è utilizzare il seguente comando cURL semplice. Anche in questo caso non è richiesta l'autenticazione per visualizzare una lista dei comunicati pubblicati. Aprite semplicemente un prompt dei comandi (ad esempio "cmd" sul vostro computer Windows) e incollate il seguente comando cURL. Come risultato dovreste ottenere una lista in formato JSON degli ultimi 20 comunicati pubblicati su ePublikation.ch.
curl -X "POST" "https://preview.epublication.ch/api/management/public/interface/v1/announcements" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"page\": 0, \"pageSize\": 20}"
Bruno
Bruno è un client API open-source, utilizzato qui come alternativa gratuita a strumenti come Postman e Insomnia. Bruno salva le vostre raccolte utilizzando un semplice linguaggio di markup testuale direttamente in una cartella del vostro file system.
Scaricate Bruno: https://www.usebruno.com
Importate la collezione fornita qui. Ulteriori informazioni sull'uso si trovano nella scheda "Docs" all'interno della collezione.
Collezione di esempio
Alla collezione Bruno sono stati aggiunti nuovi import di comunicati per i seguenti tipi di comunicati:
- Comunicato ufficiale generale
- Singolo progetto edilizio
- Comunicazione al registro notarile
- Iscrizione nel registro commerciale
- Apertura di una procedura fallimentare
- Invito a far valere diritti a seguito di una modifica organizzativa
Quali sono i prossimi passi?
Il MVP verrà ora migliorato continuamente. Nuove informazioni e guide passo-passo saranno pubblicate qui regolarmente. I prossimi argomenti saranno:
- Schemi dei principali tipi di comunicati
- Catalogo delle chiavi/termini possibili
- Catalogo dei casi d'uso possibili