API Reference

L'API REST publique Nalabo360 — intégrez les visites dans vos applications.

v1 · stable

Base URL

https://votre-domaine.com

Les endpoints /api/v1/*sont publics (CORS open). Les endpoints analytiques et d'export requièrent une session authentifiée.

Tous les montants (prix, chiffre d'affaires, totaux de commande) sont des entiers en francs CFA (XOF), sans centimes : 89000 correspond à 89 000 FCFA.

Valeurs de catégorie

realestateImmobilierretailCommerce / RetailtourismTourisme / CulturehotelHôtellerieeventÉvénementielotherAutre

GET/api/v1/tours

Liste toutes les visites publiques. Supporte la recherche et la pagination.

Paramètres

`q`	string?	Recherche dans titre, description, tags
`cat`	string?	Filtre par catégorie : realestate, retail, tourism, hotel, event, other
`limit`	number?	Nombre de résultats (max 100, défaut 20)
`offset`	number?	Pagination offset (défaut 0)

Exemple

GET /api/v1/tours?cat=tourism&limit=5

Réponse

{
  "data": [
    {
      "id": 3,
      "title": "Galerie des Lumières — Musée",
      "category": "tourism",
      "tags": "toulouse,musée,art,culture",
      "lat": 43.6047,
      "lng": 1.4442,
      "views": 1243,
      "isFeatured": false
    }
  ],
  "count": 1,
  "limit": 5,
  "offset": 0
}

GET/api/v1/tours/:id

Retourne une visite publique avec ses scènes et hotspots. Les prix (price) sont des montants entiers en francs CFA (XOF), par exemple 1400 = 1 400 FCFA. Un produit expose sa photo de couverture (productImage), ses photos supplémentaires (productImages) et ses options (variantColors en hexadécimal, variantSizes).

Paramètres

id number ID de la visite

Exemple

GET /api/v1/tours/3

Réponse

{
  "data": {
    "id": 3,
    "title": "Galerie des Lumières — Musée",
    "scenes": [
      {
        "id": 4,
        "title": "Grande Galerie",
        "imageUrl": "/panoramas/museum.jpg",
        "hotspots": [
          { "id": 9, "type": "info",    "yaw": -30, "pitch": 4,  "title": "Collection permanente", "price": null },
          { "id": 10, "type": "product", "yaw": 80,  "pitch": -2, "title": "Billet coupe-file",    "price": 1400,
            "productImage": "/products/billet-1.jpg", "productImages": ["/products/billet-2.jpg"],
            "variantColors": [], "variantSizes": [] }
        ]
      }
    ]
  }
}

GET/api/search

Recherche full-text sur les visites publiques (titre, description, adresse, tags).

Paramètres

`q`	string?	Terme de recherche
`cat`	string?	Filtre catégorie
`sort`	string?	Tri : recent (défaut) \| views \| alpha

Exemple

GET /api/search?q=paris&sort=views

Réponse

[ { "id": 1, "title": "Appartement Lumière — Paris 11e", ... } ]

GET/api/qrcode/:tourId

Génère un QR Code SVG pointant vers la visite. Cache 1h.

Paramètres

tourId number ID de la visite

Exemple

GET /api/qrcode/1

Réponse

<svg ...>...</svg>  (image/svg+xml)

POST/api/hotspot-click

Enregistre un clic sur un hotspot (tracking analytics).

Paramètres

hotspotId number ID du hotspot (body JSON)

Exemple

POST /api/hotspot-click
{ "hotspotId": 10 }

Réponse

{ "ok": true }

GET/api/analytics/:tourId

Analytics détaillés d'une visite (auth requise — propriétaire uniquement). Les montants (totalRevenue, avgOrder, revByProduct, dailyRevenue, total des commandes) sont des entiers en FCFA.

Paramètres

tourId number ID de la visite

Exemple

GET /api/analytics/1

Réponse

{
  "totalViews": 342,
  "totalRevenue": 89000,
  "orderCount": 2,
  "conversion": "0.6",
  "trend": "+12.5",
  "views": [...],
  "orders": [...],
  "topProduct": [...]
}

GET/api/export/orders/:tourId

Export CSV de toutes les commandes d'une visite (auth requise). La colonne total_fcfa est un montant entier en FCFA.

Paramètres

tourId number ID de la visite

Exemple

GET /api/export/orders/2

Réponse

id,date,client,email,produits,total_fcfa,status
1,2025-01-15,Awa Diallo,awa@example.com,Billet coupe-file x2,2800,paid

Rate Limiting

Les endpoints publics sont limités à 100 req/min par IP. Pour les applications à fort trafic, contactez-nous pour un accès API dédié avec clé.

SDK JavaScript (bientôt)

Un SDK officiel est en préparation pour faciliter l'intégration.

// Bientôt disponible
import { Nalabo360Client } from '@nalabo360/sdk';
const client = new Nalabo360Client();
const tours = await client.tours.list({ cat: 'retail', limit: 10 });