Documentation de l’API

L'API Bertel v3 supporte plusieurs méthodes d'authentification selon votre contexte d'utilisation :

JWT (Recommandée pour les applications)

Pour les applications web/mobile avec utilisateurs connectés :

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Avantages : Accès aux données étendues selon les rôles utilisateur, sécurité maximale.

Clé API (Service-to-Service)

Pour les intégrations serveur-à-serveur :

apikey: bertel_sk_1234567890abcdef

Avantages : Accès complet aux données publiques, idéal pour les synchronisations automatiques.

Accès anonyme (Lecture seule)

Pour les données publiques uniquement :

apikey: <SUPABASE_ANON_KEY>
Authorization: Bearer <SUPABASE_ANON_KEY>

Limitations : Seules les données publiques (status = 'published') sont accessibles.

Chaque requête doit inclure :

• Content-Type: application/json
• Accept: application/json
• Content-Profile: api
• Vos en-têtes d'authentification selon votre méthode choisie (voir ci-dessus)

Exemple complet de requête

curl -X POST "https://api.bertel.re/rpc/get_object_resource" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Content-Profile: api" \
  -H "apikey: {SUPABASE_ANON_KEY}" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"p_object_id": "HOTTST0000000001"}'

Remplacez {SUPABASE_ANON_KEY} par la clé publique (anon) de votre projet Supabase. Pour les appels serveur à serveur, utilisez la clé service et un token approprié.

Selon votre méthode d'authentification, vous avez accès à différents niveaux de données :

L'API retourne des codes d'erreur spécifiques pour les problèmes d'authentification :

Exemple de réponse d'erreur

{
  "code": "PGRST301",
  "message": "JWT expired",
  "hint": "Refresh your token and try again"
}

Méthode : POST
Chemin : /rpc/<nom_fonction>

Exemples : /rpc/get_object_resource • /rpc/list_object_resources_page • /rpc/list_object_resources_since_fast • /rpc/list_object_resources_filtered_page • /rpc/list_object_resources_filtered_since_fast

Corps : JSON avec paramètres nommés (voir chaque endpoint).

Les endpoints d’énumération et de recherche acceptent un ou plusieurs codes de type d’objet via p_types (ou p_object_type selon la fonction). Liste des codes disponibles :

Exemples : "p_types": ["PSV"] pour lister uniquement les services publics • "p_types": ["RVA","CAMP"] pour aires et campings.

But — Obtenir toutes les données d’un objet (et, si demandé, son tracé KML/GPX pour un itinéraire).

Paramètres (JSON)

{
  "p_object_id": "HOT123",
  "p_lang_prefs": ["fr", "en"],
  "p_track_format": "kml",
  "p_options": {
    "include_stages": true,
    "stage_color": "blue",
    "render": true,
    "render_locale": "fr-FR",
    "fields": ["id", "name", "contacts", "media"],
    "org_object_id": "ORG456"
  }
}

Exemples d’appel

curl -X POST "{BASE_URL}/rpc/get_object_resource" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Content-Profile: api" \
  -H "apikey: {SUPABASE_ANON_KEY}" \
  -H "Authorization: Bearer {SUPABASE_ANON_KEY}" \
  -d '{
    "p_object_id": "ITI123",
    "p_lang_prefs": ["fr","en"],
    "p_track_format": "kml",
    "p_options": { "include_stages": true, "stage_color": "blue" }
  }'

const res = await fetch(`${BASE_URL}/rpc/get_object_resource`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Content-Profile": "api",
    "apikey": SUPABASE_ANON_KEY,
    "Authorization": `Bearer ${SUPABASE_ANON_KEY}`
  },
  body: JSON.stringify({
    p_object_id: "ITI123",
    p_lang_prefs: ["fr","en"],
    p_track_format: "none" // pas de tracé par défaut
  })
});
const json = await res.json();

But — Lister des ressources avec pagination simple (offset/page), filtrées par type, statut, recherche. Par défaut, pas de tracé.

Paramètres (JSON)

Réponse

{
  "info": {
    "kind": "page",
    "language": "fr",
    "language_fallbacks": ["fr","en"],
    "page_size": 50,
    "offset": 0,
    "total": 1234,
    "cursor": "<opaque>",
    "next_cursor": "<opaque or null>"
  },
  "data": [ /* ressources */ ]
}

Flux d’usage

1. Premier appel sans p_cursor.
2. Lisez info.next_cursor.
3. Rappelez en passant p_cursor pour la page suivante, etc.

Exemple (cURL)

curl -X POST "{BASE_URL}/rpc/list_object_resources_page" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Content-Profile: api" \
  -H "apikey: {SUPABASE_ANON_KEY}" \
  -H "Authorization: Bearer {SUPABASE_ANON_KEY}" \
  -d '{
    "p_page_size": 20,
    "p_types": ["ITI"],
    "p_status": ["published"],
    "p_search": "crêtes",
    "p_track_format": "none"
  }'

Mode de nettoyage (omit_empty)

