---
title: "Annonce par lien ou identifiant, en lot"
method: POST
path: "/annonces/lot"
---

# Annonce par lien ou identifiant, en lot

`POST /annonces/lot`

## Request

- Base URL: `https://pillr.fr/api/v1`
- URL: `https://pillr.fr/api/v1/annonces/lot`
- Auth: HTTP bearer

Annonce par lien ou identifiant pour 100 éléments au plus en un appel : chaque élément est servi ou refusé seul, avec son code d'erreur, et seuls les éléments servis sont débités. Fiche complète d'une annonce de vente analysée, retrouvée par son lien Leboncoin, BienIci ou SeLoger, ou par son identifiant : faits du bien et détails du portail (honoraires, taxe foncière, copropriété, équipements), vendeur professionnel nommé avec son enseigne, son SIREN et son mandat, photos et description, analyse complète (score et sous-scores, verdict, forces et faiblesses, leviers et cibles de négociation, loyer, rendements recalculés, budget, travaux par poste lus sur les photos, stratégie locative, régime fiscal), valeurs brutes du modèle à côté des valeurs recalculées, coût de sortie de passoire, échéance de location, historique des prix et diffusion en nombres. Données brutes du portail avec inclure=brut, pour un professionnel. Rien n'est débité si l'annonce est absente ou pas encore analysée. Coût : 3 crédits par élément rendu.

## Request body

- object
  - `elements` object[], required: Les entrées de l'opération unitaire, 100 au plus.
    - `id` string: Identifiant de l'annonce : lbc:<numéro>, bienici:<identifiant>, seloger:<numéro> ou identifiant Pillr.
    - `url` string, uri: Lien de l'annonce sur le portail d'origine.
    - `inclure` 'brut': brut : ajoute les données brutes du portail (vendeur professionnel seulement).

## Response `200`

Réponse servie et débitée (sauf réponse identique déjà servie dans les 24 h).

