API : Site web d'offres et planificateur de cours personnalisés
Vous pouvez présenter des offres sur votre propre site web ou dans un planificateur de cours externe et effectuer la réservation effective dans edoobox. Ce guide décrit une synchronisation côté serveur avec des pages de détail propres, des textes repris de manière ciblée et une mémoire tampon locale.
Séparer la présentation, la synchronisation et la réservation
Le serveur du site lit les données d’offres autorisées via l’API et enregistre les champs nécessaires dans sa propre base de données. Le site public utilise cet ensemble préparé. Le bouton d’inscription ouvre le parcours de réservation fourni par edoobox. La vérification définitive de la possibilité de réserver, du prix, de la capacité et des conditions reste effectuée dans le processus de réservation edoobox.
Pour intégrer une offre prête à l’emploi, utilisez le plugin WordPress ou Aperçu/Share et iFrame. Un site personnalisé utilisant l’API nécessite un développement propre pour le stockage des données, les actualisations, la navigation et le SEO. Les modèles déjà rendus fournissent du HTML ; leur format de sortie diffère des données brutes utilisées ici.
Préparer l'accès et la portée de publication
- Créez une clé API propre et limitez-la aux droits de lecture nécessaires, par exemple pour les offres, les textes et, le cas échéant, les rendez-vous, les lieux ou les prix.
- Configurez l’authentification côté serveur avec l’hôte, le jeton et l’
edidcorrects. - Déterminez quelles offres et quelles langues doivent être visibles sur le site web. Un droit de lecture administratif API ne constitue pas une approbation publique automatique de tous les contenus lus.
- Enregistrez l'identifiant d'offre edoobox comme association inchangée à votre propre page web.
- Définissez une fréquence de mise à jour ainsi qu'un comportement pour les données manquantes ou obsolètes.
N’intégrez pas les offres internes et leurs codes d’accès à des données publiques sans vérification. Reprenez uniquement les champs explicitement autorisés ; ne transmettez pas les identifiants API au navigateur du site.
Lire les données d'offres de manière complète et liée à la langue
Utilisez GET /v2/offer/list et sélectionnez les champs nécessaires. Vous pouvez partir de id, number, name, status, date_start, date_end, archive, trash, shortdescription et image. Définissez explicitement language sur une langue utilisée, par exemple de. La référence de l’API v2 décrit chaque ressource.
Lisez toutes les pages avec limit.start, limit.reply et les données de réponse. Le guide Récupérer les listes intégralement explique la structure. Conservez les mêmes filtres et un ordre de tri non ambigu pendant toute l’exécution.
shortdescription est une description courte dérivée. Ce n’est ni un texte supplémentaire librement nommé, ni un remplacement de la description HTML complète. Pour une version courte rédigée spécifiquement, utilisez un texte supplémentaire convenu.
Lire la description et les textes supplémentaires propres via la ressource de texte
Les textes constituent des enregistrements distincts. GET /v2/text/list prend en charge les champs id, resource, resource_id, language et value. Filtrez conjointement le type de texte, l’ID de l’offre et la langue :
| Contenu souhaité | Valeur pour resource |
|---|---|
| Description complète | description |
| Texte supplémentaire 1 | additionaltext1 |
| Texte supplémentaire 2 | additionaltext2 |
| Texte supplémentaire 3 | additionaltext3 |
// offerId est repris sans modification de la réponse de l’offre.
const url = new URL('https://app2.edoobox.com/v2/text/list');
url.searchParams.set('fields', JSON.stringify([
'id', 'resource', 'resource_id', 'language', 'value'
]));
url.searchParams.set('filter', JSON.stringify([
{ property: 'resource', expression: '=', value: 'additionaltext1' },
{ property: 'resource_id', expression: '=', value: offerId },
{ property: 'language', expression: '=', value: 'de' }
]));
url.searchParams.set('response_type', 'array');
// Récupérer côté serveur avec les mêmes en-têtes edid et Authorization.L’entrée correspondante contient son texte dans value. Un résultat vide doit être traité comme une version de texte manquante ; l’intégration doit choisir un texte de remplacement ou masquer le contenu. Un texte de catégorie constitue une entrée distincte associée à l’ID de la catégorie. Ce filtre d’offre ne le charge pas automatiquement.
Convenez par exemple de ce qui suit : le texte supplémentaire 1 contient le résumé éditorial du planificateur de cours externe, tandis que la description reste l'information de cours détaillée. Vérifiez à l'avance les autres utilisations des textes supplémentaires dans les e-mails et les PDF. Une modification y a également un effet si le même texte est émis. Les contenus HTML doivent être traités de manière appropriée et sécurisée dans le système cible ; un texte HTML n'est pas automatiquement du texte en clair.
Prendre en charge les liens de réservation actuels
Lisez pour l'offre GET /v2/offer/{id}/shareurl. La réponse contient sous data.shareurl.url.booknow le lien de réservation directe prévu et sous data.shareurl.url.segment les chemins d'offre liés à la langue. Utilisez les valeurs réellement livrées. La sélection dans le dialogue d'aperçu/partage est également utile si vous avez besoin d'un lien public complet de langue, de catégorie ou d'intégration.
Associez durablement votre page de détail à l’ID de l’offre et actualisez les URL fournies par edoobox lors de la synchronisation. Les noms, les chemins des catégories et la langue peuvent changer ; un lien edoobox assemblé à partir du nom visible de l’offre ne constitue pas un remplacement fiable. N’utilisez pas non plus une session personnelle de réservation ou un lien d’accès participant pour un bouton général d’inscription.
Pour une sous-offre d'une offre multiple, le processus de partage fournit le chemin de réservation de l'offre multiple parent. Vérifiez donc la sélection réelle dans le processus cible. Les codes internes d'une réponse de partage ne doivent arriver que dans les distributeurs protégés prévus.
Vérifier les URL d'image, les variantes et les proportions d'origine
Le champ d'offre image peut être false. Pour une image assignée, il contient entre autres name, type, url et url300. Utilisez les URL renvoyées sans modification. image.url ne possède pas d'engagement général pour une taille de pixels fixe ou pour le fichier d'origine inchangé.
edoobox traite les images différemment selon la voie de téléversement et le type d'image stocké. Les images d'aperçu existantes peuvent être recadrées sur des rapports d'aspect fixes ; d'autres voies d'image utilisent le fichier de départ public ou leurs propres variantes de taille. Un fichier téléversé en format vertical ne signifie donc pas que chaque vue d'offre ou URL API livre le format vertical.
| Sortie | Ce que vous pouvez utiliser |
|---|---|
| Réponse d'offre REST | Les image.url et image.url300 réellement livrés. Un champ général image.original, url600 ou url900 n'est pas émis ici. |
| En-têtes WordPress | Le plugin utilise les variantes d'image fournies par le modèle pour sa sortie OpenGraph. Ces en-têtes sont un contexte de sortie distinct. |
| Image d'aperçu des réseaux sociaux | Extraits générés indépendamment pour l'aperçu du lien. Ils ne sont pas une interface d'image d'origine pour votre front-end. |
Un suffixe ajouté manuellement comme _900 ne fonctionne pas pour tous les types d’images et tous les emplacements de stockage. N’en faites pas une règle générale pour récupérer les images. Vérifiez le fichier réellement fourni, sa résolution et ses proportions sur plusieurs offres et après un changement d’image.
Si votre propre planificateur de cours exige un original non recadré ou une grande résolution spécifique, gérez cette image web avec une association fixe à l'identifiant d'offre dans votre CMS ou clarifiez la récupération de fichier appropriée pour votre connexion concrète. Le redimensionnement d'une petite image d'aperçu ne crée pas de détails d'image supplémentaires.
Mettre à jour le cache propre et traiter les pannes
- Chargez les offres, textes et liens de réservation prévus dans une nouvelle version préparée. Vérifiez chaque réponse API pour les erreurs HTTP et fonctionnelles.
- N'adoptez la nouvelle version complète que lorsque toutes les pages nécessaires et les données obligatoires ont été lues avec succès.
- Enregistrez le moment de la dernière synchronisation réussie et l'association par identifiant d'offre.
- En cas d'erreur, conservez la dernière version vérifiée, marquez la perturbation en interne et répétez la récupération de manière contrôlée. Une erreur ne doit pas remplacer le stock par un résultat apparemment vide.
- Déterminez à partir de quel âge des données les prix, les places libres ou les boutons d'inscription ne sont plus affichés sans vérification. Le processus de réservation edoobox reste déterminant pour la conclusion réelle.
Un intervalle de 15 minutes est une décision de votre intégration. Il ne crée pas de réservation dans edoobox et ne garantit pas des places inchangées jusqu'à la prochaine exécution. Adaptez les offres terminées, archivées ou non plus publiées dans votre stock de manière appropriée. Supprimez un enregistrement seulement après une synchronisation entièrement vérifiée et non à cause d'une page échouée.
Avec Webhooks, vous pouvez utiliser les modifications appropriées comme occasion pour un rechargement ciblé. Maintenez la synchronisation régulière. Pour les réservations reprises, API : Synchroniser les réservations explique l'état de traitement propre et les annulations ultérieures.
Exemple : Planificateur de cours externe avec résumé propre
Une organisation entretient des informations de cours complètes dans edoobox et une introduction éditoriale courte dans le texte supplémentaire 1. Votre back-end de site web lit les offres et la version de texte allemande, les stocke par identifiant d'offre et présente des pages propres sous https://example.org/kurse/…. Le bouton d'inscription utilise le lien de réservation edoobox chargé avec succès le plus récemment.
Lorsqu’un texte change, la prochaine exécution complète reprend la nouvelle version courte. En cas de panne de l’API, le dernier contenu vérifié est conservé ; les disponibilités obsolètes sont traitées selon la règle convenue pour le site. Après un déplacement vers une autre catégorie, le lien actuel est récupéré à nouveau dans edoobox. Le site ne génère aucune confirmation de réservation définitive à partir du cache.
Vérifier avant la publication et en cas d'erreurs
- Comparer une offre avec un texte complet, une sans texte supplémentaire et une offre multilingue.
- Prendre en compte plus d'une page de liste, une offre supprimée ou archivée et une page API échouée.
- Vérifier les images en format vertical, horizontal et remplacées dans la résolution réellement utilisée.
- Vérifier séparément le lien de réservation public, l'offre multiple et une zone protégée.
- Gérer le titre, la description et l'URL canonique de votre propre site web dans votre propre CMS ; distinguer OpenGraph et Canonical.
- Pour l'exploitation, journaliser le moment, l'identifiant d'offre et la catégorie d'erreur ; omettre les identifiants de connexion et les données personnelles inutiles.