Documentation technique

Les formats

Maintenez vos développements à jour et profitez plus rapidement des nouveautés en vous assurant d’utiliser la dernière version des formats et des services.

Changements de noms de champs

Globalement, il a été décidé de faire disparaitre les références à la version précédente de Apidae dans les noms de champs et de paramètres.

Dans l’objet touristique au format JSON :

Le champ identifierSitra1 présent à la racine de l’objet et représentant anciennement l’identifier provenant de la version précédente, a été renommé identifier. Cet identifier provient soit de la version précédente de Apidae (quand l’objet existait déjà) soit est généré automatiquement à partir de l’identifiant pour les nouveaux objets.

Dans la requête d’API :

Champs ajoutés

  • Le champ formatVersion a été ajouté. Ce champ rappelle quelle version est utilisée : v001 ou v002.
  • Le champ descriptionTarif.periodes.devise a été ajouté. Ce champ indique quelle est la devise appliquée à une période tarifaire. Valeurs possible : EUR, CHF, GBP, USD.
  • Le champ aspects a été ajouté. Il contient les différents aspects définis sur l’objet. Voir les aspects.

Champs dépréciés

Suite à la mise en place d’évolution, des champs de la version 2 sont dépréciés et ne seront pas reconduits dans les nouvelles versions du format. Veillez à utiliser les bons champs.

Livraison prestataires (4 février 2015 – voir détail)

  • Remplacement de informationsActivite.commerceEtServicePrestataire (déprécié) par informationsActivite.prestataireActivites
  • Remplacement de informationsCommerceEtService.activitesCulturelles et informationsCommerceEtService.activitesSportives (dépréciés) par informationsPrestataireActivites.activitesCulturelles et informmationsPrestataireActivites.activitesSportives

Champs supprimés

Objet Touristique (tous types confondus)

  • Le champ imagePrincipale a été supprimé. L’information est désormais disponible dans le champ illustrations. Plus précisement, l’image principale est le premier élément du champ illustrations.
  • Le champ images a été supprimé. L’information est désormais disponible dans le champ illustrations.
  • Le champ imagePrincipaleHiver a été supprimé. L’information est désormais disponible dans le champ illustrations de l’aspect HIVER de l’objet. Plus précisement, l’image principale est le premier élément du champ illustrations.
  • Le champ imagesHiver a été supprimé. L’information est désormais disponible dans le champ illustrations de l’aspect HIVER de l’objet.
  • Le champ imagesHandicap a été supprimé. L’information est désormais disponible dans le champ illustrations de l’aspect HANDICAP de l’objet.
  • Le champ imagesTourismeAffaires a été supprimé. L’information est désormais disponible dans le champ illustrations de l’aspect TOURISME_AFFAIRES de l’objet.
  • Le champ liens.objetsLies, qui contenait la liste non typée des objets liés, a été supprimé. C’était un champ historique convervé dans la V1 pour des raisons de compatibilité. Cette information, enrichie avec le type de lien est disponible dans le champ liens.liensObjetsTouristiquesTypes.

> Voir documentation des aspects

Entité juridique

  • Le champ informationsStructure.structureType a été supprimé. C’était un champ historique conservé pour la compatibilité avec la version précédente. L’information est disponible dans le champ informationsStructure.entiteType.
  • Le champ informationsStructure.activitesCulturelles a été supprimé. Cette information a été migrée sur le/les commerces et services de l’entité juridique.
  • Le champ informationsStructure.activitesSportives a été supprimé. Cette information a été migrée sur le/les commerces et services de l’entité juridique.
  • Le champ informationsStructure.classement a été supprimé. Cette information a été migrée sur le/les commerces et services de l’entité juridique.
  • Le champ informationsStructure.habilitationsPrestataires a été supprimé. Cette information a été migrée sur le/les commerces et services de l’entité juridique.

Territoire

  • Le champ informationsTerritoire.descriptifCourtHiver a été supprimé. L’information est désormais disponible dans le champ presentation.descriptifCourt de l’aspect HIVER de l’objet. Voir documentation des aspects.
  • Le champ informationsTerritoire.descriptifDetailleHiver a été supprimé. L’information est désormais disponible dans le champ presentation.descriptifDetaille de l’aspect HIVER de l’objet. Voir documentation des aspects.

Activité

Le champ informationsActiviteSection.frequence a été supprimé. L’information est disponible dans le champ informationsActiviteSection.nombreJours.

Moyen de communication

Le champ coordonnee d’un moyen de communication (MoyenCommunication.schema dans les schémas JSON) a été supprimé. La coordonnée d’un moyen de communication étant devenue un champ traduisible, cette information correspond au contenu du champ coordonnees.fr d’un moyen de communication.

Elément de référence

Le champ code a été supprimé. Ce champ était un reliquat de la codification TIF issue de la version précédente de Apidae.

Introduction des aspects

La V2 introduit dans les API et dans les exports la notion aspect. Les aspects permettent de définir du contenu spécifique sur un objet, en surchargeant certains champs. Les différents aspects disponibles sont :

