{"info":{"name":"Octave Flux Immobilier API (v1.2.0)","description":"# Vue d'ensemble\n\nAPI REST en lecture pour les partenaires (portails, CRM, multidiffusion). Elle expose le catalogue d'une application Octave : programmes, lots, prix, documents et images.\n\nAuthentification OAuth client_credentials, identifiants stables (tokens), pagination, m\u00e9dias via URLs S3 temporaires.\n\n---\n\n# Authentification (OAuth 2.0)\n\nGrant `client_credentials` uniquement.\n\n1. Un administrateur Octave cr\u00e9e un acc\u00e8s API (page Acc\u00e8s API) et vous donne `client_id` \/ `client_secret`.\n2. `POST \/oauth\/token` renvoie un `access_token`.\n3. Passez `Authorization: Bearer {access_token}` sur les appels m\u00e9tier.\n\n| Param\u00e8tre | Description |\n|-----------|-------------|\n| `grant_type` | `client_credentials` |\n| `client_id` \/ `client_secret` | Identifiants de l'acc\u00e8s API |\n| `application` | Slug, token ou ID de l'application (requis si l'acc\u00e8s couvre plusieurs applications) |\n\n- Dur\u00e9e de vie : `expires_in` en secondes (souvent 3600).\n- Acc\u00e8s expir\u00e9 ou supprim\u00e9 : les bearer d\u00e9j\u00e0 \u00e9mis sont refus\u00e9s.\n- Acc\u00e8s lecture seule : GET et HEAD uniquement (sinon 403).\n\n---\n\n# Identifiants\n\n| Ressource | Dans l'URL | Stable |\n|-----------|------------|--------|\n| Programme | `token` (pr\u00e9fixe `program_\u2026`) | Oui |\n| Lot | `token` | Oui |\n| Document | `token` | Oui |\n| Image | `id` m\u00e9dia | Oui pour une m\u00eame image |\n\nUtilisez les `token` dans les URLs, pas les `id` num\u00e9riques internes des programmes ou lots.\n\n---\n\n# Pagination\n\nLes listes et l export renvoient un objet `meta` (et `total` en racine pour l export) :\n\n```json\n{\n \"current_page\": 1,\n \"per_page\": 25,\n \"total\": 128,\n \"last_page\": 6\n}\n```\n\n- `total` : nombre total de programmes (ou lots) sur toutes les pages \u2014 pour savoir s il faut continuer.\n- `last_page` : derni\u00e8re page ; continuez tant que `current_page < last_page`.\n- `GET \/v1\/programs` : `per_page` d\u00e9faut 25, max 100.\n- `GET \/v1\/programs\/export` : `page` et `per_page` obligatoires (`per_page` max 25).\n- `GET \/v1\/programs\/{program}\/lots` : `per_page` d\u00e9faut 50, max 200.\n\n---\n\n# M\u00e9dias (documents et images)\n\nL'API ne sert pas les fichiers en binaire. Les r\u00e9ponses donnent des URLs S3 pr\u00e9-sign\u00e9es.\n\n- Validit\u00e9 : 24 heures (1440 minutes) \u00e0 partir de la r\u00e9ponse.\n- Apr\u00e8s expiration, rappelez l'endpoint pour de nouvelles URLs.\n- `GET \u2026\/images` : tailles `large`, `medium`, `small`.\n- Dans l'export programme, les images sont group\u00e9es par taille.\n\n---\n\n# Synchronisation\n\n1. `GET \/v1\/programs` pour la liste et les tokens (`updated_at`).\n2. `GET \/v1\/programs\/export` (pagin\u00e9) ou `GET \/v1\/programs\/{token}` pour le d\u00e9tail.\n3. Sous-ressources lots, prix, documents, images si besoin hors export.\n\n**Sync incr\u00e9mentale** : query `updated_since` (ISO 8601) sur liste et export \u2014 ne renvoie que les programmes avec `updated_at >= updated_since`.\n\n**Cache conditionnel** : en-t\u00eate `ETag` sur liste, export et d\u00e9tail ; renvoyez `If-None-Match` pour obtenir `304 Not Modified` si rien n a chang\u00e9.\n\nRespectez les plafonds `per_page`.\n\n---\n\n# Erreurs HTTP\n\n| Code | Signification |\n|------|----------------|\n| 401 | Token manquant, invalide, expir\u00e9, ou acc\u00e8s API r\u00e9voqu\u00e9 |\n| 403 | Client lecture seule sur une m\u00e9thode non autoris\u00e9e |\n| 404 | Ressource introuvable ou hors p\u00e9rim\u00e8tre de l'application |\n| 304 | Contenu inchang\u00e9 (`If-None-Match` = `ETag`) |\n| 422 | Corps OAuth invalide \/ application manquante (multi-apps) |\n\nCorps typique : `{ \"message\": \"\u2026\" }`.\n\n---\n\n# Donn\u00e9es personnelles\n\nLe flux ne contient pas d'email, pr\u00e9nom, nom, t\u00e9l\u00e9phone ni d'identifiants utilisateurs (`user_id`, `created_by`, etc.).\n\nLes op\u00e9rations commerciales sont limit\u00e9es aux champs publics (type, libell\u00e9s, dates, montants), sans listes de commercialisateurs.\n\nLes adresses concernent le programme immobilier (ligne, ville, g\u00e9oloc).\n\n---\n\n# Tester dans cette interface\n\n1. `POST \/oauth\/token` \u2192 Try it out \u2192 Execute.\n2. Copiez `access_token`.\n3. Authorize \u2192 collez le token (sans `Bearer`).\n4. Les GET deviennent ex\u00e9cutables.","schema":"https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json","_postman_id":"octave-api-1.2.0"},"variable":[{"key":"baseUrl","value":"https:\/\/api.octave.immo"},{"key":"access_token","value":""},{"key":"client_id","value":"oct_demo_sandbox"},{"key":"client_secret","value":"demo_secret_change_me"}],"auth":{"type":"bearer","bearer":[{"key":"token","value":"{{access_token}}","type":"string"}]},"item":[{"name":"Authentification","item":[{"name":"Obtenir un access token","request":{"method":"POST","header":[{"key":"Accept","value":"application\/json"},{"key":"Content-Type","value":"application\/json"}],"url":{"raw":"{{baseUrl}}\/oauth\/token","host":["{{baseUrl}}"],"path":["oauth","token"]},"description":"\u00c9change `client_id` \/ `client_secret` contre un bearer token. Aucune authentification pr\u00e9alable.\n\nSi l'acc\u00e8s est multi-applications, passez `application` (slug, token ou id).","auth":{"type":"noauth"},"body":{"mode":"raw","raw":"{\n    \"grant_type\": \"client_credentials\",\n    \"client_id\": \"{{client_id}}\",\n    \"client_secret\": \"{{client_secret}}\"\n}","options":{"raw":{"language":"json"}}}}}]},{"name":"Programmes","item":[{"name":"Lister les programmes (catalogue l\u00e9ger)","request":{"method":"GET","header":[{"key":"Accept","value":"application\/json"}],"url":{"raw":"{{baseUrl}}\/v1\/programs","host":["{{baseUrl}}"],"path":["v1","programs"]},"description":"Liste l\u00e9g\u00e8re : `token`, `name`, `slug`, `is_active`, `updated_at`. Filtre optionnel `updated_since`. Support ETag \/ If-None-Match.","auth":{"type":"bearer","bearer":[{"key":"token","value":"{{access_token}}","type":"string"}]}}},{"name":"Exporter les programmes (flux complet pagin\u00e9)","request":{"method":"GET","header":[{"key":"Accept","value":"application\/json"}],"url":{"raw":"{{baseUrl}}\/v1\/programs\/export","host":["{{baseUrl}}"],"path":["v1","programs","export"]},"description":"Export d\u00e9taill\u00e9 : lots, prix, documents (URLs sign\u00e9es), images par taille, fiscalit\u00e9s, adresses, prestations, etc. `page` et `per_page` sont obligatoires (`per_page` max 25). Filtre optionnel `updated_since`. Support ETag \/ If-None-Match.","auth":{"type":"bearer","bearer":[{"key":"token","value":"{{access_token}}","type":"string"}]}}},{"name":"Consulter un programme (d\u00e9tail complet)","request":{"method":"GET","header":[{"key":"Accept","value":"application\/json"}],"url":{"raw":"{{baseUrl}}\/v1\/programs\/{program}","host":["{{baseUrl}}"],"path":["v1","programs","{program}"]},"description":"M\u00eame richesse que l'export, pour un seul programme identifi\u00e9 par son `token`.","auth":{"type":"bearer","bearer":[{"key":"token","value":"{{access_token}}","type":"string"}]}}},{"name":"Export d'exemple (sans authentification)","request":{"method":"GET","header":[{"key":"Accept","value":"application\/json"}],"url":{"raw":"{{baseUrl}}\/v1\/sample\/export","host":["{{baseUrl}}"],"path":["v1","sample","export"]},"description":"Exemple de payload d'export, sans authentification.","auth":{"type":"noauth"}}}]},{"name":"Lots","item":[{"name":"Lister les lots d'un programme","request":{"method":"GET","header":[{"key":"Accept","value":"application\/json"}],"url":{"raw":"{{baseUrl}}\/v1\/programs\/{program}\/lots","host":["{{baseUrl}}"],"path":["v1","programs","{program}","lots"]},"description":"Liste pagin\u00e9e des lots du programme. Pour un inventaire exhaustif avec annexes et documents, pr\u00e9f\u00e9rez souvent `GET \/v1\/programs\/{program}` ou l'export.","auth":{"type":"bearer","bearer":[{"key":"token","value":"{{access_token}}","type":"string"}]}}},{"name":"Consulter un lot","request":{"method":"GET","header":[{"key":"Accept","value":"application\/json"}],"url":{"raw":"{{baseUrl}}\/v1\/programs\/{program}\/lots\/{lot}","host":["{{baseUrl}}"],"path":["v1","programs","{program}","lots","{lot}"]},"description":"D\u00e9tail d'un lot (prix, surfaces, \u00e9tats, documents charg\u00e9s).","auth":{"type":"bearer","bearer":[{"key":"token","value":"{{access_token}}","type":"string"}]}}}]},{"name":"Prix","item":[{"name":"Lister les prix d'un lot","request":{"method":"GET","header":[{"key":"Accept","value":"application\/json"}],"url":{"raw":"{{baseUrl}}\/v1\/programs\/{program}\/lots\/{lot}\/prices","host":["{{baseUrl}}"],"path":["v1","programs","{program}","lots","{lot}","prices"]},"description":"Toutes les lignes de prix actives du lot (immobilier TTC, foncier, travaux, loyers\u2026 selon param\u00e9trage).","auth":{"type":"bearer","bearer":[{"key":"token","value":"{{access_token}}","type":"string"}]}}}]},{"name":"Documents","item":[{"name":"Lister les documents d'un programme","request":{"method":"GET","header":[{"key":"Accept","value":"application\/json"}],"url":{"raw":"{{baseUrl}}\/v1\/programs\/{program}\/documents","host":["{{baseUrl}}"],"path":["v1","programs","{program}","documents"]},"description":"Chaque document expose `url` et \u00e9ventuellement `thumbnail_url` (URLs S3 pr\u00e9-sign\u00e9es, **validit\u00e9 24 h**). Renouvelez les URLs en rappelant cet endpoint.","auth":{"type":"bearer","bearer":[{"key":"token","value":"{{access_token}}","type":"string"}]}}},{"name":"Consulter un document de programme","request":{"method":"GET","header":[{"key":"Accept","value":"application\/json"}],"url":{"raw":"{{baseUrl}}\/v1\/programs\/{program}\/documents\/{document}","host":["{{baseUrl}}"],"path":["v1","programs","{program}","documents","{document}"]},"description":"M\u00e9tadonn\u00e9es + URL S3 sign\u00e9e (`url`), validit\u00e9 24 h.","auth":{"type":"bearer","bearer":[{"key":"token","value":"{{access_token}}","type":"string"}]}}},{"name":"Lister les documents d'un lot","request":{"method":"GET","header":[{"key":"Accept","value":"application\/json"}],"url":{"raw":"{{baseUrl}}\/v1\/programs\/{program}\/lots\/{lot}\/documents","host":["{{baseUrl}}"],"path":["v1","programs","{program}","lots","{lot}","documents"]},"description":"Documents rattach\u00e9s au lot (plans de lot, fiches\u2026). URLs S3 sign\u00e9es, validit\u00e9 24 h.","auth":{"type":"bearer","bearer":[{"key":"token","value":"{{access_token}}","type":"string"}]}}}]},{"name":"Images","item":[{"name":"Lister les images d'un programme","request":{"method":"GET","header":[{"key":"Accept","value":"application\/json"}],"url":{"raw":"{{baseUrl}}\/v1\/programs\/{program}\/images","host":["{{baseUrl}}"],"path":["v1","programs","{program}","images"]},"description":"Liste des images du programme, tri\u00e9es par `order`.\n\nChaque \u00e9l\u00e9ment : `id`, `type`, `order`, `urls.large` \/ `medium` \/ `small` (URLs S3 pr\u00e9-sign\u00e9es, 24 h).\n\nDans l'export programme, le bloc `images` est group\u00e9 par taille (`large[]`, `medium[]`, `small[]`).","auth":{"type":"bearer","bearer":[{"key":"token","value":"{{access_token}}","type":"string"}]}}}]}]}