Le paramètre p_omit_empty permet de réduire la taille des réponses en supprimant automatiquement les blocs de données vides au niveau supérieur de chaque ressource.

Comment l'utiliser

Passez p_omit_empty: true dans l'endpoint de pagination :

curl -X POST "{BASE_URL}/rpc/list_object_resources_page" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Content-Profile: api" \
  -H "apikey: {SUPABASE_ANON_KEY}" \
  -H "Authorization: Bearer {SUPABASE_ANON_KEY}" \
  -d '{
    "p_page_size": 2,
    "p_omit_empty": true
  }'

Le paramètre est également préservé dans le curseur et propagé automatiquement aux appels suivants.

Ce qui est supprimé

Quand omit_empty est activé, les blocs suivants sont supprimés s'ils sont vides :

• actors[] — Personnes liées à l'objet
• legal_records[] — Documents légaux
• meeting_rooms[] — Salles de réunion
• fma[] — Événements FMA
• fma_occurrences[] — Occurrences d'événements

Note : Les blocs opening_times et render sont toujours conservés, même s'ils sont vides.

But — Synchroniser ce qui a changé depuis un instant T (robuste pendant les mises à jour).

Réponse

{
  "info": {
    "kind": "since",
    "language": "fr",
    "language_fallbacks": ["fr"],
    "since": "2024-04-01T00:00:00Z",
    "use_source": false,
    "limit": 50,
    "cursor": "<opaque>",
    "next_cursor": "<opaque or null>"
  },
  "data": [ /* ressources modifiées/ajoutées depuis p_since */ ]
}

Flux d’usage (sync incrémentale)

1. Appelez avec votre p_since (ex. dernière sync réussie).
2. Tant que next_cursor n’est pas null, chaînez avec p_cursor.
3. Enregistrez ensuite un nouveau “since” (ex. maintenant) pour la prochaine sync.

But — Même idée que §2.2, mais avec un JSON de filtres riches p_filters.

{
  "amenities_any": ["PARKING","WIFI"],
  "itinerary": { "is_loop": true, "distance_max_km": 15, "practices_any": ["hiking"] },
  "within_radius": { "lat": 45.76, "lon": 4.84, "radius_m": 20000 },
  "media_types_any": ["image"],
  "media_published_only": true,
  "media_must_have_main": true
}

But — La combinaison de §2.3 (since/keyset) et §2.4 (filtres riches).

Réponse : même forme que §2.3, avec filters propagés dans le curseur.

But — Récupérer des objets avec leurs données en profondeur : objets parents, acteurs, organisations et contacts associés. Idéal pour les applications nécessitant des informations complètes.

2.6.1 Récupérer un objet avec Deep Data : get_object_with_deep_data

2.6.2 Récupérer plusieurs objets avec Deep Data : get_objects_with_deep_data

2.6.3 Lister par type avec Deep Data : get_objects_by_type_with_deep_data

2.6.4 Rechercher avec Deep Data : search_objects_with_deep_data

2.6.5 Recherche spécialisée restaurants : search_restaurants_by_cuisine

2.6.6 Recherche événements par cuisine : search_events_by_restaurant_cuisine

Structure de réponse Deep Data

Les fonctions Deep Data retournent une structure enrichie :

{
  "object": {
    // Données complètes de l'objet principal (comme get_object_resource)
    "id": "HOT123",
    "name": "Hôtel Example",
    "type": "HOT",
    "contacts": [...],
    "media": [...],
    // ... toutes les autres données de l'objet
  },
  "parent_objects": [
    {
      "id": "ORG456",
      "type": "ORG", 
      "name": "Organisation Parent",
      "status": "published",
      "relation_type": {
        "id": "uuid-relation-type",
        "name": "Gestionnaire"
      },
      "distance_m": 100,
      "note": "Relation de gestion",
      "basic_info": {
        "id": "ORG456",
        "type": "ORG",
        "name": "Organisation Parent",
        "status": "published"
      }
    }
  ],
  "actors": [
    {
      "id": "actor-uuid",
      "display_name": "Jean Dupont",
      "first_name": "Jean",
      "last_name": "Dupont",
      "role": {
        "id": "role-uuid",
        "code": "manager",
        "name": "Gestionnaire"
      },
      "is_primary": true,
      "valid_from": "2024-01-01",
      "valid_to": "2024-12-31",
      "contacts": [...]
    }
  ],
  "organizations": [
    {
      "id": "ORG789",
      "type": "ORG",
      "name": "Agence de Conciergerie",
      "status": "published",
      "role": {
        "id": "org-role-uuid",
        "code": "concierge",
        "name": "Conciergerie"
      },
      "contacts": [...]
    }
  ]
}

Chaque réponse de l’API provient d’un modèle relationnel unifié. Les blocs ci-dessous sont assemblés à partir des tables et vues principales :

