Format des objets (écriture)

Afin de faciliter l’utilisation des API en écriture, les formats utilisés sont semblables aux formats utilisés en lecture. Cette page traite des spécificités lors de l’utilisation des API en écriture.

Pour plus d’informations sur le format des objets Apidae, consultez la documentation ou utilisez l’outil de sérialisation pour observer des objets existants.

Champ nom

Le champ « nom » est le seul champ strictement obligatoire à la création d’un objet touristique ; sans nom, même l’émission d’une demande à valider n’est pas possible. Lorsque vous créez un objet touristique, vous devez toujours inclure un nom français, accompagné du champ « nom » dans la fieldList des champs à traiter.

Champ type

Si vous envoyez un objet touristique entier, il est nécessaire de fournir le champ « type » de manière à ce que le moteur de désérialisation pusisse fonctionner. Exemple :

root={
    "type": "RESTAURATION",
    "presentation" : {
        "descriptifCourt" : {
            "libelleFr" : "Descriptif court FR",
            "libelleNl" : "Descriptif court NL"
        }
    },
    "informationsRestauration" : {
        "capacite" : {
            "nombreSalles" : 3,
            "nombreMaximumCouverts" : 75,
            "nombreCouvertsTerrasse" : 30
        }
    }
}

Champs date

Les champs dates sont contrôlés à l’écriture (depuis la release 1.36 – juin 2022). Comme pour les autres champs, vous pouvez vous baser sur l’API de lecture pour voir le format attendu :

2022-01-01

Tout autre format entraînera une erreur d’écriture ECRITURE_INVALID_JSON_DATA
Ex :

{
    "message" : "Erreur lors du traitement des données pour le paramètre 'root'.
               Cause: Le format de date '2022-12-03T00:00:00+01:00' est invalide...",
   "errorType" : "ECRITURE_INVALID_JSON_DATA"
}

Éléments réutilisables

Afin de pouvoir réutiliser / modifier des éléments de liste existants (moyens de communication, contacts, salles de réunion, …), il est nécessaire d’introduire les champs identifiant et identifiantTemporaire.
Les éléments de liste pouvant porter ces deux champs sont :

• les moyens de communication,
• les contacts,
• les périodes tarifaires,
• les périodes d’ouverture,
• les organismes de réservation,
• les salles de réunion

Attention lorsque vous manipulez les moyens de communication d’une entité juridique. Gardez en tête que toute modification ou suppression peut avoir des impacts sur les fiches qui utilisent cette entité comme entité de gestion ou comme entité de réservation. Les modifications sur les champs « informations.moyensCommunication » ou « contacts » d’une entité juridique doivent être effectués avec précaution.

Champ « identifiant »

On utilise le champ identifiant pour référencer un élément existant que l’on souhaite modifier ou réutiliser.

Champ « identifiantTemporaire »

Le champ identifiantTemporaire est utile si vous souhaitez créer un élément et le réutiliser sur un aspect dans le même appel. Lors de la création de l’élément, généralement sur le standard, on donne un identifiant numérique temporaire au nouvel élément, puis dans l’aspect pour réutiliser l’élement, on lui donne le même identifiant temporaire.

Exemple : réutilisation d’un nouveau moyen de communication sur un aspect :

/* Création sur le standard */
"moyensCommunication": [ {
    "identifiantTemporaire" : 12
    "type" : {
        "id" : 204,
        "elementReferenceType" : "MoyenCommunicationType"
    },
    "coordonnees" : {
        "fr" : "test@openwide.fr",
        "es" : "test@openwide.es"
    }
} ]

/* Réutilisation sur un aspect */
"moyensCommunication": [ {
    "identifiantTemporaire" : 12
} ]

Éléments du référentiel

Les éléments du référentiel (éléments de référence, communes et lieux principalement) sont amenés à changer ou à disparaître au cours de la vie de l’application Apidae. De plus, les champs contenant ces éléments sont soumis côté Apidae à des règles de validation qui peuvent être complexes. C’est pourquoi nous déconseillons fortement de tenter de reproduire un mécanisme de saisie extérieur exhaustif pour ces champs.
Il est par contre possible de gérer sans souci des saisies spécialisées (où les règles de saisie pourront être discutées et validées par un responsable du réseau Apidae).

Lors de l’ajout d’un élément de référence à un champ, vous devez préciser les valeurs id et elementReferenceType : les autres valeurs sont inutiles en écriture (libelleFr, ordre, familleCritere…) :

"conforts": [
    {
        "elementReferenceType" : "PrestationConfort",
        "id":898
    }]

$fieldlist[] = 'prestations.conforts';
$root['prestations']['conforts'] = [
    [
        'elementReferenceType' => 'PrestationConfort',
        'id' => 994 // Gaz de ville (désactivé)
    ],
    [
        'elementReferenceType' => 'PrestationConfort',
        'id' => 898 // Coin Cuisine
    ]
];

Champs obligatoires

informationsFeteEtManifestation.portee (Manifestations seulement)

"informationsFeteEtManifestation" : {
    "portee" : {
        "id" : 2354,
        "elementReferenceType" : "FeteEtManifestationPortee"
    }
}

$fieldlist[] = 'informationsFeteEtManifestation.portee';
$root['informationsFeteEtManifestation']['portee'] = [
        'id' => 2354, // Habitants
        'elementReferenceType' => 'FeteEtManifestationPortee'
];

ouverture.periodesOuvertures[].type

Si vous souhaitez ajouter des périodes d’ouverture, ce type est obligatoire pour chaque période. Les dates sont à passer au format YYYY-MM-DD et les horaires au format HH:MM:SS.

$root['ouverture']['periodesOuvertures'] = [
    [
        'dateDebut' => '2021-09-01',
        'dateFin' => '2021-10-01',
        'horaireOuverture' => '10:00:00',
        'horaireFermeture' => '12:00:00',
        //'tousLesAns' => false,
        'type' => 'OUVERTURE_SAUF' // obligatoire
    ]
];
$fieldList[] = 'ouverture.periodesOuvertures';