Adlead - Documentation

# Lots

# ⚠️ Bonnes pratiques d'utilisation ⚠️

Les routes /lots et /allotments sont particulièrement consommatrices en ressources, car elles renvoient un grand volume de données.
Leur usage doit donc être raisonné afin de préserver la performance et la stabilité de l'API.

Avant d'implémenter une récupération automatique, nous vous invitons à :

  • Limiter la fréquence des appels : les grilles de lots ne changent pas fréquemment, un rafraîchissement quotidien est généralement suffisant.
  • Utiliser les webhooks pour recevoir des notifications automatiques lors des mises à jour (nouveau lot, changement de prix, statut, etc.) si vous avez un besoin de synchronisation en temps réel.

IMPORTANT

Un usage abusif de cette route peut entraîner des restrictions sur votre clé API.
Pour en savoir plus sur les bonnes pratiques en vigueur, consultez les Bonnes pratiques spécifiques à la route /lots 🔗.

# Lister les lots

Permet de récupérer la liste des lots d'un programme.

UTILE

Pour obtenir la fiche détaillée d'un lot il est nécessaire de consulter directement sa fiche.

# Requête HTTP

GET https://api.adlead.immo/v1/{tenantKey}/programs/{programId}/lots

# Paramètres d'URL

Nom de la clé Description
{tenantKey} Clé de l'espace client - Détails
{programId} ID du programme

# curl

curl --location --request GET 'https://api.adlead.immo/v1/{tenantKey}/programs/{programId}/lots' \
    --header 'Accept: application/json' \
    --header 'X-API-Key: VOTRE_CLE_API'

# Lister les lots allotés

Permet de récupérer la liste des lots allotés d'un programme.

# Requête HTTP

GET https://api.adlead.immo/v1/{tenantKey}/programs/{programId}/allotments

# Paramètres d'URL

Nom de la clé Description
{tenantKey} Clé de l'espace client - Détails
{programId} ID du programme

# curl

curl --location --request GET 'https://api.adlead.immo/v1/{tenantKey}/programs/{programId}/allotments' \
    --header 'Accept: application/json' \
    --header 'X-API-Key: VOTRE_CLE_API'

# Consulter la fiche d'un lot

Permet de récupérer la fiche détaillée d'un lot

# Requête HTTP

GET https://api.adlead.immo/v1/{tenantKey}/programs/{programId}/lots/{lotId}

# Paramètres d'URL

Nom de la clé Description
{tenantKey} Clé de l'espace client - Détails
{programId} ID du programme
{lotId} ID du lot

# curl

curl --location --request GET 'https://api.adlead.immo/v1/{tenantKey}/programs/{programId}/lots/{lotId}' \
    --header 'Accept: application/json' \
    --header 'X-API-Key: VOTRE_CLE_API'

# Body de réponse