• Objets touristiques object — entité cœur pour tous les types (hébergements, itinéraires, événements, etc.) avec les métadonnées communes (statut, dates de publication, indicateurs d’édition en cours).
• Localisation unifiée object_location — regroupe adresse postale, coordonnées géographiques et rattachements territoriaux via object_zone.
• Contenus multilingues object_description et colonnes *_i18n — textes publics, chapôs, infos mobiles stockés soit en JSONB, soit via la table générique i18n_translation exposée dans les vues api.*.
• Contacts & médias object_contact, media — téléphones, e-mails, réseaux sociaux et ressources médias, y compris les médias spécifiques à un lieu via media.place_id.
• Référentiels ref_code, ref_classification_scheme, ref_classification_value — types, labels, classements et tags reliés aux objets par object_classification et object_capacity.
• Accessibilité & labels handicap — entrées object_classification avec scheme_code = "HANDICAP_LABEL", valeurs et sous-valeurs (subvalue_ids) pour chaque handicap couvert (moteur, visuel, auditif, mental), justificatifs optionnels via ref_document.
• Horaires d’ouverture opening_period, opening_schedule, opening_time_period — structure hiérarchique permettant de décrire des plages complexes et leurs exceptions.
• Modération pending_change, object_version — suivi des propositions de modification et historisation avant/après pour audit.
• API JSON — vues et fonctions du schéma api (ex. api.v_hot, api.v_objects, api.v_needed, api.get_object_resource) qui orchestrent les blocs ci-dessus.

Les sections du dictionnaire (§3.x) décrivent comment ces blocs sont agrégés pour produire chaque champ. Pour une vision exhaustive, consultez le schéma SQL : schema_unified.sql.

Bloc contenant toutes les descriptions multilingues de l'objet, avec support pour différents contextes d'affichage et mesures sanitaires.

Le bloc contacts[] regroupe tous les moyens de contact disponibles pour un établissement : téléphone, email, site web, réseaux sociaux, etc. Chaque contact inclut des métadonnées pour l'affichage et la priorisation.

Types de contacts disponibles

Le système supporte plusieurs types de contacts via le référentiel contact_kind :

Exemple concret : Contacts d'un hôtel

{
  "contacts": [
    {
      "kind_code": "phone",
      "kind_name": "Téléphone",
      "kind_description": "Numéro de téléphone",
      "icon_url": "https://cdn.example.com/phone.svg",
      "value": "+262 262 12 34 56",
      "is_public": true,
      "is_primary": true,
      "role": "booking",
      "position": 1
    },
    {
      "kind_code": "email",
      "kind_name": "E-mail",
      "kind_description": "Adresse électronique",
      "icon_url": "https://cdn.example.com/email.svg",
      "value": "contact@hotel-exemple.fr",
      "is_public": true,
      "is_primary": false,
      "role": "info",
      "position": 2
    },
    {
      "kind_code": "website",
      "kind_name": "Site web",
      "kind_description": "Site internet",
      "icon_url": "https://cdn.example.com/website.svg",
      "value": "https://www.hotel-exemple.fr",
      "is_public": true,
      "is_primary": false,
      "role": "info",
      "position": 3
    },
    {
      "kind_code": "whatsapp",
      "kind_name": "WhatsApp",
      "kind_description": "Contact WhatsApp",
      "icon_url": "https://cdn.example.com/whatsapp.svg",
      "value": "+262 692 12 34 56",
      "is_public": true,
      "is_primary": false,
      "role": "booking",
      "position": 4
    }
  ]
}

Utilisation pratique

Le bloc languages[] indique les langues parlées par le personnel de l'établissement. Cette information est cruciale pour l'accessibilité et l'expérience client.

Langues supportées

Le système supporte les principales langues via le référentiel ref_language :

Exemple concret : Langues d'un hôtel

{
  "languages": [
    {
      "code": "fr",
      "name": "Français"
    },
    {
      "code": "en",
      "name": "Anglais"
    },
    {
      "code": "de",
      "name": "Allemand"
    },
    {
      "code": "es",
      "name": "Espagnol"
    }
  ]
}

Utilisation pratique

Le bloc media[] contient tous les médias publiés associés à l'établissement : photos, vidéos, documents PDF, etc. La réponse n'inclut que les médias publiés.

Types de médias disponibles

Le système supporte plusieurs types de médias via le référentiel media_type :

Exemple concret : Médias d'un hôtel

{
  "media": [
    {
      "id": "media_001",
      "type_code": "image",
      "type_name": "Image",
      "icon_url": "https://cdn.example.com/image.svg",
      "title": "Vue panoramique de l'hôtel",
      "credit": "© Hôtel Exemple",
      "url": "https://cdn.example.com/hotel-panorama.jpg",
      "is_main": true,
      "visibility": "public",
      "position": 1,
      "width": 1920,
      "height": 1080
    },
    {
      "id": "media_002",
      "type_code": "video",
      "type_name": "Vidéo",
      "icon_url": "https://cdn.example.com/video.svg",
      "title": "Visite virtuelle de l'hôtel",
      "credit": "© Hôtel Exemple",
      "url": "https://cdn.example.com/hotel-tour.mp4",
      "is_main": false,
      "visibility": "public",
      "position": 2,
      "width": 1920,
      "height": 1080
    },
    {
      "id": "media_003",
      "type_code": "brochure_pdf",
      "type_name": "Brochure PDF",
      "icon_url": "https://cdn.example.com/pdf.svg",
      "title": "Brochure complète 2024",
      "credit": "© Hôtel Exemple",
      "url": "https://cdn.example.com/brochure-2024.pdf",
      "is_main": false,
      "visibility": "public",
      "position": 3,
      "width": null,
      "height": null
    }
  ]
}