HIVER : pour les informations de l’objet à exploiter en hiver,
ETE : pour les informations de l’objet à exploiter en été,
HANDICAP : pour les informations relatives au tourisme pour les personnes handicapées,
TOURISME_AFFAIRES : pour les informations relatives au tourisme d’affaires.
GROUPES : pour les informations relatives aux groupes de personnes.

Un objet peut seulement implémenter 1 aspect de chaque type.

Attention, les aspects ne sont pas des objets complets qui se substituent à l’objet dit « STANDARD ». Les aspects permettent simplement de surcharger certains champs de l’objet standard afin de définir du contenu qui aura du sens, et qui peut être exploité dans certaines circonstances. Il n’y a aucun automatisme concernant l’exploitation du contenu des aspect et leur exploitation nécessite une spécification avec votre client (utilisation systématique, utilisation conditionnelle, …).

> Documentation des aspects

Elargissement de la notion de prestataire

(livraison le 4 février 2015)

Champ informationsActivite.commerceEtServicePrestataire -> informationsActivite.prestataireActivites

Jusqu’à maintenant, il était possible de lier des activités uniquement avec une partie des commerces et services (type COMMERCE_ET_SERVICE). Cette information était disponible dans le champ informationsActivite.commerceEtServicePrestataire.

Suite à cette mise à jour, nous conservons à des fins de compatibilité ce champ qui référence le potentiel commerce prestataire.

Un nouveau champ apparait, appelé informationsActivite.prestataireActivites qui peut pointer vers un objet de n’importe quel type.
Pour tout nouveau développement, ou si vous désirez pouvoir afficher les prestataires d’un type autre que COMMERCE_ET_SERVICE, il vous faut
utiliser ce champ.

Champs informationsPrestatairesActivite.*

Les champs informationsCommerceEtService.activites{Sportives,Culturelles} sont
conservés à fin de compatibilité sur les objets COMMERCE_ET_SERVICE.

De nouveaux champs informationsPrestataireActivites.activites{Sportives,Culturelles} sont introduits sur tous les objets prestataires d’activités (y compris les COMMERCE_ET_SERVICE). Ce sont les champs à utiliser pour tout nouveau développement.

Introduction de l’aspect PRESTATAIRE_ACTIVITES

Un nouvel aspect est introduit, appelé PRESTATAIRE_ACTIVITES. Le fonctionnement est le même que pour les autres aspects. C’est un aspect à privilégier si vous désirez mettre en avant l’objet touristique comme un prestataire d’activité.
(exemple : cas d’un objet RESTAURATION, qui propose des cours de cuisine en ACTIVITE ; si vous désirez faire un listing de prestataire, il faut utiliser les informations de l’aspect PRESTATAIRE_ACTIVITES si présentes).

Nouveaux champs à prendre en compte dans les aspects

Les champs informationsPrestataireActivites.activites{Sportives,Culturelles} sont éligibles à la surcharge dans l’aspect (les informations fournises dans l’aspect seront alors plus précises que celles fournies sur l’aspect standard)
Cas d’usage : un COMMERCE_ET_SERVICE de montagne (moniteur) proposant des activités en HIVER et en ETE. Les aspects HIVER et ETE permettront d’obtenir une liste d’activité contextualisée par rapport à la saison si présents.

Précision sur les objets touristiques éligibles en tant que prestataire

A titre indicatif, les types éligibles aujourd’hui comme prestataire d’activité sont listés ici. Cette liste peut être amenée à évoluer sans préavis en fonction des besoins de saisie :

COMMERCE_ET_SERVICE, DEGUSTATION, EQUIPEMENT, HEBERGEMENT_COLLECTIF, HEBERGEMENT_LOCATIF, HOTELLERIE, HOTELLERIE_PLEIN_AIR, PATRIMOINE_CULTUREL, RESTAURATION.

Résumé des actions nécessaires pour bénéficier des nouvelles informations

Remplacer le champ informationsActivite.commerceEtServicePrestataire par informationsActivite.prestataireActivites et vous assurer que le fait que
l’objet pointé n’est pas forcément un COMMERCE_ET_SERVICE ne pose pas de problème.

Récupérer les informations informationsPrestataireActivites.activites{Sportives,Culturelles} sur les objets qui les proposent (y compris les COMMERCE_ET_SERVICE. Sur les objets COMMERCE_ET_SERVICE, récupérer ces champs plutôt que les champs informationsCommerceEtService.activites{Sportives,Culturelles})

Stocker les informations de l’aspect PRESTATAIRE_ACTIVITES et les préférer aux informations de l’aspect STANDARD quand cela est nécessaire.

Traiter les champs informationsPrestataireActivites.activites{Sportives,Culturelles} comme des champs surchargeables dans les aspects.

Notification des exports

Le format de la notification des exports a été modifié. Le champ siteWebId a été renommé projetId.

> Documentation sur les exports