{"openapi":"3.1.0","info":{"title":"API de publication Sitigeo","version":"1.0.0","description":"Publication gratuite et illimitée des annonces immobilières des professionnels sur Sitigeo.com, depuis leur logiciel. Clé de test (sg_test_…) : tous les contrôles, rien n’est publié. Clé de production (sg_live_…) : publication immédiate. Documentation : https://developers.sitigeo.com/docs","contact":{"name":"Sitigeo","email":"contact@sitigeo.com","url":"https://developers.sitigeo.com"}},"servers":[{"url":"https://api.sitigeo.com/v1"}],"x-webhooks":"Événements listing.published, listing.rejected, listing.removed, contact.received : POST JSON signé (Sitigeo-Signature: t=…,v1=HMAC-SHA256 de \"t.corps\"). Voir https://developers.sitigeo.com/docs","security":[{"cle":[]}],"components":{"securitySchemes":{"cle":{"type":"http","scheme":"bearer","description":"Clé d’API créée dans Mon espace › Pros"}},"schemas":{"Probleme":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}},"Annonce":{"type":"object","required":["reference","type","price","surface","postal_code","city","description","fees","photos"],"properties":{"reference":{"type":"string","maxLength":120,"description":"Votre référence interne : clé d’idempotence (un même envoi ne crée jamais deux annonces)"},"type":{"type":"string","enum":["house","apartment","parking","garage","building","loft","warehouse","land","office","other"]},"title":{"type":"string","maxLength":120},"price":{"type":"integer","description":"Prix de vente honoraires inclus, en euros"},"surface":{"type":"number","description":"Surface habitable (ou du terrain), en m²"},"rooms":{"type":"integer","minimum":1},"new_build":{"type":"boolean","default":false},"exclusive":{"type":"boolean","default":false},"address":{"type":"string","description":"Adresse du bien : jamais affichée, sert à placer le bien (position publique décalée de 10 à 90 m)"},"postal_code":{"type":"string","pattern":"^\\d{5}$"},"city":{"type":"string"},"description":{"type":"string","minLength":50},"dpe":{"type":"string","enum":["A","B","C","D","E","F","G","NC"],"description":"Obligatoire pour les logements"},"ges":{"type":"string","enum":["A","B","C","D","E","F","G","NC"]},"fees":{"type":"object","required":["paid_by"],"properties":{"paid_by":{"type":"string","enum":["seller","buyer"]},"rate":{"type":"number","description":"Taux TTC du prix hors honoraires, obligatoire si paid_by = buyer"}}},"photos":{"type":"array","minItems":1,"maxItems":30,"items":{"type":"string","format":"uri"},"description":"Adresses https des photos, la première est la photo principale"},"features":{"type":"array","items":{"type":"string","enum":["piscine","jardin","ascenseur","gardien","interphone","cave","cheminee","garage","box","cuisineequipee","climatisation","chauffageind","parking","balcon","terrasse","duplex","triplex","souplex","rdc","lotissement","copropriete","dernieretage","travauxaprevoire"]}},"floor":{"type":"string"},"year_built":{"type":"integer"},"property_tax":{"type":"integer"},"video_url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["active","inactive","sold"],"default":"active"}}},"AnnoncePubliee":{"type":"object","properties":{"reference":{"type":"string"},"id":{"type":"integer"},"status":{"type":"string","enum":["active","inactive","sold","removed"]},"url":{"type":["string","null"]},"title":{"type":"string"},"type":{"type":"string"},"price":{"type":"integer"},"city":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ResultatPublication":{"type":"object","properties":{"action":{"type":"string","enum":["created","updated"]},"test":{"type":"boolean"},"listing":{"$ref":"#/components/schemas/AnnoncePubliee"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/listings":{"parameters":[{"name":"Sitigeo-Agence","in":"header","required":false,"description":"Clé d’éditeur de logiciel seulement : SIREN de l’agence pour laquelle vous publiez (elle doit vous avoir autorisé)","schema":{"type":"string","pattern":"^\\d{9}$"}}],"get":{"summary":"Lister vos annonces","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["active","inactive","sold","removed"]}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"per_page","in":"query","schema":{"type":"integer","maximum":200}}],"responses":{"200":{"description":"Vos annonces et leur statut de publication"},"400":{"description":"Clé d’éditeur sans en-tête Sitigeo-Agence","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"401":{"description":"Clé absente, inconnue, révoquée ou expirée","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"403":{"description":"Agence suspendue, pas encore validée (clé de production), ou n’ayant pas autorisé cet éditeur","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"422":{"description":"Refusée par le contrôle qualité (voir problems)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"429":{"description":"Plus de 120 requêtes par minute (en-tête Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}}}},"post":{"summary":"Créer (ou mettre à jour) une annonce","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Annonce"}}}},"responses":{"200":{"description":"Annonce publiée (201 à la création, 200 sinon ; 200 avec \"test\": true pour une clé de test)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultatPublication"}}}},"201":{"description":"Annonce publiée (201 à la création, 200 sinon ; 200 avec \"test\": true pour une clé de test)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultatPublication"}}}},"400":{"description":"Clé d’éditeur sans en-tête Sitigeo-Agence","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"401":{"description":"Clé absente, inconnue, révoquée ou expirée","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"403":{"description":"Agence suspendue, pas encore validée (clé de production), ou n’ayant pas autorisé cet éditeur","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"422":{"description":"Refusée par le contrôle qualité (voir problems)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"429":{"description":"Plus de 120 requêtes par minute (en-tête Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}}}}},"/listings/{ref}":{"parameters":[{"name":"ref","in":"path","required":true,"description":"Référence interne de l’annonce dans votre logiciel","schema":{"type":"string"}},{"name":"Sitigeo-Agence","in":"header","required":false,"description":"Clé d’éditeur de logiciel seulement : SIREN de l’agence pour laquelle vous publiez (elle doit vous avoir autorisé)","schema":{"type":"string","pattern":"^\\d{9}$"}}],"get":{"summary":"Lire une annonce","responses":{"200":{"description":"L’annonce"},"400":{"description":"Clé d’éditeur sans en-tête Sitigeo-Agence","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"401":{"description":"Clé absente, inconnue, révoquée ou expirée","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"403":{"description":"Agence suspendue, pas encore validée (clé de production), ou n’ayant pas autorisé cet éditeur","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"404":{"description":"Référence inconnue"},"422":{"description":"Refusée par le contrôle qualité (voir problems)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"429":{"description":"Plus de 120 requêtes par minute (en-tête Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}}}},"put":{"summary":"Remplacer une annonce (la crée si la référence est inconnue)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Annonce"}}}},"responses":{"200":{"description":"Annonce publiée (201 à la création, 200 sinon ; 200 avec \"test\": true pour une clé de test)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultatPublication"}}}},"201":{"description":"Annonce publiée (201 à la création, 200 sinon ; 200 avec \"test\": true pour une clé de test)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultatPublication"}}}},"400":{"description":"Clé d’éditeur sans en-tête Sitigeo-Agence","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"401":{"description":"Clé absente, inconnue, révoquée ou expirée","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"403":{"description":"Agence suspendue, pas encore validée (clé de production), ou n’ayant pas autorisé cet éditeur","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"422":{"description":"Refusée par le contrôle qualité (voir problems)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"429":{"description":"Plus de 120 requêtes par minute (en-tête Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}}}},"patch":{"summary":"Modifier quelques champs (prix, photos, statut…)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Annonce publiée (201 à la création, 200 sinon ; 200 avec \"test\": true pour une clé de test)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultatPublication"}}}},"400":{"description":"Clé d’éditeur sans en-tête Sitigeo-Agence","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"401":{"description":"Clé absente, inconnue, révoquée ou expirée","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"403":{"description":"Agence suspendue, pas encore validée (clé de production), ou n’ayant pas autorisé cet éditeur","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"404":{"description":"Référence inconnue"},"422":{"description":"Refusée par le contrôle qualité (voir problems)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"429":{"description":"Plus de 120 requêtes par minute (en-tête Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}}}},"delete":{"summary":"Retirer une annonce (vendue, mandat expiré)","responses":{"200":{"description":"Annonce retirée"},"400":{"description":"Clé d’éditeur sans en-tête Sitigeo-Agence","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"401":{"description":"Clé absente, inconnue, révoquée ou expirée","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"403":{"description":"Agence suspendue, pas encore validée (clé de production), ou n’ayant pas autorisé cet éditeur","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"404":{"description":"Référence inconnue"},"422":{"description":"Refusée par le contrôle qualité (voir problems)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"429":{"description":"Plus de 120 requêtes par minute (en-tête Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}}}}},"/sync":{"parameters":[{"name":"Sitigeo-Agence","in":"header","required":false,"description":"Clé d’éditeur de logiciel seulement : SIREN de l’agence pour laquelle vous publiez (elle doit vous avoir autorisé)","schema":{"type":"string","pattern":"^\\d{9}$"}}],"post":{"summary":"Envoyer le stock complet","description":"Chaque annonce est créée ou mise à jour ; toute annonce en ligne absente de l’envoi est retirée. Un envoi vide est refusé sauf \"allow_empty\": true. 5 000 annonces au plus.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["listings"],"properties":{"listings":{"type":"array","items":{"$ref":"#/components/schemas/Annonce"}},"allow_empty":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Bilan : created, updated, rejected, removed, et le détail par référence"},"400":{"description":"Clé d’éditeur sans en-tête Sitigeo-Agence","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"401":{"description":"Clé absente, inconnue, révoquée ou expirée","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"403":{"description":"Agence suspendue, pas encore validée (clé de production), ou n’ayant pas autorisé cet éditeur","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"422":{"description":"Refusée par le contrôle qualité (voir problems)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"429":{"description":"Plus de 120 requêtes par minute (en-tête Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}}}}},"/stats":{"parameters":[{"name":"Sitigeo-Agence","in":"header","required":false,"description":"Clé d’éditeur de logiciel seulement : SIREN de l’agence pour laquelle vous publiez (elle doit vous avoir autorisé)","schema":{"type":"string","pattern":"^\\d{9}$"}}],"get":{"summary":"Vues, contacts et mises en favori par annonce","responses":{"200":{"description":"Statistiques"},"400":{"description":"Clé d’éditeur sans en-tête Sitigeo-Agence","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"401":{"description":"Clé absente, inconnue, révoquée ou expirée","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"403":{"description":"Agence suspendue, pas encore validée (clé de production), ou n’ayant pas autorisé cet éditeur","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"422":{"description":"Refusée par le contrôle qualité (voir problems)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}},"429":{"description":"Plus de 120 requêtes par minute (en-tête Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/Probleme"}}},"required":["code","message"]}}}}}}}}}}}