Utilisation pratique

Le bloc capacity[] définit les capacités d'accueil de l'établissement selon différentes métriques : nombre de lits, couverts, chambres, etc. Ces informations sont essentielles pour la planification et la réservation.

Métriques de capacité disponibles

Le système supporte plusieurs métriques via le référentiel ref_capacity_metric :

Exemple concret : Capacités d'un hôtel

{
  "capacity": [
    {
      "metric_code": "rooms",
      "metric_name": "Chambres",
      "icon_url": "https://cdn.example.com/room.svg",
      "value": 25,
      "unit": "chambres"
    },
    {
      "metric_code": "beds",
      "metric_name": "Lits",
      "icon_url": "https://cdn.example.com/bed.svg",
      "value": 50,
      "unit": "lits"
    },
    {
      "metric_code": "covers",
      "metric_name": "Couverts",
      "icon_url": "https://cdn.example.com/restaurant.svg",
      "value": 80,
      "unit": "couverts"
    },
    {
      "metric_code": "parking_spaces",
      "metric_name": "Places parking",
      "icon_url": "https://cdn.example.com/parking.svg",
      "value": 30,
      "unit": "places"
    }
  ]
}

Utilisation pratique

Le bloc amenities[] liste tous les équipements et services disponibles dans l'établissement : WiFi, piscine, parking, restaurant, etc. Ces informations sont cruciales pour l'expérience client et les filtres de recherche.

Familles d'équipements disponibles

Les équipements sont organisés en familles via le référentiel amenity_family :

Équipements populaires

Voici quelques équipements couramment utilisés :

Exemple concret : Équipements d'un hôtel

{
  "amenities": [
    {
      "code": "WIFI",
      "name": "WiFi gratuit",
      "icon_url": "https://cdn.example.com/wifi.svg",
      "family": {
        "code": "connectivity",
        "name": "Connectivité",
        "icon_url": "https://cdn.example.com/connectivity.svg"
      }
    },
    {
      "code": "PARKING",
      "name": "Parking",
      "icon_url": "https://cdn.example.com/parking.svg",
      "family": {
        "code": "transport",
        "name": "Transport",
        "icon_url": "https://cdn.example.com/transport.svg"
      }
    },
    {
      "code": "POOL",
      "name": "Piscine",
      "icon_url": "https://cdn.example.com/pool.svg",
      "family": {
        "code": "outdoor",
        "name": "Extérieur",
        "icon_url": "https://cdn.example.com/outdoor.svg"
      }
    },
    {
      "code": "RESTAURANT",
      "name": "Restaurant",
      "icon_url": "https://cdn.example.com/restaurant.svg",
      "family": {
        "code": "dining",
        "name": "Restauration",
        "icon_url": "https://cdn.example.com/dining.svg"
      }
    },
    {
      "code": "SPA",
      "name": "Spa",
      "icon_url": "https://cdn.example.com/spa.svg",
      "family": {
        "code": "wellness",
        "name": "Bien-être",
        "icon_url": "https://cdn.example.com/wellness.svg"
      }
    }
  ]
}

Utilisation pratique

Ces deux blocs partagent la même structure simple mais servent des objectifs différents : environment_tags[] décrit l'environnement de l'établissement, tandis que payment_methods[] liste les moyens de paiement acceptés.

Structure commune

Tags environnementaux disponibles

Le système supporte plusieurs tags environnementaux via le référentiel environment_tag :

Moyens de paiement disponibles

Le système supporte plusieurs moyens de paiement via le référentiel payment_method :

Exemple concret : Hôtel côtier

{
  "environment_tags": [
    {
      "code": "beach",
      "name": "Plage",
      "icon_url": "https://cdn.example.com/beach.svg"
    },
    {
      "code": "lagoon",
      "name": "Lagon",
      "icon_url": "https://cdn.example.com/lagoon.svg"
    },
    {
      "code": "volcano",
      "name": "Volcan",
      "icon_url": "https://cdn.example.com/volcano.svg"
    }
  ],
  "payment_methods": [
    {
      "code": "card",
      "name": "Carte bancaire",
      "icon_url": "https://cdn.example.com/card.svg"
    },
    {
      "code": "cash",
      "name": "Espèces",
      "icon_url": "https://cdn.example.com/cash.svg"
    },
    {
      "code": "paypal",
      "name": "PayPal",
      "icon_url": "https://cdn.example.com/paypal.svg"
    }
  ]
}