DETAILS 
{
    "success": true,
    "message": null,
    "data": {
        "id": 1,
        "primpromo_id": 1,
        "building": {
            "id": 1,
            "name": "La Riviera",
            "type": "VEFA",
            "vat_rate": 20,
            "has_specific_vat_rate": false,
            "specific_vat_rate": null,
            "updated_at": "2024-04-22T15:46:04.000000Z"
        },
        "reference": "A01",
        "can_be_broadcasted": true,
        "is_broadcastable": true,
        "is_primary": true,
        "type": "apartment",
        "type_display": "Appartement",
        "typology": "T2",
        "typology_display": "2 pièces",
        "subtype": null,
        "subtype_display": null,
        "floors": null,
        "level": "RDJ",
        "price_including_vat": null,
        "price_with_secondary_including_vat": null,
        "price_with_secondary_reduced_vat": 173691.36,
        "reduced_vat_ineligibility": false,
        "price_reduced_vat": 172636.36,
        "reduced_vat_eligibility": true,
        "brs_eligibility": false,
        "bare_ownership_eligibility": true,
        "psla_eligibility": false,
        "available_vat_rates": [
            10
        ],
        "available_prices": [
            {
                "vat_rate": 10,
                "price": 180000,
                "price_with_secondary": 187700,
                "price_per_square_meter": 3272.73
            }
        ],
        "price_excluding_vat": 163636.36,
        "price_with_secondary_excluding_vat": 170636.36,
        "unrestricted_distribution": false,
        "living_area": 38.89,
        "additional_area": null,
        "land_area": null,
        "balconies": null,
        "balconies_area": null,
        "terraces": null,
        "terraces_area": null,
        "gardens": 1,
        "gardens_area": 28.02,
        "loggias": null,
        "loggias_area": null,
        "bedrooms": 1,
        "exposure": [
            "north",
            "east"
        ],
        "exposure_display": "Nord / Est",
        "tags": [],
        "tags_display": [],
        "plan3d": "https://...",
        "description": null,
        "status": "available",
        "status_display": "Disponible",
        "documents": [
            {
                "id": 8,
                "name": "Notice A01.pdf",
                "type": "pdf",
                "category": "other",
                "file_url": "https:\/\/storage.adlead.immo\/uploads\/...\/Notice%20A01.pdf",
                "thumbnail_url": "https:\/\/storage.adlead.immo\/uploads\/...\/Notice%20A01.jpg"
            }
        ],
        "plans": [
            {
                "id": 3,
                "name": "Plan A01.pdf",
                "type": "pdf",
                "category": "plan",
                "file_url": "https:\/\/storage.adlead.immo\/uploads\/...\/Plan%20A01.pdf",
                "thumbnail_url": "https:\/\/storage.adlead.immo\/uploads\/...\/Plan%20A01.jpg"
            }
        ],
        "updated_at": "2020-09-09T09:11:32.000000Z"
    }
}

# Créer ou modifier des lots

Permet de créer ou modifier un ou plusieurs lots (batch).

# Requête HTTP

POST https://api.adlead.immo/v1/{tenantKey}/programs/{programId}/lots

# Paramètres d'URL

Nom de la clé Description
{tenantKey} Clé de l'espace client - Détails
{programId} ID du programme

# curl

curl --location --request POST 'https://api.adlead.immo/v1/{tenantKey}/programs/{programId}/lots' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --header 'Content-Length: ###' \
    --header 'X-API-Key: VOTRE_CLE_API' \

# Paramètres de Body

IMPORTANT

Pour la création d'un lot, il est obligatoire de préciser :

  • Un identifiant externe external_id unique
  • Une référence de lot (ou numéro de lot) reference unique
  • Un statut status
  • La nature du lot (lot principal ou lot annexe) is_primary
  • Le type de lot type
  • La typologie du lot (si nécessaire) typology
  • Un prix de vente HT price_excluding_vat

Pour la mise à jour d'un lot, il est obligatoire de préciser :

  • Son identifiant unique Adlead id
  • Un identifiant externe external_id unique

# Exemple

{
  "lots": [
    {
      "id": 12653,
      "parent_lot_id": null,
      "building_id": null,
      "external_id": "123456",
      "reference": "A500",
      "status": "available",
      "is_primary": true,
      "type": "apartment",
      "typology": "T4",
      "subtype": null,
      "price_excluding_vat": 300000,
      "reduced_vat_eligibility": false,
      "brs_eligibility": false,
      "can_be_broadcasted": true,
      "is_broadcastable": true,
      "unrestricted_distribution": false,
      "living_area": 65.23,
      "additional_area": 5.65,
      "land_area": null,
      "balconies": 1,
      "balconies_area": 8.23,
      "terraces": null,
      "terraces_area": null,
      "gardens": null,
      "gardens_area": null,
      "loggias": null,
      "loggias_area": null,
      "bedrooms": null,
      "exposure": [
        "south",
        "west"
      ],
      "plan3d": "https://..."
    },
    {
      "parent_lot_id": 12653,
      "building_id": null,
      "external_id": "123457",
      "reference": "P12",
      "status": "available",
      "is_primary": true,
      "type": "parking",
      "typology": "underground",
      "subtype": null,
      "price_excluding_vat": 10000,
      "reduced_vat_eligibility": false,
      "brs_eligibility": false,
      "can_be_broadcasted": true,
      "is_broadcastable": true
    }
  ]
}

# Body de réponse