- object
  - `resultats` union[], required: Un résultat par élément, dans l'ordre de l'entrée : la sortie de l'opération, ou l'erreur de cet élément.
    - union
      - object
        - `index` integer, required
        - `ok` true, required
        - `donnees` object, required
          - `id` string, required: Identifiant Pillr de l'annonce.
          - `id_portail` string, nullable, required: Identifiant chez le portail (lbc:<n>, bienici:<id>, seloger:<id>), servi avec la portée lien_origine.
          - `lien` string, nullable, required: Lien d'origine de l'annonce, servi avec la portée lien_origine.
          - `source` string, required
          - `statut` 'actif' | 'retire' | 'masque', required: actif : en ligne ; retire : retirée du portail ; masque : ni l'un ni l'autre (contrôle en cours).
          - `actif` boolean, required
          - `type` string, required
          - `neuf_ancien` string, nullable, required
          - `commune` string, nullable, required
          - `code_postal` string, nullable, required
          - `insee` string, nullable, required
          - `departement` string, nullable, required
          - `region` string, nullable, required
          - `position` object, nullable, required: Position telle que le portail la donne, avec sa précision.
            - `lat` number, required
            - `lon` number, required
            - `precision` string, required: adresse, approchee, centre_commune ou inconnue.
          - `prix` number, nullable, required
          - `prix_m2` number, nullable, required: Prix divisé par la surface (jamais la valeur du portail).
          - `prix_m2_portail` number, nullable, required: Prix au m² affiché par le portail, servi à côté.
          - `surface` number, nullable, required
          - `pieces` number, nullable, required
          - `chambres` number, nullable, required
          - `etage` number, nullable, required
          - `nb_etages` number, nullable, required
          - `salles_de_bain` number, nullable, required
          - `salles_d_eau` number, nullable, required
          - `terrain_m2` number, nullable, required
          - `jardin_privatif_m2` number, nullable, required
          - `terrain_portail_m2` number, nullable, required
          - `terrain_suspect` boolean, nullable, required: Vrai si le terrain d'une maison est plus petit que sa surface habitable.
          - `annee_construction` number, nullable, required
          - `dpe` object, required
            - `etiquette` 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G', nullable, required
            - `conso_kwh_m2_an` number, nullable, required
            - `ges` 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G', nullable, required
            - `ges_kg_m2_an` number, nullable, required
            - `ges_statut` 'non_soumis' | 'vierge', nullable, required
            - `interdiction_location` string, nullable, required: Premier jour où la location d'un logement de cette classe est interdite (AAAA-MM-JJ), selon le calendrier de la loi Climat et résilience en métropole (G 2025, F 2028, E 2034). null : classe sans échéance, DPE absent, ou adresse hors de la métropole (le calendrier des outre-mer n'est pas servi).
            - `mois_restants` integer, nullable, required: Mois pleins avant l'échéance ; 0 quand l'interdiction est déjà en vigueur ; null sans échéance.
          - `equipements` object, required
            - `ascenseur` boolean, nullable, required
            - `balcon` boolean, nullable, required
            - `cave` boolean, nullable, required
            - `parking` boolean, nullable, required
            - `meuble` boolean, nullable, required
            - `terrasse` boolean, nullable, required
            - `jardin` boolean, nullable, required
            - `piscine` boolean, nullable, required
            - `garage` boolean, nullable, required
            - `cuisine_equipee` boolean, nullable, required
            - `visite_virtuelle` boolean, nullable, required
            - `orientation` string, nullable, required
            - `chauffage` string, nullable, required
            - `chauffage_mode` string, nullable, required
            - `liste` string[], required: Équipements listés par le portail.
          - `details_portail` object, required
            - `prix_hors_honoraires` number, nullable, required
            - `honoraires` number, nullable, required
            - `honoraires_a_charge` string, nullable, required
            - `taxe_fonciere` number, nullable, required
            - `charges_copro_annuelles` number, nullable, required
            - `charges_suspectes` boolean, nullable, required: Vrai si les charges annuelles d'un appartement en copropriété semblent mensuelles.
            - `budget_energie_min` number, nullable, required
            - `budget_energie_max` number, nullable, required
            - `lots_copro` number, nullable, required
            - `procedure_copro` boolean, nullable, required
            - `en_copro` boolean, nullable, required
          - `type_vendeur` 'pro' | 'particulier' | 'inconnu', required: Statut du vendeur déclaré par le portail : pro (agence, réseau, promoteur), particulier, ou inconnu.
          - `annonceur` object, required: Le vendeur : un professionnel est servi en entier (nom, enseigne, SIREN, mandat, coordonnées professionnelles), un particulier jamais.
            - `type_vendeur` 'pro' | 'particulier' | 'inconnu', required: Statut du vendeur déclaré par le portail : pro (agence, réseau, promoteur), particulier, ou inconnu.
            - `nom` string, nullable, required
            - `enseigne` string, nullable, required
            - `siren` string, nullable, required
            - `mandat` string, nullable, required: Type de mandat publié (simple, exclusif) ; null si inconnu.
            - `telephone` string, nullable, required: Téléphone professionnel publié par le portail ; jamais celui d'un particulier.
            - `email` string, nullable, required: Adresse électronique professionnelle publiée par le portail ; jamais celle d'un particulier.
          - `titre` string, nullable, required
          - `description` string, nullable, required: Description du portail, en texte ; les coordonnées d'un vendeur qui n'est pas un professionnel en sont retirées.
          - `photos` string[], required: Liens des photos chez le portail.
          - `premiere_parution` object, required
            - `date` string, nullable, required
            - `estimee` boolean, required: Vrai quand la date est une estimation (portail qui ne la publie pas).
          - `vu_le` string, nullable, required
          - `retire_le` string, nullable, required
          - `entree_le` string, nullable, required
          - `maj_le` string, nullable, required
          - `bien_uid` string, nullable, required: Bien dédoublonné qui porte l'annonce (opération bien).
          - `analyse` object, required
            - `score` number, nullable, required: Score Pillr sur 100.
            - `sous_scores` object, required
              - …
            - `profil` string, nullable, required
            - `verdict` string, nullable, required
            - `forces` string[], required
            - `faiblesses` string[], required
            - `recommandation` string, nullable, required
            - `leviers` string[], required: Leviers de négociation.
            - `negociation` object, required
              - …
            - `loyer` object, required
              - …
            - `rendement_brut` number, nullable, required: Rendement brut en %, recalculé depuis le loyer estimé et le prix.
            - `rendement_brut_moteur` number, nullable, required
            - `rendement_net` number, nullable, required: Rendement net en %, recalculé sur le budget total.
            - `rendement_net_moteur` number, nullable, required
            - `frais_notaire` number, nullable, required: Frais de notaire au taux de l'ancien, en euros.
            - `frais_notaire_moteur` number, nullable, required
            - `budget_total` number, nullable, required: Prix, frais de notaire et milieu de la fourchette des travaux, en euros ; null si les travaux ne sont pas évalués.
            - `budget_total_moteur` number, nullable, required: Budget écrit par le modèle : son sens varie selon les analyses, à lire avec prudence.
            - `etat_visuel` number, nullable, required: État visuel lu sur les photos, sur 100 ; null avec des photos de catalogue.
            - `photos` object, required
              - …
            - `travaux` object, required
              - …
            - `strategie_locative` string, nullable, required
            - `strategie_locative_raison` string, nullable, required
            - `regime_fiscal` string, nullable, required
            - `regime_fiscal_fiable` boolean, required: Faux quand le régime vaut LMNP_REEL : le modèle le propose sur presque toutes les analyses.
            - `regime_fiscal_raison` string, nullable, required
            - `economie_fiscale_an` number, nullable, required
            - `taxe_fonciere_moteur` number, nullable, required
            - `charges_annuelles_moteur` number, nullable, required
            - `drapeaux` object, required
              - …
            - `confiance` object, required
              - …
            - `completude` 'haute' | 'moyenne' | 'basse', nullable, required
            - `completude_criteres` object, required
              - …
            - `sources` string[], required
            - `moteur` object, required
              - …
            - `qualite` object, required: Ce qui permet de juger la valeur : nombre, provenance, incertitude, drapeaux, date et source.
              - …
          - `sortie_passoire` object, nullable, required: Coût de sortie d'une passoire (classe E, F ou G) vers D, C ou B, mesuré sur les audits énergétiques réglementaires de l'ADEME pour des logements comparables. null hors des classes E à G, pour un type de logement sans comparable, ou hors de la métropole.
            - `classe_depart` 'E' | 'F' | 'G', required
            - `cibles` object[], required
              - …
            - `lecture` string, required: Ce que mesure le chiffre : une estimation d'auditeur, pas un devis.
            - `source` string, required
          - `prix_historique` object[], required: Variations de prix détectées, dédoublonnées au jour ; le détail est dans vie_annonce.
            - `le` string, required
            - `de` number, nullable, required
            - `a` number, required
            - `doublon_probable` boolean, required
          - `diffusion` object, nullable, required: Le même bien chez d'autres annonceurs, en nombres ; les agences nommées sont dans vie_annonce.
            - `annonces` integer, required
            - `agences` integer, required
            - `particuliers` integer, required
            - `portails` integer, required
            - `prix_min` number, nullable, required
            - `prix_max` number, nullable, required
            - `premiere_parution` string, nullable, required
          - `brut` object, nullable, required: Données brutes du portail, avec inclure=brut, pour un vendeur professionnel seulement ; null sinon.
          - `drapeaux` string[], required: Ce qui doit faire lire l'annonce avec prudence ; vide si rien.
          - `qualite` object, required: Ce qui permet de juger la valeur : nombre, provenance, incertitude, drapeaux, date et source.
            - `n` integer, nullable, required: Nombre d'observations derrière la valeur ; null si sans objet.
            - `provenance` 'mesure' | 'estime', nullable, required: mesure : observé sur la donnée ; estime : modèle, barème ou imputation ; null : sans objet.
            - `incertitude` object, nullable, required: Incertitude de la valeur : fourchette et demi-largeur.
              - …
            - `drapeaux` string[], required: Ce qui doit faire lire la valeur avec prudence ; vide si rien.
            - `methode` string, nullable, required: Méthode de calcul ou de rattachement, en clair.
            - `donnees_du` string, nullable, required: Date de la donnée (AAAA-MM-JJ ou horodatage ISO 8601).
            - `source` string, required: Source publique ou moteur Pillr, en clair.
      - object
        - `index` integer, required
        - `ok` false, required
        - `erreur` object, required
          - `code` string, required: Code stable de l'erreur (lib/api/v1/erreurs.ts).
          - `detail` string, required
  - `n_ok` integer, required
  - `n_erreurs` integer, required
  - `credits` object, required: Crédits débités par cet appel (réservés, pour une tâche en cours), et crédits encore utilisables ce mois avant la coupure : crédits offerts, crédits inclus du mois et crédits facturables sous le plafond de dépense (null si inconnus ou en bac à sable).
    - `debites` integer, required
    - `restants` integer, nullable, required

## Other responses

- `400`: Paramètres invalides
- `401`: Clé d'API absente
- `402`: Crédits insuffisants ; Carte requise ; Plafond mensuel de dépense atteint
- `403`: Portée insuffisante
- `404`: Ressource absente : rien n'est débité
- `429`: Trop de requêtes par minute
- `500`: Erreur interne
- `503`: API indisponible ; Donnée momentanément indisponible

---

[API](https://skmtc.dev/pillr/apis/api-pillr.md) · [All operations](https://skmtc.dev/pillr/apis/api-pillr/llms.txt) · [OpenAPI document](https://skmtc.dev/pillr/apis/api-pillr/revisions/218b2866bd6c?raw)