Utilisation pratique

Le bloc prices[] gère la tarification complexe des établissements avec des prix variables selon les périodes, les types de clients, et les unités de facturation. Il supporte les fourchettes de prix, les conditions spéciales, et les créneaux horaires détaillés.

Structure principale d'un tarif

Types de tarifs disponibles

Le système supporte plusieurs types de tarifs via le référentiel price_kind :

Unités de tarification disponibles

Le système supporte plusieurs unités via le référentiel price_unit :

Périodes imbriquées (periods[])

Chaque tarif peut avoir des périodes spécifiques avec des créneaux horaires et des conditions particulières :

Exemple concret : Tarification hôtel complexe

{
  "prices": [
    {
      "kind": {
        "id": "uuid-kind-1",
        "code": "adult",
        "name": "Adulte",
        "position": 1,
        "icon_url": "https://cdn.example.com/adult.svg"
      },
      "unit": {
        "id": "uuid-unit-1", 
        "code": "per_night",
        "name": "Par nuit",
        "position": 1,
        "icon_url": "https://cdn.example.com/night.svg"
      },
      "amount": 120.00,
      "amount_max": null,
      "currency": "EUR",
      "valid_from": "2024-01-01",
      "valid_to": "2024-12-31",
      "conditions": "Petit-déjeuner inclus, TVA comprise",
      "periods": [
        {
          "id": "uuid-period-1",
          "start_date": "2024-07-01",
          "end_date": "2024-08-31",
          "start_time": "15:00",
          "end_time": "11:00",
          "note": "Haute saison - Prix majoré"
        },
        {
          "id": "uuid-period-2",
          "start_date": "2024-09-01",
          "end_date": "2024-10-31",
          "start_time": "16:00",
          "end_time": "10:00",
          "note": "Saison intermédiaire"
        }
      ]
    },
    {
      "kind": {
        "id": "uuid-kind-2",
        "code": "child",
        "name": "Enfant",
        "position": 2,
        "icon_url": "https://cdn.example.com/child.svg"
      },
      "unit": {
        "id": "uuid-unit-1", 
        "code": "per_night",
        "name": "Par nuit",
        "position": 1,
        "icon_url": "https://cdn.example.com/night.svg"
      },
      "amount": 60.00,
      "amount_max": null,
      "currency": "EUR",
      "valid_from": "2024-01-01",
      "valid_to": "2024-12-31",
      "conditions": "Enfant de 3 à 12 ans, petit-déjeuner inclus",
      "periods": []
    },
    {
      "kind": {
        "id": "uuid-kind-3",
        "code": "group",
        "name": "Groupe",
        "position": 3,
        "icon_url": "https://cdn.example.com/group.svg"
      },
      "unit": {
        "id": "uuid-unit-2", 
        "code": "per_person",
        "name": "Par personne",
        "position": 2,
        "icon_url": "https://cdn.example.com/person.svg"
      },
      "amount": 80.00,
      "amount_max": 100.00,
      "currency": "EUR",
      "valid_from": "2024-01-01",
      "valid_to": "2024-12-31",
      "conditions": "Minimum 10 personnes, petit-déjeuner inclus",
      "periods": []
    }
  ]
}

Utilisation pratique

Le bloc classifications[] regroupe tous les labels, classements et certifications attribués à un objet touristique. C'est ici que sont stockées les étoiles d'hôtel, les labels environnementaux, les certifications d'accessibilité et autres reconnaissances officielles.

Types de classifications disponibles

Le système supporte plusieurs types de classifications via le référentiel ref_classification_scheme :

Exemple concret : Hôtel 4 étoiles

{
  "classifications": [
    {
      "scheme": "hot_stars",
      "scheme_name": "Classement hôtelier",
      "value": "4",
      "value_name": "4 étoiles",
      "awarded_at": "2024-01-15",
      "valid_until": "2025-01-15",
      "status": "active"
    },
    {
      "scheme": "green_key",
      "scheme_name": "La Clef Verte",
      "value": "certified",
      "value_name": "Certifié",
      "awarded_at": "2024-03-01",
      "valid_until": "2025-03-01",
      "status": "active"
    }
  ]
}

Utilisation pratique

Expose la labellisation « Tourisme & Handicap » pour chaque objet. Les entrées sont issues de object_classification avec le schéma HANDICAP_LABEL, les sous-valeurs (subvalue_ids) représentant les handicaps couverts.

{
  "handicap_labels": [
    {
      "scheme": { "code": "HANDICAP_LABEL", "name": "Tourisme & Handicap" },
      "value": { "code": "th_level_4", "name": "Labellisé 4 handicaps", "position": 4 },
      "dimensions": [
        { "code": "HANDICAP_MOTOR", "name": "Moteur" },
        { "code": "HANDICAP_VISUAL", "name": "Visuel" },
        { "code": "HANDICAP_AUDITORY", "name": "Auditif" },
        { "code": "HANDICAP_MENTAL", "name": "Mental" }
      ],
      "awarded_at": "2023-06-15",
      "valid_until": "2026-06-14",
      "status": "granted",
      "document": { "id": "uuid-doc-1", "title": "Attestation 2023", "url": "https://…/attestation.pdf" },
      "note": "Renouvellement 2023"
    }
  ]
}

