← Phase 3 / M18 — API Publique & Partenaires

🔌 API Publique & Partenaires

API RESTful publique permettant à des partenaires (agences de voyage, OTAs, offices de tourisme) d'intégrer les données NOMIIQ : lieux, scores de sécurité, itinéraires, alertes. Developer portal, SDK TypeScript, webhooks et tiers de facturation.

10+

Partenaires cibles

Tiers API (free/pro/ent)

OpenAPI

3.1 Spec complète

User Stories

📋 12 User Stories — M18

US18.1 Must En tant que développeur partenaire, je peux m'inscrire sur le developer portal NOMIIQ et obtenir une API key en moins de 5 minutes.

US18.2 Must En tant que développeur, je peux consulter la documentation API complète (OpenAPI 3.1 + Swagger UI interactif).

US18.3 Must En tant que partenaire, je peux requêter les données de lieux (GET /places) avec filtres (pays, type, score sécurité) en lecture seule.

US18.4 Must En tant que partenaire, je peux obtenir le score de sécurité d'une destination en temps réel avec résumé IA.

US18.5 Must En tant que partenaire, je suis limité par rate limiting selon mon tier (free: 100 req/j, pro: 10k, enterprise: illimité).

US18.6 Should En tant que partenaire, je peux m'abonner à des webhooks pour recevoir les alertes sécurité en temps réel sur mes destinations suivies.

US18.7 Should En tant que développeur, je peux utiliser le SDK TypeScript officiel (@nomiiq/sdk) pour intégrer l'API facilement.

US18.8 Should En tant que partenaire pro, je peux accéder aux itinéraires publics NOMIIQ (lecture seule) pour les intégrer dans mes propres produits.

US18.9 Should En tant que développeur, je dispose d'un sandbox (données factices) pour tester l'API sans impacter la production.

US18.10 Could En tant que partenaire enterprise, je peux obtenir un accès SLA garanti (99.9% uptime) avec support dédié.

US18.11 Could En tant que partenaire, je reçois des rapports mensuels d'utilisation (requêtes, latence, erreurs) par email.

US18.12 Could En tant qu'admin NOMIIQ, je peux activer/désactiver un partenaire et voir ses statistiques d'utilisation en temps réel.

API Reference

🔗 Endpoints API Publique v1

📍 Places & Safety

Endpoint	Description
`GET /v1/places`	Liste lieux (filtres: country, type, lat/lng, radius)
`GET /v1/places/:id`	Fiche lieu complet + score sécurité
`GET /v1/places/:id/safety`	Score sécurité détaillé + résumé IA
`GET /v1/places/:id/alerts`	Alertes actives sur un lieu
`GET /v1/places/search`	Recherche full-text (q=tokyo)
`GET /v1/countries/:code/safety`	Sécurité niveau pays (GDELT + advisories)

🛤️ Itinéraires & Contenu

Endpoint	Description
`GET /v1/itineraries`	Itinéraires publics (paginé, filtré)
`GET /v1/itineraries/:id`	Itinéraire complet (public uniquement)
`GET /v1/itineraries/featured`	Sélection éditoriale NOMIIQ
`POST /v1/webhooks`	S'abonner à des événements
`DELETE /v1/webhooks/:id`	Désabonnement
`GET /v1/webhooks`	Mes webhooks actifs

Tarification

💰 Tiers API & Tarification

Free

0€/mois

✓100 requêtes / jour

✓Données places & safety

✓Pas de webhooks

✓Support communauté

✓Sandbox inclus

Recommandé

Pro

199€/mois

✓10 000 requêtes / jour

✓Itinéraires publics inclus

✓5 webhooks actifs

✓Email support (48h)

✓Rapport mensuel

✓SLA 99%

Enterprise

Sur devis

✓Illimité

✓Accès données premium

✓Webhooks illimités

✓Support dédié (4h)

✓Accès SDK custom

✓SLA 99.9% + pénalités

Base de données

🗄️ Tables — Developer Portal

🔑 Table `api_partners`

          id UUID PRIMARY KEY

          company_name TEXT NOT NULL

          email TEXT UNIQUE NOT NULL

          tier ENUM(free,pro,enterprise)

          api_key_hash TEXT UNIQUE -- bcrypt

          api_key_prefix CHAR(8) -- nq_live_xxxx

          daily_quota INT DEFAULT 100

          daily_used INT DEFAULT 0

          quota_reset_at TIMESTAMPTZ

          is_active BOOLEAN DEFAULT true

          stripe_customer_id TEXT

          created_at TIMESTAMPTZ

🔔 Table `api_webhooks`

          id UUID PRIMARY KEY

          partner_id UUID → api_partners

          event_types TEXT[] -- ['safety.alert','itinerary.new']

          target_url TEXT NOT NULL

          secret TEXT -- HMAC signing key

          is_active BOOLEAN DEFAULT true

          last_triggered_at TIMESTAMPTZ

          fail_count INT DEFAULT 0

          created_at TIMESTAMPTZ

📊 Table `api_requests_log` (audit & billing)

        id, partner_id, endpoint, method, status_code, latency_ms, ip_address, user_agent, request_at

        -- Partitionnée par mois (pg_partman). Rétention 90 jours. Agrégation quotidienne vers partner_daily_stats.

Sécurité API

🔒 Sécurité & Authentification API

🔑

Clés API

Format nq_live_XXXXX (prod) / nq_test_XXXXX (sandbox). Stockées en bcrypt en base. Rotation possible sans interruption.

🛡️

HMAC Webhooks

Chaque payload webhook signé avec HMAC-SHA256. Header X-NOMIIQ-Signature. Partenaire vérifie la signature.

⚡

Rate Limiting

Redis sliding window par clé API. Headers X-RateLimit-Limit/Remaining/Reset renvoyés. 429 si dépassé.

🌐

CORS & Origines

Whitelist d'origines par partenaire. Requêtes server-to-server recommandées (pas de clé côté client).