Référence de l’API publique Hubigo

Cette API expose, principalement en lecture, ce qui est déjà visible sur le portail citoyen de votre ville : avis, activités, plateaux, types de demande, consultations. Elle ajoute quelques opérations B2B (vérification d’abonnement, suivi de demande, lookup cadastral) et le pont d’écriture des Organismes. Le contrat complet (schémas et exemples) est publié en OpenAPI sur le portail développeur.

Introduction

Toutes les requêtes se font en HTTPS ; les réponses sont en JSON encodé UTF-8. Chaque installation Hubigo expose sa propre API sur un domaine Hubigo. Une instance dédiée reçoit un domaine API équivalent, communiqué à la livraison.

URL de base
https://api-core.hubigo.ca

Démarrage rapide

Créez une clé dans Administration → Paramètres → API, puis appelez un endpoint avec l’en-tête X-API-Key.

# Avis publics actifs
GET https://api-core.hubigo.ca/public-api-notices?status=active&limit=50
X-API-Key: hbg_…

# Réponse (extrait)
{ "data": [ { "id": "…", "title": "Avis d’ébullition, secteur nord", "status": "active" } ] }

Authentification

Une clé API par appel, dans l’en-tête X-API-Key. Deux types de clés :

Les clés se créent et se révoquent dans Administration → Paramètres → API. Les endpoints marqués public acceptent une clé optionnelle (recommandée pour le quota et l’audit) ; les endpoints B2B et PII l’exigent.

X-API-Key: hbg_xxxxxxxxxxxxxxxxxxxx

Signature HMAC (optionnelle)

Si un secret de signature est configuré sur votre clé, signez chaque requête avec l’en-tête X-Hubigo-Signature.

X-Hubigo-Signature: t=<unix>,v1=<hex>
# v1 = HMAC-SHA256(secret, "<t>.<corps_brut>")
# fenêtre de validité : 5 minutes

Conventions et formats

Chemins et paramètres en anglais (status, limit, format). Certaines ressources géographiques renvoient du GeoJSON via ?format=geojson ; les loisirs exposent un flux iCal. La lecture est la règle : les seules écritures documentées appartiennent à la famille Organismes.

Sensibilité et sécurité

Chaque endpoint porte un niveau de sensibilité, indiqué dans le contrat OpenAPI :

Pas d’export de citoyens, pas de notes internes, pas de secrets. Tous les appels sont journalisés ; des quotas s’appliquent à certaines familles (avis, facturation).

Erreurs

{
  "error": {
    "code": "platform_key_required",
    "message": "Cette famille exige une clé plateforme."
  }
}

Limites de débit

Appliquées par clé. Un dépassement renvoie 429 avec Retry-After : prévoyez un recul exponentiel. Les familles Avis et Facturation ont des quotas plus stricts.

Communications

Avis publics, messages, catégories d’alerte, niveaux d’urgence et zones affectées.

Services aux citoyens

Catalogue des types de demande, référentiels de formulaire, statistiques agrégées et suivi d’une demande par jeton.

Loisirs

Catalogue d’activités, camps de jour, événements et plateaux réservables, plus un flux iCal public.

Organismes

La seule famille en écriture : synchronisation des organismes et de leurs réservations de plateaux avec vos systèmes.

Participation

Consultations publiques et résultats agrégés, lorsque la ville les publie.

Abonnements

Vérification de l’accès d’un citoyen à un service (éco-centre, bibliothèque, borne). Endpoints à données personnelles : clé requise.

Administration ville

Socle partagé : métadonnées de la ville, zones, lieux, sondes de disponibilité, pages légales et lookup cadastral.

Facturation plateforme

Usage, limites et alertes agrégés sur l’ensemble des villes. Réservé aux clés plateforme Hubigo (hbg_pk_…).

Surface complète, paramètres, schémas JSON et exemples exécutables : contrat OpenAPI sur le portail développeur.