Le bloc tags[] contient des étiquettes thématiques personnalisées pour caractériser l'établissement : "romantique", "familial", "luxe", "authentique", etc. Ces tags permettent un filtrage et une catégorisation fine des établissements.

Types de tags populaires

Voici quelques exemples de tags couramment utilisés :

Exemple concret : Tags d'un hôtel de charme

{
  "tags": [
    {
      "slug": "romantique",
      "name": "Romantique",
      "color": "#FF6B6B",
      "icon": "heart",
      "icon_url": "https://cdn.example.com/heart.svg"
    },
    {
      "slug": "authentique",
      "name": "Authentique",
      "color": "#6BCF7F",
      "icon": "leaf",
      "icon_url": "https://cdn.example.com/leaf.svg"
    },
    {
      "slug": "historique",
      "name": "Historique",
      "color": "#8B4513",
      "icon": "castle",
      "icon_url": "https://cdn.example.com/castle.svg"
    },
    {
      "slug": "tranquille",
      "name": "Tranquille",
      "color": "#95A5A6",
      "icon": "peace",
      "icon_url": "https://cdn.example.com/peace.svg"
    }
  ]
}

Utilisation pratique

Le bloc meeting_rooms[] décrit les salles de réunion, de conférence et d'événements disponibles dans l'établissement, avec leurs capacités selon différents formats d'organisation et leurs équipements techniques.

Structure d'une salle de réunion

Formats de salle expliqués

Les différentes capacités correspondent aux formats d'organisation d'événements :

Équipements disponibles

Le système supporte plusieurs types d'équipements via le référentiel meeting_equipment :

Exemple concret : Salle de conférence

{
  "meeting_rooms": [
    {
      "name": "Salle des Palmiers",
      "surface": 120,
      "cap_theatre": 80,
      "cap_u": 24,
      "cap_classroom": 40,
      "cap_boardroom": 16,
      "cap_cocktail": 100,
      "cap_banquet": 60,
      "equipment": [
        {
          "code": "projector",
          "name": "Vidéoprojecteur",
          "icon_url": "https://cdn.example.com/projector.svg"
        },
        {
          "code": "screen",
          "name": "Écran de projection",
          "icon_url": "https://cdn.example.com/screen.svg"
        },
        {
          "code": "sound_system",
          "name": "Système audio",
          "icon_url": "https://cdn.example.com/sound.svg"
        },
        {
          "code": "wifi",
          "name": "WiFi",
          "icon_url": "https://cdn.example.com/wifi.svg"
        },
        {
          "code": "air_conditioning",
          "name": "Climatisation",
          "icon_url": "https://cdn.example.com/ac.svg"
        }
      ]
    }
  ]
}

Utilisation pratique

Structure d'horaires d'ouverture organisée en deux groupes temporels :

Structure d'une période d'ouverture

Jours de la semaine

Pour chaque jour (lundi, mardi, mercredi, jeudi, vendredi, samedi, dimanche), jusqu'à 2 créneaux horaires peuvent être définis :

• [jour]heuredebut1 / [jour]heurefin1 : Premier créneau
• [jour]heuredebut2 / [jour]heurefin2 : Deuxième créneau (optionnel)

{
  "PeriodeOuvertures": [
    {
      "ID": "uuid-period-1",
      "Ordre": 1,
      "SyndicObjectId": "OBJ_001",
      "Datedebut": "2024-01-01",
      "Datefin": "2024-12-31",
      "Joursfermeture": [],
      "lundiheuredebut1": "09:00",
      "lundiheurefin1": "18:00",
      "mardiheuredebut1": "09:00",
      "mardiheurefin1": "18:00",
      "mercrediheuredebut1": "09:00",
      "mercrediheurefin1": "12:00",
      "mercrediheuredebut2": "14:00",
      "mercrediheurefin2": "18:00",
      "dimancheheuredebut1": null,
      "dimancheheurefin1": null
    }
  ],
  "PeriodeOuverturesAnneeSuivantes": []
}

Articles de menu (items[])

Tags & Allergènes : structure { id, code, name, icon_url }

Médias des articles (media[])

Chaque article de menu peut avoir des médias associés (photos, vidéos, etc.) via la table de liaison object_menu_item_media.

Colonnes du lieu (id, nom, position, …).

descriptions[] : multilingue — structure transparente (ex. language, text, position, …).

Associe les actions de durabilité et les labels obtenus.

Les relations sont exposées par sens pour plus de clarté : outgoing_relations[] (liens sortants) et incoming_relations[] (liens entrants). Chaque entrée fournit le type de relation et les métadonnées nécessaires.