{
    "success": true,
    "message": "Batch traité",
    "data": {
        "success": [
            {
                "id": 12653,
                "external_id": "123456",
                "reference": "A500"
            },
            {
                "id": 12670,
                "external_id": "123457",
                "reference": "P12"
            }
        ],
        "errors": []
    }
}

# Supprimer un lot

Permet de supprimer un lot qui n'est pas dans un statut protégé.

# Requête HTTP

DELETE https://api.adlead.immo/v1/{tenantKey}/programs/{programId}/lots/{lotId}

# Paramètres d'URL

Nom de la clé Description
{tenantKey} Clé de l'espace client - Détails
{programId} ID du programme
{lotId} ID du lot

# curl

curl --location --request DELETE 'https://api.adlead.immo/v1/{tenantKey}/programs/{programId}/lots/{lotId}' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --header 'Content-Length: ###' \
    --header 'X-API-Key: VOTRE_CLE_API' \

# Modèle

Champ Type Description Exemple Format des données
id int ID du lot 1
primpromo_id int ID Primpromo 1
parent_lot_id int ID du lot parent 1
building object Bâtiment {"id": 10, "name": "La Riviera"}
reference string Référence unique du lot A01
can_be_broadcasted boolean Indique si le lot peut être diffusé, en prenant en compte sa disponibilité et autres critères pertinents. true false true = Toutes conditions remplies pour la diffusion / false = Au moins une condition non remplie.
is_broadcastable boolean Indique si le lot est techniquement prêt à être diffusé, indépendamment de sa disponibilité. true false true = Lot prêt pour diffusion sous l'aspect technique / false = Lot non prêt techniquement.
is_primary boolean Lot principal true false true = Lot principal / false = Lot annexe
type string Type de bien apartment Accéder au tableau
type_display string Type de bien (affichage) Appartement Accéder au tableau
typology string Typologie du bien T2 Accéder au tableau
typology_display string Typologie du bien (affichage) 2 pièces Accéder au tableau
subtype string Sous-type de bien contemporary-house Accéder au tableau
subtype_display string Sous-type de bien (affichage) Maison contemporaine Accéder au tableau
floors int Nombre d'étage (maison seulement) 5
level string Niveau structurel (position technique verticale) R+1 Accéder au tableau
level_type string Type de niveau ground-floor Accéder au tableau
level_display string Niveau (affichage) Rez-de-chaussée 1er étage Sous-sol -2
reduced_vat_eligibility boolean Éligibile à la TVA réduite true false true = éligible
brs_eligibility boolean Éligibile au BRS true false true = éligible
bare_ownership_eligibility boolean Éligibile à la Nue-Propriété true false true = éligible
psla_eligibility boolean Éligibile au PSLA true false true = éligible
available_vat_rates array Liste des TVA disponibles [20, 10, 5.5]
available_prices array Liste des prix disponibles
price_excluding_vat float Prix de vente HT 250000.00
price_including_vat deprecated float ⚠️ déprécié Prix de vente TVA 20% 300000.00 Déprécié : Utiliser le champ available_prices
price_with_secondary_including_vat deprecated float ⚠️ déprécié Prix de vente TVA 20% lots annexes inclus 350000.00 Déprécié : Utiliser le champ available_prices
price_with_secondary_reduced_vat deprecated float ⚠️ déprécié Prix de vente TVA 5,5% lots annexes inclus 300000.00 Déprécié : Utiliser le champ available_prices
price_reduced_vat deprecated float ⚠️ déprécié Prix de vente TVA 5,5% 263750.00 Déprécié : Utiliser le champ available_prices
price_excluding_vat_per_square_meter deprecated float ⚠️ déprécié Prix HT du m² 4450.44 Déprécié : Utiliser le champ available_prices
price_including_vat_per_square_meter deprecated float ⚠️ déprécié Prix TVA 20% du m² 4450.44 Déprécié : Utiliser le champ available_prices
price_reduced_vat_per_square_meter deprecated float ⚠️ déprécié Prix TVA 5,5% du m² 4450.44 Déprécié : Utiliser le champ available_prices
unrestricted_distribution boolean Lot en grille ouverte true false true = disponible en grille ouverte
living_area float Surface habitable 68.89
additional_area float Surface supplémentaire (< 1,80m) 5.56
land_area float Surface du terrain 350.00
balconies int Nombre de balcons 2
balconies_area float Surface des balcons 9.08
terraces int Nombre de terrasses 1
terraces_area float Surface des terrasses 12.23
gardens int Nombre de jardins 1
gardens_area float Surface des jardins 22.56
loggias int Nombre de loggias 1
loggias_area float Surface des loggias 7.49
bedrooms int Nombre de chambres 1
exposure array Orientations ["south", "west"] north east south west
exposure_display string Orientations (affichage) Sud / Ouest
tags array Tags ["duplex"] Accéder au tableau
tags_display array Tags (affichage) ["Duplex"] Accéder au tableau
plan3d string Lien vers la maquette 3D https://...
actable_date string Date d'actabilité 2024-01-01
inherited_actable_date string Date d'actabilité héritée
delivery_date string ⚠️ déprécié 2024-01-01
real_delivery_date string Date de livraison réelle 2024-01-01
inherited_delivery_date string Date de livraison réelle héritée 2024-01-01
description string Texte descriptif Appartement 2 pièces d'une surface de 47,03 m²...
status string Statut / Disponibilité available Accéder au tableau
status_display string Statut / Disponibilité (affichage) Disponible Accéder au tableau
documents array Liste des documents
plans array Liste des plans
lots_related array Lots associés/jumelés
updated_at string Dernière mise à jour 2020-09-04T10:20:04.000000Z ISO 8601

