Cette page décrit l’API accessible de l’extérieur pour ePublication. L’API permet une interaction programmée pour publier des annonces dans les bulletins officiels. Cette API RESTful a été développée selon la spécification OpenAPI pour une intégration fluide par des tiers et dispose d’une documentation interactive fournie via Swagger UI.
Le tutoriel « Premiers pas » est conçu de façon à ne nécessiter ni connaissances approfondies des concepts derrière ePublication ni compétences de programmation avancées. Il est toutefois conseillé de se familiariser d’abord avec le concept et les fonctionnalités de la plateforme afin de pouvoir ensuite implémenter les différents types d’annonces.
Le frontend de l’application est accessible à https://preview.epublication.ch.
Ce guide vous accompagne à travers les bases de l’utilisation de l’API ePublication. Il existe plusieurs façons de se familiariser avec l’API.
- La méthode la plus simple : tester l’API avec Swagger
- Envoyer une requête via cURL dans le CLI
- Utiliser la collection Bruno prédéfinie, fournie dans ce dépôt
Swagger
Swagger est un ensemble d’outils open source basé sur la spécification OpenAPI qui aide les développeurs à concevoir, créer, documenter et utiliser des services web RESTful. Si vous souhaitez expérimenter un peu et vous familiariser avec l’API, vous n’avez pas besoin d’installer un logiciel localement. Il suffit d’accéder aux points de terminaison Swagger publics.
Récupérer les annonces publiées
La récupération des annonces publiées se fait étape par étape comme suit :
1. Aucune authentification n’est nécessaire pour la requête des annonces publiées (la capture d’écran ci-dessous montre tous les points de terminaison qui ne nécessitent pas d’authentification).
2. Par le point de terminaison "../announcements", les annonces peuvent être récupérées sous forme de liste. La liste contient uniquement les métadonnées, telles que le titre de l’annonce et le numéro de publication. Le code d’exemple suivant illustre les possibilités de filtrage. En utilisant les critères de filtre indiqués, seules les annonces publiées dans la « Gazette A » et contenant le terme « Sample » sont retournées. Cliquez sur « Try it out ».
Insérez le code ci-dessous dans le champ « Request Body ».
{
"filter": {
"gazette": "GZA",
"term": "Sample"
},
"page": 0,
"pageSize": 20,
"sort": {
"field": "businessId",
"direction": "ASC"
}
}Cliquez sur « Execute ».
Si la requête réussit (statut HTTP 200), la liste est renvoyée au format JSON.
3. La valeur de « publicationNumber » est ensuite utilisée pour récupérer les données détaillées d’une annonce. Pour cela, on utilise le point de terminaison "../announcement/{publicationNumber}". Copiez la valeur de « publicationNumber » dans le champ « publication-number ».
Cette procédure illustre comment la récupération des données doit essentiellement être effectuée.
Soumettre une annonce
Le point de terminaison pour soumettre des annonces est particulièrement intéressant. Passons-le en revue étape par étape. Certaines requêtes (soumission d’annonces, récupération d’annonces non publiées) nécessitent une authentification. Veuillez nous contacter pour obtenir un accès de démonstration. Avec les identifiants fournis, vous pourrez utiliser les points de terminaison restreints suivants.
1. Connectez-vous avec les identifiants fournis.
2. Ouvrez le point de terminaison "../submission" et cliquez sur « Try it out ».
3. Vous voyez maintenant un champ éditable avec un fond blanc. Supprimez le code dans ce champ.
4. Collez le code indiqué ci-dessous dans le champ.
Important : la valeur de « publicationDateTime » doit être dans le futur et tomber un jour de semaine.
{
"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": "Titre de l’annonce",
"type": "stringMultiLang",
"value": [
"Some Sample Title"
]
},
{
"key": "notice",
"label": "Contenu",
"type": "textarea",
"value": [
"Some Sample Content: Lorem Ipsum est simplement un faux texte de l’imprimerie et de la composition. Lorem Ipsum est le faux texte standard de l’industrie depuis les années 1500, quand un imprimeur inconnu a pris une galère de caractères et les a mélangés pour faire un livre d’échantillons de caractères.<br /><br /><ul><li>Il a survécu non seulement à cinq siècles</li><li>mais aussi au passage à la composition électronique</li></ul>Restant essentiellement inchangé. Il a été popularisé dans les années 1960 avec la sortie des feuilles Letraset contenant des passages de Lorem Ipsum, et plus récemment avec des logiciels de publication assistée par ordinateur comme Aldus PageMaker incluant des versions de Lorem Ipsum."
]
}
]
}
],
"publicationDateTime": "2026-04-02",
"status": "PUBLISHED"
}
5. Vous devriez alors recevoir une réponse HTTP 201. Cela signifie que l’annonce a été importée avec succès.
6. L’annonce est maintenant publiée. Vous pouvez consulter l’annonce dans l’interface frontend de l’application à https://preview.epublication.ch.
CLI
Une autre façon simple d’établir une première connexion est d’utiliser la commande cURL simple suivante. Là aussi, aucune authentification n’est nécessaire pour afficher une liste des annonces publiées. Ouvrez simplement une invite de commandes (par exemple « cmd » sur votre ordinateur Windows) et collez la commande cURL suivante. Vous devriez obtenir en résultat une liste au format JSON des 20 dernières annonces publiées sur ePublication.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 est un client API open source, utilisé ici comme alternative libre à des outils comme Postman et Insomnia. Bruno stocke vos collections à l’aide d’un langage de balisage texte simple directement dans un dossier de votre système de fichiers.
Téléchargez Bruno : https://www.usebruno.com
Importez la collection fournie ici. Pour plus d’informations sur l’utilisation, consultez l’onglet « Docs » dans la collection.
Collection modèle
De nouvelles importations d’annonces ont été ajoutées à la collection Bruno pour les types d’annonces suivants :
- Annonce officielle générale
- Projet de construction individuel
- Notification au registre notarial
- Inscription au registre du commerce
- Ouverture d’une procédure d’insolvabilité
- Invitation à faire valoir des créances en raison d’un changement organisationnel
Et ensuite ?
Le MVP sera désormais continuellement amélioré. De nouvelles informations et des guides pas à pas seront publiés ici régulièrement. Les prochaines étapes sont :
- Schémas des principaux types d’annonces
- Catalogue des clés/termes possibles
- Catalogue des cas d’affaires possibles