• outgoing_relations[] : l'objet courant pointe vers une autre ressource exposée sous target: { id, type, name }.
• incoming_relations[] : une autre ressource référence l'objet courant, exposée sous source: { id, type, name }.

Chaque enregistrement conserve les métadonnées du lien (id, relation_type_id, distance_m, note, position, created_at, updated_at) et ajoute le nœud opposé déjà résolu (target ou source).

Pour interpréter le type de relation, mappez relation_type_id avec la table de référence ref_object_relation_type (code, libellé, description). Les champs distance_m et note restent optionnels et peuvent être utilisés pour afficher une distance ou un commentaire éditorial.

{
  "outgoing_relations": [
    {
  "id": "uuid-relation-1",
  "relation_type_id": "uuid-type-restaurant",
  "position": 1,
  "note": null,
  "distance_m": 120.0,
  "created_at": "2024-03-12T09:15:00Z",
  "updated_at": "2024-03-12T09:15:00Z",
  "target": { "id": "RES-001", "type": "RES", "name": "Restaurant Chez Léon" }
    }
  ],
  "incoming_relations": [
    {
      "id": "uuid-relation-2",
      "relation_type_id": "uuid-type-managed-by",
      "position": 1,
      "note": null,
      "distance_m": null,
      "created_at": "2024-03-12T09:15:00Z",
      "updated_at": "2024-03-12T09:15:00Z",
      "source": { "id": "ORG-456", "type": "ORG", "name": "Organisation Parent" }
    }
  ]
}

Les objets liés ne sont pas étendus : interrogez séparément l'identifiant fourni si vous avez besoin de leurs contacts, adresses ou médias.

Cas d'usage : un objet « Restaurant » rattaché à un « Hôtel » aura un enregistrement dans outgoing_relations[] pointant vers l'hôtel. Inversement, l'hôtel verra ce restaurant apparaître dans incoming_relations[].

Liste des réductions et offres spéciales proposées par l'objet.

{
  "discounts": [
    {
      "id": "discount-1",
      "name": "Réduction séniors",
      "description": "10% de réduction pour les plus de 65 ans",
      "discount_percent": 10.0,
      "discount_amount": null,
      "currency": "EUR",
      "conditions": "Sur présentation d'une pièce d'identité",
      "valid_from": "2024-01-01",
      "valid_to": "2024-12-31",
      "is_active": true,
      "position": 1
    }
  ]
}

Politiques et conditions spécifiques aux groupes.

{
  "group_policies": [
    {
      "id": "policy-1",
      "name": "Groupes scolaires",
      "description": "Tarifs préférentiels pour les groupes scolaires",
      "min_size": 15,
      "max_size": 50,
      "notes": "Réservation obligatoire 48h à l'avance",
      "is_active": true,
      "position": 1
    }
  ]
}

Acteurs (personnes physiques) liés à l'objet avec leurs rôles et contacts. Important : Les rôles sont définis par le référentiel ref_actor_role qui détermine les codes et libellés des fonctions (director, receptionist, guide, etc.).

Rôles d'acteurs (ref_actor_role)

Le champ role.code fait référence au référentiel ref_actor_role qui définit les types de rôles disponibles dans le système.

{
  "actors": [
    {
      "id": "actor-123",
      "display_name": "Marie Martin",
      "first_name": "Marie",
      "last_name": "Martin",
      "gender": "F",
      "role": {
        "id": "role-director",
        "code": "director",
        "name": "Directeur"
      },
      "is_primary": true,
      "valid_from": "2024-01-01",
      "valid_to": "2024-12-31",
      "visibility": "public",
      "note": "Responsable principal",
      "contacts": [
        {
          "id": "contact-1",
          "kind": {
            "code": "email",
            "name": "Email"
          },
          "value": "marie.martin@hotel.com",
          "is_primary": true,
          "role": {
            "code": "work",
            "name": "Professionnel"
          }
        }
      ]
    }
  ]
}

Enregistrements légaux et certifications officielles de l'établissement.