# Annexes

# Types, typlogies et sous-types de biens

Liste des types, typologies et sous-types de biens

DETAILS 
[
  {
    "key": "apartment",
    "name": "Appartement",
    "typologies": [
      {
        "key": "T1",
        "name": "Studio"
      },
      {
        "key": "T1B",
        "name": "1 pièce bis"
      },
      {
        "key": "T2",
        "name": "2 pièces"
      },
      {
        "key": "T3",
        "name": "3 pièces"
      },
      {
        "key": "T4",
        "name": "4 pièces"
      },
      {
        "key": "T5",
        "name": "5 pièces"
      },
      {
        "key": "T6",
        "name": "6 pièces"
      }
    ],
    "subtypes": [
      {
        "key": "duplex",
        "name": "Duplex"
      },
      {
        "key": "triplex",
        "name": "Triplex"
      }
    ]
  },
  {
    "key": "house",
    "name": "Maison",
    "typologies": [
      {
        "key": "T1",
        "name": "1 pièce"
      },
      {
        "key": "T2",
        "name": "2 pièces"
      },
      {
        "key": "T3",
        "name": "3 pièces"
      },
      {
        "key": "T4",
        "name": "4 pièces"
      },
      {
        "key": "T5",
        "name": "5 pièces"
      },
      {
        "key": "T6",
        "name": "6 pièces"
      },
      {
        "key": "T7",
        "name": "7 pièces"
      },
      {
        "key": "T8",
        "name": "8 pièces"
      },
      {
        "key": "T9",
        "name": "9 pièces"
      },
      {
        "key": "T10",
        "name": "10 pièces"
      }
    ],
    "subtypes": [
      {
        "key": "semi-detached-house",
        "name": "Maison mitoyenne"
      },
      {
        "key": "architectural-house",
        "name": "Maison d'architecte"
      },
      {
        "key": "contemporary-house",
        "name": "Maison contemporaine"
      },
      {
        "key": "townhouse",
        "name": "Maison de ville"
      },
      {
        "key": "traditional-house",
        "name": "Maison traditionnelle"
      },
      {
        "key": "pavilion",
        "name": "Pavillon"
      },
      {
        "key": "chalet",
        "name": "Chalet"
      },
      {
        "key": "villa",
        "name": "Villa"
      },
      {
        "key": "semi-detached-villa",
        "name": "Villa jumelée"
      }
    ]
  },
  {
    "key": "parking",
    "name": "Parking",
    "typologies": [
      {
        "key": "underground",
        "name": "Souterrain"
      },
      {
        "key": "box",
        "name": "Box"
      },
      {
        "key": "surface",
        "name": "Surface"
      },
      {
        "key": "above-ground",
        "name": "Aérien"
      }
    ],
    "subtypes": [
      {
        "key": "2-wheel-parking",
        "name": "Parking 2 roues"
      },
      {
        "key": "adapted-pmr",
        "name": "Adapté PMR"
      },
      {
        "key": "double-parking",
        "name": "Parking double"
      }
    ]
  },
  {
    "key": "garage",
    "name": "Garage",
    "typologies": [],
    "subtypes": [
      {
        "key": "adapted-pmr",
        "name": "Adapté PMR"
      }
    ]
  },
  {
    "key": "basement",
    "name": "Cave",
    "typologies": [],
    "subtypes": []
  },
  {
    "key": "cellar",
    "name": "Cellier",
    "typologies": [],
    "subtypes": []
  },
  {
    "key": "commercial-space",
    "name": "Local commercial",
    "typologies": [],
    "subtypes": []
  },
  {
    "key": "office-space",
    "name": "Bureau",
    "typologies": [],
    "subtypes": []
  },
  {
    "key": "land",
    "name": "Terrain",
    "typologies": [],
    "subtypes": []
  }
]

