Documentation API MessesInfo – Ajout d’horaires

10 juillet 2025
by CEF
Comments are off

Vue d’ensemble

L’API MessesInfo permet désormais de créer, modifier et supprimer des horaires de messe via des endpoints REST. Ces fonctionnalités sont disponibles en environnement de production depuis le second trimestre 2025.

URL de base en test : https://test.messes.info/api/v2/
Documentation interactive (test) : https://test.messes.info/api-docs/

Authentification

Toutes les requêtes nécessitent une clé API (userkey) passée en paramètre d’URL :

?userkey=VOTRE_CLE

Droits et permissions

  • Une clé API possède des droits sur un ou plusieurs réseaux (diocèses) et/ou communautés (paroisses)
  • Les clés sont au format : KEY-XXXXXXX

Concepts clés

Identifiants

  • CelebrationInfo ID : Identifiant d’un groupe d’horaires
  • CelebrationTime ID : Identifiant unique d’un horaire individuel
  • LocalityId : Identifiant du lieu (ex: 75/paris-07/conference-des-eveques-de-france)
  • LocalityIdfixe : Identifiant alternatif du lieu (ex: 75107_12)

Endpoints principaux

1. /horaireinfo – Gestion par groupe d’horaires

Base URL : https://test.messes.info/api/v2/horaireinfo

POST – Créer un horaire

Endpoint : POST /horaireinfo

Corps de la requête (minimum requis) :

{
  "date": "2024-09-16",
  "time": "16h40",
  "localityId": "75/paris-07/conference-des-eveques-de-france",
  "timeType": "WEEKMASS"
}

Exemple avec curl :

curl --request POST \
  --url 'https://test.messes.info/api/v2/horaireinfo?userkey=KEY&format=json' \
  --header 'Accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "date": "2024-09-16",
    "time": "16h40",
    "localityId": "75/paris-07/conference-des-eveques-de-france",
    "timeType": "WEEKMASS"
  }'

Réponse :

{
  "id": 6331467736023040,
  "networkId": "nl",
  "communityId": "nl/75/paroisse-conference-des-eveques-de-france",
  "localityId": "75/paris-07/conference-des-eveques-de-france",
  "timeType": "WEEKMASS",
  "date": "2024-09-16",
  "time": "16h40",
  "multipleLocalities": false,
  "recurrenceCategory": "UNIQUE",
  "active": true,
  "visitor": false,
  "isGenerated": true,
  "version": 1,
  "numberGenerated": 1,
  "numberRemaining": 1,
  "notification": "NONE",
  "source": "egliseinfo"
}
PATCH – Modifier un horaire

Endpoint : PATCH /horaireinfo/{celebrationInfoId}

Exemple :

curl --request PATCH \
  --url 'https://test.messes.info/api/v2/horaireinfo/6331467736023040?userkey=KEY&format=json' \
  --header 'Accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "date": "2024-09-16",
    "time": "16h50",
    "localityId": "75/paris-07/conference-des-eveques-de-france",
    "timeType": "WEEKMASS"
  }'
GET – Récupérer un groupe d’horaires

Endpoint : GET /horaireinfo/{celebrationInfoId}

GET – Récupérer les horaires d’un groupe

Endpoint : GET /horaireinfo/{id}/celebrationtime

DELETE – Supprimer un horaire

Endpoint : DELETE /horaireinfo/{celebrationInfoId}

⚠️ Statut : Non fonctionnel actuellement

2. /horaire – Gestion par horaire individuel

Base URL : https://test.messes.info/api/v2/horaire

Obtenir l’ID d’un horaire

Pour utiliser les endpoints /horaire, vous devez d’abord récupérer le CelebrationTime ID :

curl --request GET \
  --url 'https://test.messes.info/api/v2/horaires/16-09-2024%20Locality:75%2Fparis-07%2Fconference-des-eveques-de-france?userkey=KEY&format=json' \
  --header 'Accept: application/json'

Réponse (extrait) :

{
  "listCelebrationTime": [
    {
      "id": 21278594,
      "celebrationInfoId": 5187407891660800,
      "localityId": "75/paris-07/conference-des-eveques-de-france",
      "date": "2024-09-16",
      "time": "16h40",
      "timeType": "WEEKMASS"
    }
  ]
}
GET – Récupérer un horaire

Endpoint : GET /horaire/{celebrationTimeId}

GET – Récupérer les infos de groupe d’un horaire

Endpoint : GET /horaire/{id}/celebrationinfo

PATCH – Modifier un horaire par son ID

Endpoint : PATCH /horaire/{celebrationTimeId}

Exemple :

curl --request PATCH \
  --url 'https://test.messes.info/api/v2/horaire/21278594?userkey=KEY&format=json' \
  --header 'Accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "date": "2024-09-16",
    "time": "16h50",
    "localityId": "75/paris-07/conference-des-eveques-de-france",
    "timeType": "WEEKMASS"
  }'
DELETE – Supprimer un horaire par son ID

Endpoint : DELETE /horaire/{celebrationTimeId}

Exemple :

curl --request DELETE \
  --url 'https://test.messes.info/api/v2/horaire/21278595?userkey=KEY&format=json' \
  --header 'Accept: application/json'

Réponse : true

Format des données

Champs requis minimum

{
  "date": "YYYY-MM-DD",
  "time": "HHhMM",
  "localityId": "string",
  "timeType": "string"
}

Champs optionnels

  • localityIdfixe : Alternative à localityId

Valeurs possibles pour les champs

Voir page MessesInfo – Liste et imbrication des valeurs possibles pour la saisie d’un horaire

Notes importantes

  • Les champs vides doivent être laissés vides
  • Les champs marqués _libre_ permettent une saisie libre
  • Données obligatoires : Pour chaque ligne du tableau « MessesInfo – Liste et imbrication des valeurs possibles pour la saisie d’un horaire », toutes les cellules remplies correspondent à des données obligatoires.

Correspondance API / Base de données

Champ API Champ base de données
timeType timetype
celebrationTimeType celebrationtimetype
celebrationCategory celebrationcategory
celebration celebration
celebrationName celebrationname
type type
liturgyHoursType liturgyhourstype

Bonnes pratiques

Gestion des identifiants

  1. Pour créer/modifier : Utilisez /horaireinfo avec localityId
  2. Pour supprimer : Utilisez /horaire avec le CelebrationTime ID
  3. Stockage : Conservez les deux identifiants retournés pour les opérations futures

Gestion des erreurs

  • Vérifiez toujours les droits sur le diocèse/communauté
  • Validez le format des dates et heures
  • Testez d’abord sur l’environnement de test

Format des réponses

  • Toutes les réponses PATCH renvoient l’objet complet
  • Les réponses POST renvoient maintenant l’objet complet (amélioration récente)
  • Les réponses DELETE renvoient true en cas de succès

Améliorations prévues

  • Harmonisation des réponses entre tous les endpoints
  • Gestion complète des récurrences
  • Documentation mise à jour pour les nouveaux endpoints
  • Amélioration de la route GET lieux-par-communaute

Support

Pour toute question ou problème :

  • Consulter la documentation interactive
  • Tester d’abord sur l’environnement de test
  • Contacter l’équipe technique pour les évolutions nécessaires

Documentation basée sur les échanges avec l’équipe technique

About the Author