{
  "legal_records": [
    {
      "id": "legal-1",
      "type": {
        "id": "type-siret",
        "code": "SIRET",
        "name": "SIRET",
        "category": "business"
      },
      "value": "12345678901234",
      "status": "active",
      "valid_from": "2024-01-01",
      "valid_to": null,
      "validity_mode": "forever",
      "issuer": "INSEE",
      "document": {
        "id": "doc-1",
        "url": "https://.../siret.pdf",
        "title": "Extrait SIRET",
        "visibility": "private"
      },
      "notes": "Mise à jour 2024",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Bloc contenant des données formatées prêtes à l'affichage, généré quand p_options.render: true.

{
  "render": {
    "lang": "fr",
    "locale": "fr-FR",
    "timezone": "UTC",
    "version": "1.0",
    "contact_lines": [
      "Téléphone : +262 123 456 789",
      "Email : contact@hotel.com"
    ],
    "media_lines": [
      "Photo principale : Vue de la plage",
      "Vidéo : Présentation de l'hôtel"
    ],
    "capacity_lines": [
      "Chambres : 42",
      "Lits : 84"
    ],
    "amenity_lines": [
      "Piscine, WiFi, Parking"
    ],
    "price_lines": [
      "Adulte - Par nuit : 120,00 €",
      "Enfant - Par nuit : 60,00 €"
    ]
  }
}

itinerary_details

• info : méta (ex. conseils, profils altimétriques détaillés…)
• profiles[] : variantes / tronçons alternatifs
• practices[] : { code, name, icon_url } (ex. "hiking", "mtb")
• sections[] : segments/tronçons
• stages[] : étapes (avec leur propre media[])
• associated_objects[] : voir ci-dessous pour la structure détaillée

associated_objects[]

Liste les ressources liées à l’itinéraire (hébergements, points d’intérêt, services…) avec le rôle attribué dans l’étape de production.

Les éléments sont triés par nom d’objet puis date de création. Si l’objet cible a été supprimé, target vaut null mais l’identifiant brut reste disponible pour diagnostic.

Le référentiel ref_iti_assoc_role expose les colonnes { id, code, name, description, position } : utilisez-le pour afficher un libellé utilisateur.

"associated_objects": [
  {
    "associated_object_id": "LODGE-42",
    "role_id": "0ab5d76a-55f9-4bdc-9219-6a962fbf9c5d",
    "note": "Hébergement recommandé pour la nuit 2",
    "created_at": "2024-05-06T08:12:11Z",
    "updated_at": "2024-05-14T10:33:02Z",
    "target": { "id": "LODGE-42", "type": "HOT", "name": "Lodge des Cimes" }
  }
]

itinerary

Rappels tracé — Par défaut track=null. Pour obtenir un tracé, définissez p_track_format à "kml" ou "gpx". KML : utilisez p_options.stage_color si vous incluez des étapes. GPX : stage_color ignorée.

Les événements peuvent agréger les types de cuisine proposés par leurs restaurants partenaires via le bloc associated_restaurants_cuisine_types[].

Le tableau est dédupliqué et ne contient que les types présents dans au moins un menu actif d'un restaurant lié via la relation has_restaurant. Les éléments sont triés selon le référentiel (position puis nom/code).

"associated_restaurants_cuisine_types": [
  { "id": "uuid-ct-1", "code": "local", "name": "Cuisine locale", "description": null, "position": 10 },
  { "id": "uuid-ct-2", "code": "veggie", "name": "Option végétarienne", "description": null, "position": 40 }
]

Si aucun restaurant associé ne publie de menu actif, le tableau est vide.

Ce tableau regroupe l’ensemble des pièces justificatives exposées par l’API (qu’elles soient liées à la fiche légale, à une classification ou à une action RSE). Chaque entrée correspond à un enregistrement de ref_document relié à l’objet.

"documents": [
  {
    "id": "0518c3c1-6f35-40f0-bd26-19ccaf7bc93a",
    "url": "https://cdn.example.tld/docs/certificat-accessibilite.pdf",
    "title": "Certificat accessibilité 2025",
    "issuer": "Préfecture",
    "description": "Valable jusqu'au 31/12/2025",
    "valid_from": "2024-01-01",
    "valid_to": "2025-12-31",
    "visibility": "public",
    "position": 1,
    "tags": ["legal", "handicap"]
  }
]

Ce bloc retrace la vie des demandes de documents métiers : qui a demandé quoi, quand l’objet a fourni la pièce et si la visibilité est publique ou réservée. Les informations proviennent du module de suivi document_request.

"document_requests": [
  {
    "id": "dreq-2025-04",
    "document_id": "0518c3c1-6f35-40f0-bd26-19ccaf7bc93a",
    "status": "received",
    "requested_at": "2025-02-01T08:15:00Z",
    "due_at": "2025-03-01T00:00:00Z",
    "delivered_at": "2025-02-10T14:22:11Z",
    "visibility": "public",
    "requested_by": "legal@oti-sud.fr",
    "notes": "Document contrôlé et validé"
  }
]

curl -X POST "{BASE_URL}/rpc/get_object_resource" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Content-Profile: api" \
  -H "apikey: {SUPABASE_ANON_KEY}" \
  -H "Authorization: Bearer {SUPABASE_ANON_KEY}" \
  -d '{
    "p_object_id": "RESTAURANT-001",
    "p_lang_prefs": ["fr", "en"]
  }'

La réponse inclura les menus[] avec leurs items[], catégories, prix, tags alimentaires et allergènes.

curl -X POST "{BASE_URL}/rpc/get_object_resource" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Content-Profile: api" \
  -H "apikey: {SUPABASE_ANON_KEY}" \
  -H "Authorization: Bearer {SUPABASE_ANON_KEY}" \
  -d '{
    "p_object_id": "FMA-FESTIVAL-2024",
    "p_lang_prefs": ["fr"]
  }'

Les événements peuvent aussi avoir des menus pour les repas/boissons proposés.