Idealista API anbinden: Node.js-Tutorial für Spanien & Portugal

Warum Idealista — und was ist Idealista Pro?

Idealista ist in Spanien, Portugal und Italien Marktführer im Suchvolumen. Wer in diesen Märkten verkauft, mietet oder vermarktet, hat ohne Idealista nur eingeschränkte Reichweite — Funda in den Niederlanden, ImmoScout in DACH, Idealista im südeuropäischen Raum. Für Premium- und Luxus-Maklerbüros mit Ferienimmobilien (Mallorca, Costa Brava, Algarve, Alentejo) ist die Plattform Pflicht.

Idealista Pro ist die B2B-Schiene: ein dediziertes Backend für gewerbliche Anbieter mit kostenpflichtigen Listing-Slots, Bulk-Upload, Statistiken und API-Zugang. Es gibt zwei Wege, Inserate dort hineinzubekommen:

• XML-Feed nach Idealista-Pro-Standard, der per FTP oder URL bereitgestellt wird und alle paar Stunden eingelesen wird. Klassisch, robust, aber zeitverzögert.
• REST-API mit OAuth 2.0, mit der Properties einzeln in Echtzeit hochgeladen, aktualisiert und gelöscht werden. Modern, flexibel — und der Fokus dieses Tutorials.

Zugang beantragen und Vertragsmodelle

Die API ist nicht offen — du brauchst einen aktiven Idealista-Pro-Vertrag mit explizit freigeschaltetem API-Zugang. Drei Werte bekommst du nach Freischaltung:

• API-Key (auch „client_id") — identifiziert deinen Account.
• API-Secret (auch „client_secret") — geheim, für die Token-Anforderung.
• Account-Identifier — die interne ID deines Maklerbüros bei Idealista, die in einigen Request-Headern erwartet wird.

Praxis-Tipp: Lass dir vom Idealista-Account-Manager das Test-Environment einrichten, bevor du in Produktion gehst. Die Sandbox-Antworten sind realistisch und du verbrennst kein echtes Budget, falls Test-Listings hochlaufen.

OAuth 2.0 mit Client-Credentials in Node.js

Im Gegensatz zu ImmoScout24 (OAuth 1.0a) und OnOffice (eigene HMAC-Signatur) nutzt Idealista den modernen OAuth-2.0-Client-Credentials-Flow. Das macht den Auth-Code überschaubar:

// idealista-client.js
const TOKEN_URL = 'https://api.idealista.com/oauth/token';
const API_BASE = 'https://api.idealista.com/3.5';

let cachedToken = null;
let tokenExpiresAt = 0;

async function getToken() {
    if (cachedToken && Date.now() < tokenExpiresAt - 30_000) return cachedToken;

    const credentials = Buffer.from(
        `${process.env.IDEALISTA_KEY}:${process.env.IDEALISTA_SECRET}`
    ).toString('base64');

    const res = await fetch(TOKEN_URL, {
        method: 'POST',
        headers: {
            'Authorization': `Basic ${credentials}`,
            'Content-Type': 'application/x-www-form-urlencoded',
        },
        body: 'grant_type=client_credentials&scope=publish',
    });

    if (!res.ok) throw new Error(`Idealista token error: ${res.status} ${await res.text()}`);
    const data = await res.json();
    cachedToken = data.access_token;
    tokenExpiresAt = Date.now() + data.expires_in * 1000;
    return cachedToken;
}

export async function idealistaRequest(path, { method = 'GET', body } = {}) {
    const token = await getToken();
    const res = await fetch(`${API_BASE}${path}`, {
        method,
        headers: {
            'Authorization': `Bearer ${token}`,
            'Content-Type': 'application/json',
            'Accept-Language': 'es-ES',
        },
        body: body ? JSON.stringify(body) : undefined,
    });
    if (!res.ok) throw new Error(`Idealista ${res.status}: ${await res.text()}`);
    return res.status === 204 ? null : res.json();
}

Properties hochladen und aktualisieren

Das Property-Schema ist umfangreich — Idealista unterstützt 30+ Sub-Typen (Wohnung, Haus, Grundstück, Gewerbe, Garage usw.), jeder mit eigenen Pflichtfeldern. Hier das Beispiel für eine Verkaufs-Wohnung in Mallorca:

// create-property.js
import { idealistaRequest } from './idealista-client.js';

const property = {
    propertyType: 'HOMES',
    propertySubtype: 'FLAT',
    operation: 'SALE',
    externalReference: 'EXT-2026-MAL-1042',
    price: 645000,
    currency: 'EUR',
    address: {
        street: 'Calle de la Mar',
        number: '12',
        flat: '3B',
        postalCode: '07012',
        municipality: 'Palma de Mallorca',
        province: 'Islas Baleares',
        country: 'es',
    },
    description: {
        es: 'Piso luminoso en el casco antiguo de Palma...',
        en: 'Bright apartment in the old town of Palma...',
        de: 'Helle Wohnung in der Altstadt von Palma...',
    },
    rooms: 3,
    bathrooms: 2,
    builtArea: 95,
    livingArea: 88,
    constructionYear: 1928,
    condition: 'GOOD',
    energyCertification: {
        consumption: { value: 89, unit: 'kWh/m2 year', rating: 'C' },
        emissions: { value: 18, unit: 'kg CO2/m2 year', rating: 'C' },
    },
    features: ['BALCONY', 'AIR_CONDITIONING', 'HEATING_INDIVIDUAL'],
};

// PUT mit externalReference als ID = idempotenter Upsert
const result = await idealistaRequest(
    `/properties/${property.externalReference}`,
    { method: 'PUT', body: property }
);
console.log('Idealista Property ID:', result.id);

Drei Eigenheiten, die in der Doku auf den zweiten Blick stehen:

• externalReference ist der zentrale Idempotenz-Anker — wenn du dasselbe PUT mit demselben Referenz-Wert erneut schickst, aktualisiert Idealista das bestehende Property. Setze hier eine stabile ID aus deinem CRM (Propstack-Property-ID, OnOffice-Objektnummer).
• Beschreibungen als Sprach-Objekt — Idealista zeigt automatisch die richtige Sprache je nach Besucherland. Pflicht ist nur die Markt-Sprache (für ES-Listings also es), zusätzliche Sprachen sind ein massiver SEO-Hebel für internationale Käufer.
• Energie-Zertifikat — sowohl in Spanien als auch in Portugal Pflicht. Listings ohne energyCertification-Block werden in vielen Regionen automatisch als „inkomplett" markiert und in der Suchergebnis-Reihenfolge benachteiligt.

Bilder und virtuelle Touren

Bilder gehen nicht im Property-Payload, sondern als separate Multipart-Uploads:

// upload-images.js
import fs from 'node:fs';
import FormData from 'form-data';
import { getToken } from './idealista-client.js';

export async function uploadImages(propertyRef, imagePaths) {
    const token = await getToken();
    for (const [index, imagePath] of imagePaths.entries()) {
        const form = new FormData();
        form.append('image', fs.createReadStream(imagePath));
        form.append('order', index + 1);
        form.append('isMainImage', index === 0 ? 'true' : 'false');

        const res = await fetch(
            `https://api.idealista.com/3.5/properties/${propertyRef}/images`,
            {
                method: 'POST',
                headers: { 'Authorization': `Bearer ${token}`, ...form.getHeaders() },
                body: form,
            }
        );
        if (!res.ok) throw new Error(`Image upload failed: ${await res.text()}`);
        console.log(`Uploaded image ${index + 1}/${imagePaths.length}`);
    }
}

Virtuelle Touren (Matterport, EyeSpy360) werden über das Feld virtualTourUrl im Property-Body referenziert — Idealista bettet sie dann direkt im Listing ein. Plant ihr Touren parallel zur Listing-Erstellung, dann achtet auf öffentlich erreichbare URLs ohne Login-Walls.

Regionen, Sprachen und Sub-Markets

Idealista ist auf den ersten Blick eine Plattform, intern aber drei: idealista.com (Spanien), idealista.pt (Portugal), idealista.it (Italien). Properties werden anhand des country-Feldes im address-Block dem richtigen Sub-Market zugeordnet. Wer Häuser an der Algarve verkauft, setzt country: 'pt'; für Mallorca country: 'es'.

Sprach-Strategie aus der Praxis:

• Markt-Sprache immer voll — ES-Listings mit kompletter spanischer Beschreibung, PT-Listings mit voller portugiesischer Beschreibung.
• Englisch zweite Priorität — internationale Käufer kommen via Google, das Idealista-Englisch-Listings bevorzugt indexiert.
• Deutsch dritte Priorität — wer aktiv DACH-Käufer anspricht (Ferien-Immobilien-Käufer), wird mit deutschen Beschreibungen besser geklickt.

Praxis-Stolpersteine

1. 401 Unauthorized trotz frischem Token

Häufig ein Scope-Problem: Der Standard-Token (scope=read) kann nur lesen. Für Property-Uploads explizit scope=publish anfordern.

2. Property erscheint nicht im Frontend

Idealista hat einen Approval-Workflow: Neue Properties werden zunächst manuell geprüft (Bildqualität, Texte, Energie-Zertifikat), erst dann live geschaltet. Plan 4-24 Stunden Latenz ein. Status abfragen über GET /properties/{ref}/status.

3. Bilder verschwinden nach erstem Upload

Wenn du das Property mehrfach per PUT aktualisierst und vergisst, die Bilder erneut zuzuordnen, werden sie nicht automatisch übernommen. Eleganter: Bilder über separate order-Felder verwalten und nach jedem Property-Update einen Image-Sync-Schritt durchlaufen.

4. Region-Mismatch

Wer eine Property in Mallorca mit province: 'Mallorca' markiert, bekommt einen 422. Korrekt ist province: 'Islas Baleares'. Vor dem Upload immer gegen die offizielle Idealista-Region-Liste validieren (separater /regions-Endpoint).

Wann sich die Integration für deutsche Büros lohnt

Eine direkte Idealista-API-Anbindung lohnt sich, wenn:

• du mehr als 10 Auslands-Listings im Jahr in ES/PT/IT vermarktest,
• dein Inventar sich schnell ändert (Preis-Adjustments, Reservierungen, Verkäufe),
• du parallel auf mehreren Portalen (Idealista + Rightmove + ImmoScout) publizieren willst und Drift vermeiden musst,
• du eine zentrale Reporting-Pipeline brauchst.

Bei wenigen Einzel-Listings ist der manuelle Upload über das Idealista-Pro-Web-Backend günstiger. Sobald aber mehrere Maklerbüros oder mehrere Dutzend Properties zu pflegen sind, spart eine API-Integration schnell mehr als sie kostet.

Wir bei DevNest bauen solche Multi-Portal-Bridges (CRM → IS24 + Idealista + Rightmove + Savills) als Teil unserer Propstack-Integrationen. Wenn du an einer ähnlichen Lösung arbeitest: Projekt anfragen.

Weitere Themen: Propstack-Webhooks zu Portalen pushen · ImmoScout24-API anbinden · OnOffice-API anbinden · CRM-Vergleich Propstack vs OnOffice vs FlowFact