# Niveaux

Liste des niveaux structurels

DETAILS 
[
  {
    "key": "R-5"
  },
  {
    "key": "R-4"
  },
  {
    "key": "R-3"
  },
  {
    "key": "R-2"
  },
  {
    "key": "R-1"
  },
  {
    "key": "R+0"
  },
  {
    "key": "R+1"
  },
  {
    "key": "R+2"
  },
  {
    "key": "R+3"
  },
  {
    "key": "R+4"
  },
  {
    "key": "R+5"
  },
  {
    "key": "R+6"
  },
  {
    "key": "R+7"
  },
  {
    "key": "R+8"
  },
  {
    "key": "R+9"
  },
  {
    "key": "R+10"
  },
  {
    "key": "R+11"
  },
  {
    "key": "R+12"
  },
  {
    "key": "R+13"
  },
  {
    "key": "R+14"
  },
  {
    "key": "R+15"
  },
  {
    "key": "R+16"
  },
  {
    "key": "R+17"
  },
  {
    "key": "R+18"
  },
  {
    "key": "R+19"
  },
  {
    "key": "R+20"
  }
]

# Type de niveaux

Liste des types de niveaux

DETAILS 
[
  {
    "key": "basement",
    "name": "Sous-sol"
  },
  {
    "key": "ground-floor",
    "name": "Rez-de-chaussée"
  },
  {
    "key": "garden-floor",
    "name": "Rez-de-jardin"
  },
  {
    "key": "podium-floor",
    "name": "Rez-de-dalle"
  },
  {
    "key": "standard",
    "name": "Étage courant"
  },
  {
    "key": "attic",
    "name": "Attique"
  }
]

# Tags

Liste des tags

DETAILS 
[
  {
    "key": "adapted-pmr",
    "name": "Adapté PMR"
  },
  {
    "key": "alcove",
    "name": "Alcôve"
  },
  {
    "key": "duplex",
    "name": "Duplex"
  },
  {
    "key": "triplex",
    "name": "Triplex"
  },
  {
    "key": "rooftop",
    "name": "Rooftop"
  },
  {
    "key": "not-overlooked",
    "name": "Sans vis-à-vis"
  },
  {
    "key": "RDJ",
    "name": "Rez-de-jardin"
  },
  {
    "key": "RDC",
    "name": "Rez-de-chaussée"
  },
  {
    "key": "balcony",
    "name": "Balcon"
  },
  {
    "key": "terrace",
    "name": "Terrasse"
  },
  {
    "key": "garden",
    "name": "Jardin"
  },
  {
    "key": "southern-exposure",
    "name": "Orientation Sud"
  }
]

# Statuts

Liste des statuts

DETAILS 
[
  {
    "key": "available",
    "name": "Disponible"
  },
  {
    "key": "option",
    "name": "Optionné"
  },
  {
    "key": "pre-booked",
    "name": "Pré-réservé"
  },
  {
    "key": "booked",
    "name": "Réservé"
  },
  {
    "key": "sold",
    "name": "Vendu"
  },
  {
    "key": "unavailable",
    "name": "Non disponible à la vente"
  }
]

← Plans 2D des lots →