Paramètres d'affichage

Choisissez un thème pour personnaliser l'apparence du site.

Webhook

Recevez automatiquement les données de chaque nouveau ticket créé dans votre commune via un webhook.

Introduction

Les webhooks permettent à Contribcit d'envoyer des notifications en temps réel à votre serveur lorsqu'un nouveau ticket est créé. Cela vous permet d'intégrer les contributions citoyennes directement dans vos systèmes existants.

Configuration

Pour configurer un webhook, vous devez :

  1. Accéder à la page de configuration API dans votre tableau de bord
  2. Entrer l'URL HTTPS de votre endpoint qui recevra les notifications
  3. Copier le secret généré automatiquement
  4. Configurer votre endpoint pour vérifier le secret dans les headers

Format JSON envoyé

Chaque fois qu'un nouveau ticket est créé, une requête POST est envoyée à votre URL avec le payload suivant :

Chargement...

Headers envoyés

Chaque requête webhook inclut les headers suivants :

Chargement...

Le header X-Webhook-Secret contient le secret généré automatiquement. Vous devez vérifier ce secret dans votre endpoint pour authentifier les requêtes.

Authentification

Pour sécuriser votre endpoint, vous devez vérifier le secret dans le header X-Webhook-Secret. Si le secret ne correspond pas, vous devez retourner une erreur 401 Unauthorized.

Gestion des erreurs

Contribcit gère les erreurs de la manière suivante :

  • Timeout : Si votre endpoint ne répond pas dans les 5 secondes, la requête est annulée
  • Codes HTTP d'erreur : Les codes 4xx et 5xx sont considérés comme des erreurs
  • Logs : Toutes les tentatives sont enregistrées dans les logs de votre commune

Bonnes pratiques

  • Idempotence : Votre endpoint doit être idempotent. Utilisez le ticketNumber pour éviter les doublons
  • Réponse rapide : Répondez rapidement (dans les 5 secondes) pour éviter les timeouts
  • Validation : Validez toujours les données reçues avant de les traiter
  • Logging : Enregistrez les webhooks reçus pour le débogage
  • HTTPS : Utilisez toujours HTTPS pour votre endpoint webhook

Structure des données

Le payload contient les champs suivants :

  • event : Type d'événement (actuellement "contribution.created")
  • timestamp : Date et heure de l'événement au format ISO 8601
  • contribution : Objet contenant toutes les données du ticket
    • id : Identifiant unique de la contribution
    • ticketNumber : Numéro de ticket (ex: "CT-2024-001234")
    • type : Type de contribution ("ALERT" ou "SUGGESTION")
    • status : Statut du ticket ("OPEN", "IN_PROGRESS", "RESOLVED", etc.)
    • category : Catégorie du ticket (id et name)
    • title : Titre du signalement
    • details : Description détaillée
    • email : Email du contributeur (peut être null)
    • location : Localisation (label, latitude, longitude - peuvent être null)
    • photo : Photo associée (url et publicId - peuvent être null)
    • createdAt : Date de création au format ISO 8601
    • isPotentiallyMalicious : Indicateur de contenu potentiellement malveillant
  • commune : Informations sur la commune
    • id : Identifiant unique de la commune
    • name : Nom de la commune
    • postalCode : Code postal

API GraphQL

Accédez à toutes les données de votre commune via une API GraphQL moderne et flexible. Cette fonctionnalité est réservée aux communes premium.

Introduction

L'API GraphQL de Contribcit vous permet d'interroger vos données de manière flexible et efficace. Contrairement aux API REST traditionnelles, GraphQL vous permet de récupérer exactement les données dont vous avez besoin en une seule requête.

Accès premium requis

L'API GraphQL est uniquement disponible pour les communes ayant un accès premium. Contactez-nous pour activer cette fonctionnalité.

Authentification

Pour vous authentifier, vous devez inclure votre clé API dans les headers de chaque requête. Cette clé est la même que celle utilisée pour les webhooks (webhookSecret).

Vous pouvez l'envoyer de deux manières :

  • Header X-API-Key : X-API-Key: votre-webhook-secret
  • Authorization Bearer : Authorization: Bearer votre-webhook-secret

Endpoint

L'endpoint GraphQL est disponible à l'adresse suivante :

Chargement...

Sandbox de test

Vous pouvez tester l'API GraphQL directement dans votre navigateur grâce à notre sandbox Apollo intégrée :

Ouvrir la sandbox GraphQL

Exemples de requêtes

Sélectionnez un langage pour voir un exemple d'implémentation :

Chargement...

Queries disponibles

  • commune : Récupère les informations de votre commune
  • contribution(id) : Récupère une contribution spécifique par son ID
  • contributions(filter, pagination) : Liste paginée des contributions avec filtres optionnels
  • stats(startDate, endDate) : Statistiques agrégées sur les contributions
  • categories : Liste des catégories actives

Filtres et pagination

La query contributions accepte des filtres et une pagination :

  • Filtres : status (OPEN/CLOSED), type (ALERT/SUGGESTION), categoryId, startDate, endDate
  • Pagination : Utilisez first et after pour paginer vers l'avant, ou last et before pour paginer vers l'arrière

Exemple avec filtres

Chargement...

Sécurité

L'API GraphQL est en lecture seule. Vous ne pouvez accéder qu'aux données de votre propre commune. Toutes les requêtes sont automatiquement filtrées par votre communeId pour garantir l'isolation des données.

Limites

  • La pagination est limitée à 100 éléments par page
  • Par défaut, 20 éléments sont retournés si aucune limite n'est spécifiée
  • L'API est en lecture seule (pas de mutations)

Services tiers

Bientôt disponible

Des intégrations avec des services tiers (Slack, Microsoft Teams, etc.) seront bientôt disponibles pour recevoir les notifications de contributions directement dans vos outils de communication.

Contribcit