Documentation de l'API

Authentification & En-têtes

L’API requiert une clé associée à votre entreprise, transmise via l’en-tête X-API-KEY, ainsi que la langue et le format JSON:API. Vous pouvez générer ou consulter votre clé depuis votre espace API (connexion requise). 

-H "X-API-KEY: VOTRE_CLE" \
-H "Accept-Language: fr_FR" \
-H "Accept: application/vnd.api+json"

Par défaut, le plugin WordPress pointe vers https://flowlead.fr/api/v1 (modifiable dans les options du plugin).

Erreurs & Codes retour

  • 401 — Clé X-API-KEY manquante ou incorrecte
  • 404 — Ressource introuvable
  • 4xx/5xx — Erreurs retournées au format JSON:API (objet errors)

API Posts

Cette section détaille les endpoints pour récupérer et filtrer les articles. À noter : l’attribut image_path est retourné (URL absolue de l’image de l’article, ou null s’il n’y en a pas).

GET /api/v1/posts

Récupère la liste paginée des articles au format JSON:API. Utilise page[number] (et optionnellement page[size]).

curl \
  -H "X-API-KEY: VOTRE_CLE" \
  -H "Accept-Language: fr_FR" \
  -H "Accept: application/vnd.api+json" \
  "https://votre-domaine.com/api/v1/posts?page[number]=1"
                            
