Référence API v1

Base URL : https://api.immowp.com
OpenAPI : /openapi.json

GET /v1

Discovery — liste des endpoints, liens doc, sans authentification.

GET /v1/connectors

Liste des connecteurs CRM supportés (public).

GET /v1/status

Auth requise. Query : crm, client.

Retourne l’état de la passerelle : active/désactivée, fin de contrat, dernier import (last_update_*), wordpress_url si capturée.

GET /v1/properties

Auth requise. Liste paginée. Format par défaut : normalized (schéma générique). Passez format=raw pour le modèle historique ImmoWP (plugin WP).

Cache serveur d’une heure. Header X-Cache: HIT|MISS|STALE. En cas d’erreur du flux, le dernier catalogue valide de moins de sept jours peut être servi avec HTTP 200 et le statut STALE.

meta.cache indique status, fetched_at (date UTC), age_seconds et stale. En secours, upstream_error vaut UPSTREAM_UNAVAILABLE. Sans cache utilisable, l’API répond HTTP 502, sans liste de biens. Une liste vide validée reste une réponse normale.

Pour synchroniser des suppressions, attendez un catalogue frais et complet sur toutes ses pages ; une erreur HTTP ou un catalogue ancien ne doit pas déclencher de suppression. Le paramètre fresh=1, réservé à la clé maître, force un appel au flux sans secours sur le cache.

GET /v1/properties/{id}

Auth requise. Détail d’un bien par affId ou affNum. Query : crm, client.

Le détail expose aussi meta.cache. Un bien absent du catalogue ancien renvoie HTTP 502 : sa disponibilité actuelle ne peut pas être vérifiée.

POST /v1/report

Auth requise (body ou headers). Utilisé par le plugin WordPress après import.

{
  "key": "your_api_key",
  "crm": "apimo",
  "client": "demo",
  "status": "success",
  "count": 42,
  "message": "Import OK",
  "site_url": "https://agence.example"
}

status ∈ success | error. Si site_url est absent, l’API tente d’extraire l’URL depuis le User-Agent WordPress (WordPress/x.y; https://…).

Headers de réponse

• X-Request-Id — corrélation support / logs
• X-ImmoWP-API-Version: 1
• X-Cache — HIT, MISS ou STALE sur les listes et détails de biens
• X-ImmoWP-Data-Fetched-At et X-ImmoWP-Data-Age — date du catalogue et âge en secondes

Codes d’erreur

Legacy v0

• GET /?variable1={crm}&variable2={client} + header Key — dump complet non paginé
• POST /report — même sémantique que /v1/report