API publique NGZ Ads

NGZ Ads expose une API REST publique et versionnée (/api/v1) qui donne accès aux annonces, catégories et pages du site — sans jamais passer par une session utilisateur. Elle est pensée pour être appelée depuis un script, une application tierce, un outil no-code, ou un assistant IA via le serveur MCP.

Cette page résume l'essentiel. Pour la référence complète (tous les endpoints, tous les paramètres, tous les codes d'erreur), consultez le portail dédié :

→ Documentation complète et interactive de l'API

Ce que vous pouvez faire avec l'API

Rechercher / lister les annonces actives, avec filtres (mot-clé, catégorie, prix, ville, pays, tri) et pagination.
Récupérer le détail complet d'une annonce, images comprises.
Parcourir l'arborescence des catégories, avec le nombre d'annonces actives par catégorie.
Lister et consulter les pages statiques publiées (À propos, CGU, confidentialité...).
Récupérer la spécification OpenAPI 3.0 de toute l'API, pour générer un client dans n'importe quel langage.

Toutes les réponses suivent la même enveloppe JSON :

{
  "success": true,
  "message": "OK",
  "data": { ... }
}

Authentification en un coup d'œil

L'API n'utilise ni compte utilisateur ni cookie de session : chaque application appelante s'identifie avec un couple App ID / App Secret.

Un administrateur crée une application depuis Admin → API Apps (nom, description, quota d'appels par minute).
L'écran affiche un App ID (identifiant public) et un App Secret — affiché une seule fois. Notez-le immédiatement, il ne peut être récupéré ensuite (uniquement régénéré).
Chaque appel envoie les deux identifiants, soit en deux en-têtes distincts, soit en un seul jeton Bearer :

X-App-Id: app_5f3e9c2a1b7d4e6f9a8c7d6e
X-App-Secret: sk_7c1a9e4f6b2d8e0a3c5f7b9d1e3a5c7f9b1d3e5f7a9c1e3b5d7f9a1c3e5b7d9

Authorization: Bearer app_5f3e9c2a1b7d4e6f9a8c7d6e.sk_7c1a9e4f6b2d8e0a3c5f7b9d1e3a5c7f9b1d3e5f7a9c1e3b5d7f9a1c3e5b7d9

Traitez l'App Secret comme un mot de passe. Ne le placez jamais dans une application front-end ou un dépôt public — il ne doit vivre que côté serveur.

Premier appel

Sans identifiants (endpoint public) :

curl "https://votre-site.com/api/v1/status"

Avec identifiants :

curl "https://votre-site.com/api/v1/ads?q=iphone&per_page=5" \
  -H "X-App-Id: app_5f3e9c2a1b7d4e6f9a8c7d6e" \
  -H "X-App-Secret: sk_7c1a9e4f6b2d8e0a3c5f7b9d1e3a5c7f9b1d3e5f7a9c1e3b5d7f9a1c3e5b7d9"

Versioning, quotas et suivi

Sujet	En bref
Versioning	L'API vit sous `/api/v1/`. Une future v2 arrivera en parallèle, sans casser les intégrations existantes sur v1.
Quota	Chaque application a une limite de requêtes/minute configurable (60/min par défaut) depuis Admin → API Apps.
Journalisation	Chaque appel est enregistré et consultable dans Admin → API Logs (endpoint, statut, application appelante, date).
Erreurs courantes	`401` identifiants invalides · `403` application suspendue/révoquée · `404` ressource introuvable · `422` validation · `500` erreur serveur

Aller plus loin

Spécification OpenAPI 3.0 — machine-readable, utile pour générer un client ou des outils MCP.
Documentation complète — tous les endpoints, tous les paramètres, exemples de requêtes/réponses.
Serveur MCP — pour brancher un assistant IA (Claude, ChatGPT...) directement sur ces mêmes données.

Une question, ou besoin qu'une application soit créée pour vous ? Contactez l'administrateur du site.