Réponse (exemple) :
{
  "data": [
    {
      "type": "posts",
      "id": "123",
      "attributes": {
        "title": "Mon article",
        "slug": "mon-article",
        "excerpt": "Court extrait",
        "content": "
Contenu HTML ou texte brut
",
        "image_path": "https://flowlead.fr/storage/posts/mon-article.jpg"
      }
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": null },
  "meta": { "page": { "number": 1, "size": 15 } }
}
GET /api/v1/posts/{id}

Récupère un article spécifique via son id.

curl \
  -H "X-API-KEY: VOTRE_CLE" \
  -H "Accept-Language: fr_FR" \
  -H "Accept: application/vnd.api+json" \
  "https://votre-domaine.com/api/v1/posts/123"
                            
Réponse (exemple) :
{
  "data": {
    "type": "posts",
    "id": "123",
    "attributes": {
      "title": "Mon article",
      "slug": "mon-article",
      "content": "
Contenu complet
",
      "image_path": "https://flowlead.fr/storage/posts/mon-article.jpg",
      "author": { "name": "John Doe" }
    }
  }
}
GET /api/v1/posts/slug/{slug}

Récupère un article via son slug.

curl \
  -H "X-API-KEY: VOTRE_CLE" \
  -H "Accept-Language: fr_FR" \
  -H "Accept: application/vnd.api+json" \
  "https://votre-domaine.com/api/v1/posts/slug/votre-article"
                            
Réponse (exemple) :
{
  "data": {
    "type": "posts",
    "id": "123",
    "attributes": {
      "title": "Mon article",
      "slug": "mon-article",
      "content": "
Contenu complet
",
      "image_path": "https://flowlead.fr/storage/posts/mon-article.jpg",
      "author": { "name": "John Doe" }
    }
  }
}

API Pages

Cette section détaille les endpoints pour récupérer les pages personnalisées.

Le champ content peut contenir soit du texte brut (textarea), soit un objet JSON structuré.

GET /api/v1/pages

Récupère la liste paginée des pages au format JSON:API. Utilise page[number] (et optionnellement page[size]). Supporte include=sector,locality.

curl \
  -H "X-API-KEY: VOTRE_CLE" \
  -H "Accept-Language: fr_FR" \
  -H "Accept: application/vnd.api+json" \
  "https://votre-domaine.com/api/v1/pages?include=sector,locality"
                            
Réponse (exemple) :
{
  "data": [
    {
      "type": "pages",
      "id": "456",
      "attributes": {
        "title": "Page Title",
        "slug": "votre-page",
        "content": "
Contenu HTML ou texte brut
"
      }
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": null },
  "meta": { "page": { "number": 1, "size": 15 } }
}
GET /api/v1/pages/{id}

Récupère une page spécifique via son id.

curl \
  -H "X-API-KEY: VOTRE_CLE" \
  -H "Accept-Language: fr_FR" \
  -H "Accept: application/vnd.api+json" \
  "https://votre-domaine.com/api/v1/pages/456"
                            
Réponse (exemple) :
{
  "data": {
    "type": "pages",
    "id": "456",
    "attributes": {
      "title": "Page Title",
      "slug": "votre-page",
      "content": {
        "blocks": [ /* ... */ ]
      }
    }
  }
}
GET /api/v1/pages/slug/{slug}

Récupère une page via son slug. Supporte include=locality,sector,outgoingLinks,outgoingLinks.to,outgoingLinks.to.locality,incomingLinks pour importer le maillage interne.

curl \
  -H "X-API-KEY: VOTRE_CLE" \
  -H "Accept-Language: fr_FR" \
  -H "Accept: application/vnd.api+json" \
  "https://votre-domaine.com/api/v1/pages/slug/votre-page?include=locality,sector,outgoingLinks,outgoingLinks.to,outgoingLinks.to.locality"

La réponse suit le format JSON:API et expose :

  • content_mode = html ou json
  • body (HTML, string) — présent sur la vue détail
  • body_json (JSON, objet) — présent sur la vue détail
  • image_path, meta_description, status, dates createdAt/updatedAt
  • Relations: locality, sector
  • Maillage interne (internal-links): attributs scope (sector|locality), link_kind (UP|HORIZ|DOWN), rank, score
Raccourcis inclus dans meta
  • meta.locality_name: nom de la ville de la page
  • meta.outgoing_links[]: liste simplifiée des liens sortants avec title, slug, url, image_url, locality_name, scope, kind, rank
  • meta.incoming_links[]: idem pour les liens entrants
  • meta.things_to_do[]: POIs “Things to do” de la localité (champs: name, url, image_url, source)

Ces champs sont toujours présents dans meta — pas besoin d’utiliser ?include= pour les obtenir.

{
  "meta": {
    "locality_name": "Bordeaux",
    "outgoing_links": [
      { "title": "SaaS - Talence", "slug": "saas-talence", "url": ".../api/v1/pages/slug/saas-talence", "image_url": ".../storage/pages/x.png", "locality_name": "Talence", "scope": "sector", "kind": "HORIZ", "rank": 2 }
    ],
    "incoming_links": [ /* ...même structure... */ ],
    "things_to_do": [ { "name": "Musée…", "url": "https://…", "image_url": "https://…", "source": "google" } ]
  }
}
Contrat de contenu
  • Si content_mode = html → consommez body. body_json = null.
  • Si content_mode = json → consommez body_json. body = null.
Réponse — Mode HTML (content_mode="html") :
{
  "data": {
    "type": "pages",
    "id": "456",
    "attributes": {
      "title": "Page Title",
      "slug": "votre-page",
      "content_mode": "html",
      "body": "
Bonjour
Contenu HTML…
",
      "body_json": null
    },
    "relationships": {
      "locality": { "data": { "type": "localities", "id": "1" } },
      "sector":   { "data": { "type": "sectors", "id": "2" } },
      "outgoingLinks": { "data": [
        { "type": "internal-links", "id": "901" },
        { "type": "internal-links", "id": "902" }
      ]}
    }
  }
}
                            
Inclus (exemple – internal-links) :
[
  {
    "type": "internal-links",
    "id": "901",
    "attributes": { "scope": "sector", "link_kind": "UP", "rank": 1, "score": 0.012 },
    "relationships": { "to": { "data": { "type": "pages", "id": "789" } } }
  }
]
                            
Réponse — Mode JSON (content_mode="json") :
{
  "data": {
    "type": "pages",
    "id": "789",
    "attributes": {
      "title": "Page Title",
      "slug": "votre-page",
      "content_mode": "json",
      "body": null,
      "body_json": { "blocks": [/* … */] }
    }
  }
}