Send a property to Vesta from your system, and (optionally) publish it to your website, Fotocasa and Idealista — all in one HTTPS call.

• Base URL: https://vesta-crm.com
• Content type: application/json
• Auth: per-account Bearer token
• Endpoints:
  • GET /api/listings/external/validate — check your token (no data created)
  • POST /api/listings/external/ingest — send/update a property (and, optionally, its owner contact)

You send one flat object describing the property. You don't need to know anything about how Vesta stores it internally — just send the fields you have. The only field you must keep stable across calls is reference.

Publishing to Fotocasa and Idealista is documented separately. Those calls put ads live, take them down and spend the agency's portal slots, so they are not part of this page. If your integration needs them, ask Vesta for the portal publishing reference.

1. Authentication#

Every request needs:

1. The account in the URL: ?account=<accountId>.
2. Your secret token, as a header (preferred) or query param:
   • Authorization: Bearer <token>
   • or ?token=<token>

POST /api/listings/external/ingest?account=<ACCOUNT_ID>
Authorization: Bearer <token>
Content-Type: application/json

Vesta gives you the token and the account id. Until the token is set, the account returns 401.

Validate your token#

Before sending anything, you can confirm an agency's token is valid — useful for a "connect your CRM" step. It creates nothing.

GET /api/listings/external/validate?account=<ACCOUNT_ID>
Authorization: Bearer <token>

• 200 { "valid": true } — token is good.
• 401 { "valid": false } — missing/wrong token, or the API isn't enabled for this account.

Who is pushing: the acting user (optional)#

The token identifies the agency, not the person. If your system has its own logged-in users, send who they are: Vesta assigns the property to that agent instead of the account's default one, and any owner contact it creates becomes theirs too.

X-Partner-User-Email: maria@agencia.com     ← what we match on
X-Partner-User-Id:    4821                  ← your own id, for our logs

(X-Betterplace-User-Email / X-Betterplace-User-Id are accepted as aliases.)

• The address doesn't have to match exactly. We compare it against the active users of that same account and take the closest one, so maria.garcia@tusistema.com still finds maria@agencia.com. Capitals, dots and +tags are ignored, and the agent's name counts too (mgarcia@ finds "María García").
• Never a guess between colleagues. If two agents are equally close, nobody is picked — better the default agent than the wrong one.
• A miss is never an error. The property still comes in, assigned to the account's default agent, and the response carries "agentMatched": false so you can spot users you haven't mapped yet. The field only appears when you sent the header.
• An explicit agentId in the body wins over the header.
• New listings only. Re-sending an existing reference never moves the property to a different agent — the agency may have reassigned it on purpose.

2. POST /api/listings/external/ingest#

Creates a property, or updates it if you reuse a reference you've sent before (see Idempotency). Send only the fields you have — anything you omit keeps its previous value.

Required fields#

Everything else (all optional)#

Status & text#

Type#

Size & rooms#

Address & location#

Condition#

Amenities#

disabledAccessible = adapted for reduced mobility; feeds Idealista's adapted-access and adapted-use flags.

Community & building amenities (Fotocasa)#

All boolean unless noted. Map to Fotocasa community/luxury features.

hasHeating is whether a heating system exists; heatingType is the fuel/method. terraceSize complements the terrace boolean. mainFloorType/wetFloorType drive Fotocasa parquet/stoneware feature flags.

Appliances & rental extras (Fotocasa)#

Energy certificate#

Rental-specific#

Sale-specific#

Commercial transfer (traspaso — local only)#

Garage (propertyType: "garaje")#

Land / plot (propertyType: "solar")#

Commercial premises (propertyType: "local")#

Owner contact (optional)#

Send the property's owner (propietario) in the same call and Vesta creates or matches the contact and links it to the property as its owner — no second request needed.

contact: object { "name": "Ana Pérez", "phone": "+34600111222", "email": "ana@example.com" }

At least one of phone or email is required. Matching is per-account: if a contact with the same email or phone already exists, Vesta reuses it instead of creating a duplicate, and the owner link is never duplicated. The linked contact's id is returned as contactId.

Certain partner source values are additionally configured (by Vesta) to drop the owner into the agency's captación pipeline (column Pendiente on the captaciones board) — used by sourcing platforms whose sends are mandate opportunities rather than portfolio syncs. Re-sending never resets a card the agency has already moved forward. Ask Vesta if your integration should enable this.

Photos#

images: array (max 50) of { "url": "https://…", "tag": "salon", "order": 0 }. Only url is required. Sending images replaces the current photo set, so always send the full set you want live. tag (optional) must be one of the values in Allowed values → images[].tag — use plano to mark a floor plan.

Publication control#

The fields above only set how a listing would appear — none of them contacts a portal. ingest also accepts publishTo / publishMode, which do push the ad live; they are documented in the portal publishing reference along with the /publish, /sync and /unpublish endpoints.

Allowed values for coded fields#

These fields accept only the values listed below (case-sensitive, exactly as written). Any other value is stored but ignored by the portals.

propertySubtype depends on propertyType:

Garage (propertyType: "garaje"):

Land / plot (propertyType: "solar"):

Commercial premises (propertyType: "local"):

Response#

201 Created for a new property, 200 OK for an update.

{
  "created": true,
  "reference": "PARTNER-123",
  "listingId": 84213,
  "propertyId": 90217,
  "vestaReference": "V-0001234",
  "contactId": 55012,
  "publish": {
    "fotocasa": {
      "success": true,
      "portalUrls": { "fotocasa": "https://www.fotocasa.es/..." }
    },
    "idealista": { "success": true, "exportTriggered": true }
  }
}

contactId is present only if you sent contact. listingId / propertyId / vestaReference are Vesta's internal ids — informational; you keep using your own reference. A publish block appears only for integrations that also do portal publishing (separate reference).

Idempotency#

(account, reference) identifies a property. Re-sending the same reference updates it (no duplicate). Send only changed fields; omitted fields are preserved (except images, which is full-set replace). Safe to retry and to run periodic full syncs from your system.

2b. Captación mode#

The same endpoint can behave differently for sourcing integrations: the payload is treated as a captación opportunity (a portal ad the agency may want to win the mandate for) and saved to the Captaciones board (/operaciones/captaciones) instead of creating a property + listing. It adds the originPortal, publicationDate and agencyName fields and is never published to portals.

This mode is opt-in per integration: Vesta enables it for your source slug and hands you the field-by-field transform. Ask us if your integration sends mandate opportunities rather than an existing portfolio.

5. Examples#

A. Send a flat for sale, with the full payload#

curl -X POST 'https://vesta-crm.com/api/listings/external/ingest?account=<ACCOUNT_ID>' \
  -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  -d '{
    "reference": "PARTNER-123",
    "operation": "Sale",
    "price": 185000,
    "status": "En Venta",
    "title": "Piso reformado de 3 dormitorios en el centro",
    "description": "Totalmente reformado, listo para entrar a vivir.",
    "propertyType": "piso",
    "propertySubtype": "Piso",
    "squareMeter": 95,
    "builtSurfaceArea": 105,
    "bedrooms": 3,
    "bathrooms": 2,
    "yearBuilt": 2008,
    "street": "Calle Mayor 12",
    "floor": 3,
    "door": "B",
    "postalCode": "24001",
    "latitude": 42.5987,
    "longitude": -5.5671,
    "city": "León", "province": "León", "municipality": "León", "neighborhood": "Centro",
    "conservationStatus": 6,
    "orientation": "sur",
    "exterior": true,
    "hasElevator": true,
    "hasStorageRoom": true,
    "terrace": true,
    "builtInWardrobes": true,
    "airConditioning": true,
    "heatingType": "Gas natural",
    "energyScale": "D",
    "energyValue": 120,
    "emissionsScale": "E",
    "communityFees": 45,
    "images": [
      { "url": "https://cdn.partner.com/123/1.jpg", "order": 0, "tag": "fachada" },
      { "url": "https://cdn.partner.com/123/2.jpg", "order": 1, "tag": "salon" }
    ],
    "publishToWebsite": true,
    "visibility": 2
  }'

B. Minimal rental#

curl -X POST 'https://vesta-crm.com/api/listings/external/ingest?account=<ACCOUNT_ID>' \
  -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  -d '{ "reference": "PARTNER-999", "operation": "Rent", "price": 750, "status": "En Alquiler", "rentalType": "residential", "securityDeposit": 1500 }'

C. Show an existing property on the website (or hide it)#

curl -X POST 'https://vesta-crm.com/api/listings/external/ingest?account=<ACCOUNT_ID>' \
  -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  -d '{ "reference": "PARTNER-999", "operation": "Rent", "price": 750, "publishToWebsite": true }'

6. Errors#

Validation errors include a details object (field → messages) so you can show exactly what was wrong.

7. Mapping a partner schema → this API#

If your system models properties with its own field names/codes (as some CRMs do, mirroring an Inmovilla-style integration), here's how to translate. Unlike Inmovilla, you never need Vesta's internal numeric codes — send the enums and location names below directly.

Operation#

Property type#

Condition#

Other mappings#

• Location: send province + municipality (and city/neighborhood) as names, plus latitude/longitude. No internal location codes needed.
• Photos: photos[].position → images[].order; photos[].url → images[].url.
• Central heating: send heatingType: "Central" (or "Central con contador") — there is no separate boolean.
• Contact / owner: send the contact object on ingest (see Owner contact) — no separate contact call is required.
• Source URL: source_url → sourceUrl.

Photos must be publicly downloadable URLs (no auth, common image/* formats, reasonable redirects). Vesta stores the URL you send.

Worked example (nested partner payload → Vesta)#

A nested partner payload:

{
  "external_reference": "bp_88213",
  "title": "Piso en venta en Madrid",
  "operation": "sale",
  "property_type": "flat",
  "condition": "good_condition",
  "price": 250000,
  "built_area": 95,
  "rooms": 3,
  "bathrooms": 2,
  "description": "Luminoso y reformado.",
  "source_url": "https://partner.example.com/offer/88213",
  "location": {
    "latitude": 40.4168,
    "longitude": -3.7038,
    "province_id": "Madrid",
    "municipality_id": "Madrid"
  },
  "features": {
    "lift": true,
    "air_conditioning": true,
    "central_heating": true,
    "garage": true,
    "storeroom": true,
    "balcony": true,
    "furnished": false
  },
  "energy": { "energy_certificate": "D", "emissions_certificate": "E" },
  "photos": [{ "url": "https://cdn.bp.com/88213/1.jpg", "position": 1 }],
  "contact": { "name": "Ana Pérez", "phone": "+34600111222" }
}

The exact Vesta ingest body it becomes:

{
  "reference": "bp_88213",
  "source": "partner_slug",
  "title": "Piso en venta en Madrid",
  "operation": "Sale",
  "propertyType": "piso",
  "conservationStatus": 1,
  "price": 250000,
  "builtSurfaceArea": 95,
  "bedrooms": 3,
  "bathrooms": 2,
  "description": "Luminoso y reformado.",
  "sourceUrl": "https://partner.example.com/offer/88213",
  "latitude": 40.4168,
  "longitude": -3.7038,
  "province": "Madrid",
  "municipality": "Madrid",
  "hasElevator": true,
  "airConditioning": true,
  "heatingType": "Central",
  "hasGarage": true,
  "hasStorageRoom": true,
  "balconyCount": 1,
  "isFurnished": false,
  "energyScale": "D",
  "emissionsScale": "E",
  "images": [{ "url": "https://cdn.bp.com/88213/1.jpg", "order": 0 }],
  "contact": { "name": "Ana Pérez", "phone": "+34600111222" }
}

For a partner that needs a step-by-step parsing guide (with drop-in transform code) for a nested/coded schema like this, Vesta can provide a tailored companion doc on request.

Push contacts into a Vesta account from your own system — the contact-side companion to the Vesta Listing API.

• Base URL: https://vesta-crm.com
• Content type: application/json
• Auth: per-account Bearer token — the same externalApiToken as the Listing API.
• Endpoints:
  • POST /api/listings/external/contacts — create or update a contact (name, surname, notes, pipeline stage, consent, …), and move one you created along the board (contactado → gestionado → …)
  • GET /api/listings/external/contacts/status — read back the pipeline state of the contacts you created (stages only, no personal data)

This lives under /api/listings/external/* because it shares the Listing API's token and infrastructure — the path prefix is historical, the payload is pure contact data.

🔒 No endpoint here returns personal data. You can write a contact and you can read back where it ended up in the pipeline, but never the stored record — no name, email, phone, NIF, address or notes come back out. Contacts leave the database through the agency's own Vesta account. GET on /contacts itself answers 405; the state endpoint is /contacts/status.

1. Authentication#

Every request needs:

1. The account in the URL: ?account=<accountId>.
2. Your secret token, as a header (preferred) or query param:
   • Authorization: Bearer <token>
   • or ?token=<token>

POST /api/listings/external/contacts?account=<ACCOUNT_ID>
Authorization: Bearer <token>
Content-Type: application/json

Vesta gives you the token and the account id — the same pair used for the Listing API. Until the token is set, the account returns 401. You can reuse GET /api/listings/external/validate?account=<ACCOUNT_ID> to check a token.

Who is pushing: the acting user (optional)#

The token identifies the agency, not the person. If your system has its own logged-in users, send who they are and the contact you create gets that agent as its gestor instead of landing unassigned:

X-Partner-User-Email: maria@agencia.com     ← what we match on
X-Partner-User-Id:    4821                  ← your own id, for our logs

(X-Betterplace-User-Email / X-Betterplace-User-Id are accepted as aliases.)

• The address doesn't have to match exactly. We compare it against the active users of that same account and take the closest one, so maria.garcia@tusistema.com still finds maria@agencia.com. Capitals, dots and +tags are ignored, and the agent's name counts too (mgarcia@ finds "María García").
• Never a guess between colleagues. If two agents are equally close, nobody is picked — better unassigned than the wrong gestor.
• A miss is never an error. The lead still comes in, and the response carries "agentMatched": false so you can spot users you haven't mapped yet. The field only appears when you sent the header.
• On create only. Updating a contact never changes its gestor — the agency may have reassigned it on purpose.

2. POST /api/listings/external/contacts — create or update#

Send one flat object. Send firstName (to create or match a person) or contactId (to target one you already created). Anything you omit keeps its previous value on an update, and is left blank on a create.

The same endpoint does both jobs: it creates the contact, and later it moves it along the pipeline — see §4.

Targeting an existing contact: contactId#

The contactId we return on POST (and on the status read) can be sent back to target that exact contact. Dedup is skipped, and only the fields you send are written:

# "this lead is now managed" — no name, no email, nothing else touched
curl -X POST 'https://vesta-crm.com/api/listings/external/contacts?account=<ACCOUNT_ID>' \
  -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  -d '{ "contactId": 84021, "ingestChannel": "tu-slug", "leadStatus": "gestionado" }'

• ingestChannel is required alongside contactId, and it must be your own slug. You can only move contacts your integration created; a contact the agency's agent typed into Vesta is not addressable, and an id that isn't yours comes back as 400 Unknown contactId.
• Prefer it over matching by name for a status change. Name matching can land on a namesake — contactId cannot.

Idempotency / dedup#

When you don't send contactId:

Vesta runs its own duplicate detection (the same logic the app uses when an agent adds a contact) against the account's existing contacts, in this order:

1. NIF/DNI/NIE exact match
2. Email exact match
3. Phone exact match
4. Email + name, or phone + name

• A match is found → that contact is updated with the fields you sent (partial merge) and the response is 200 { "created": false }.
• No match → a new contact is created, 201 { "created": true }.

This makes repeat calls safe: send the same person twice and you update, you don't duplicate. Sending a stable email or nif is the most reliable way to land updates on the right record.

Body fields#

Sending the questions from your form#

Anything your form asked that has no dedicated field above goes in questions. Each entry lands two places:

• Raw, in additional_info.externalQuestions (the full array, verbatim).
• As a note on the contact, one • Pregunta: respuesta line per answered question under a 📋 Cuestionario — <ingestChannel> header. That note is what the agent actually reads: it surfaces as the captación card's note preview and on the contact timeline. This mirrors how GOEX folds its sheet columns in.

The note is idempotent by content — re-POSTing the same lead with the same answers does not stack duplicates. Send it changed (you enriched the lead later) and a second note is written, because that is new information.

"questions": [
  { "question": "¿Tiene propiedad en venta?", "answer": true },
  { "question": "¿En qué zona?",              "answer": "Chamberí, Madrid" },
  { "question": "Precio esperado",            "answer": 350000 },
  { "question": "¿Cuándo quiere vender?",     "answer": ["3 meses", "6 meses"] }
]

renders on the contact as:

📋 Cuestionario — Tu Integración
• Tiene propiedad en venta: Sí
• En qué zona: Chamberí, Madrid
• Precio esperado: 350000
• Cuándo quiere vender: 3 meses, 6 meses

Example#

curl -X POST 'https://vesta-crm.com/api/listings/external/contacts?account=<ACCOUNT_ID>' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "firstName": "María",
    "lastName": "García López",
    "email": "maria.garcia@example.com",
    "phone": "+34 600 000 000",
    "notes": "Propietaria interesada en vender. Llamar por las tardes.",
    "source": "idealista",
    "ingestChannel": "tu-slug",
    "captacionStatus": "contactado",
    "gdprConsentStatus": "accepted",
    "questions": [
      { "question": "¿Tiene propiedad en venta?", "answer": true },
      { "question": "¿En qué zona?", "answer": "Chamberí, Madrid" }
    ]
  }'

Moving that same person on later — send only the key and the new stage, the dedup finds them:

curl -X POST 'https://vesta-crm.com/api/listings/external/contacts?account=<ACCOUNT_ID>' \
  -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  -d '{ "firstName": "María", "email": "maria.garcia@example.com", "captacionStatus": "valoracion" }'

Response#

A write receipt — ids and the pipeline stage, never the stored record:

{
  "created": true,          // false when an existing contact was updated
  "contactId": 84021,
  "contact": {
    "id": 84021,
    "captacionStatus": "contactado",
    "leadStatus": null,
    "createdAt": "2026-07-21T10:15:00.000Z",
    "updatedAt": "2026-07-21T10:15:00.000Z"
  }
}

created tells you which of the two happened, and contactId is stable — store it. It is what you send back to move the contact later (§4) and to query its state (§3).

3. GET /api/listings/external/contacts/status — where did my leads end up?#

Read back the pipeline state of the contacts your integration created: which column the agency's agent moved them to, and when.

curl 'https://vesta-crm.com/api/listings/external/contacts/status?account=<ACCOUNT_ID>&ingestChannel=tu-slug' \
  -H 'Authorization: Bearer <TOKEN>'

Query params#

Response#

{
  "contacts": [
    {
      "id": 84021,
      "captacionStatus": "valoracion",
      "captacionStatusUpdatedAt": "2026-08-16T09:12:04.000Z",
      "leadStatus": "contactado",
      "leadStatusUpdatedAt": "2026-08-15T18:40:11.000Z",
      "gdprConsentStatus": "accepted",
      "ingestChannel": "tu-slug",
      "isActive": true,
      "updatedAt": "2026-08-16T09:12:04.000Z"
    }
  ],
  "count": 1
}

🔒 What this endpoint will never return#

No personal data. Ever. No name, email, phone, NIF, address, date of birth or notes — only the stages above and their timestamps. Contacts as records leave the database through the agency's own Vesta account, never through a partner integration.

ingestChannel is required because it is the whole security model. Only contacts carrying your channel come back. A contact an agent typed into Vesta by hand has no channel at all, so the agency's own book is unreachable here no matter what you ask for — in a live account with thousands of contacts, this endpoint returns only the handful your integration sent.

Practical notes:

• Poll with since, not by refetching everything: pass the largest updatedAt you have seen.
• Repeat sends are safe — the upsert dedups (§2), so re-sending is still the way to change a contact. This endpoint only reads.
• isActive: false means the agency deleted the contact. Stop sending it.

4. Moving a contact through a pipeline#

🚨 There are two boards and they do not share lane ids. Pick the one that matches what the person wants; sending a lane id to the wrong board is a 400.

captacionStatus — Captaciones#

Every created contact lands on the Captaciones board. If you omit captacionStatus on a create, Vesta defaults it to the initial column (pendiente) — the board only shows contacts whose captacionStatus is set, so this guarantees imports appear there. Send an explicit stage to place them elsewhere.

leadStatus — Leads#

Unlike the captación board, leadStatus is only written when you send it — an owner lead has no business appearing as a buyer demand. Send it on the first call and the contact appears on the Leads board too.

An account may insert its own lanes between Contactado and Gestionado. Those are as valid as the built-ins; a 400 response lists every id the account accepts in an allowed array, so you never have to guess.

Both boards#

A move is a POST with the id and the new stage — nothing else:

curl -X POST 'https://vesta-crm.com/api/listings/external/contacts?account=<ACCOUNT_ID>' \
  -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  -d '{ "contactId": 84021, "ingestChannel": "tu-slug", "leadStatus": "gestionado" }'

contactado → gestionado → back to contactado all work, in either direction, on either board. Notes:

• Sending an unknown value returns 400 with the allowed ids.
• Setting or changing a stage stamps its own clock (captacionStatusUpdatedAt / leadStatusUpdatedAt, the SLA clocks). Re-sending the value it already has is a no-op for that timestamp.
• On an update, an omitted stage leaves the contact where it is — no accidental resurrection of a descartado or inactivo contact.
• Moving a lead back out of gestionado re-flags it as open, so it reappears on the board instead of being written into a column nobody can see.
• There is no webhook. If the agency's agent drags the card themselves, your system is not notified — poll /contacts/status with since (§3) to pick the change up. Both sides can move a card; last write wins.

4b. Consent (gdprConsentStatus)#

You collected the lead, so you are the only one who knows on what basis. Send it with the contact:

Setting it stamps gdprConsentDate with the moment we received it and records the method as portal. A status with no date proves nothing, which is why the two always travel together.

Send it even when it's rejected. A lead that arrives with no consent information is indistinguishable from one nobody ever asked, and the agency ends up guessing whether it can legally call the person.

5. Errors#

Feed JSON de inmuebles de tu agencia servido desde Vesta CRM. Sustituye a los antiguos feeds XML (Apinmo / Inmovilla y similares). Mismo modelo (consultas por HTTP a una URL), pero en JSON y protegido por token.

Esta documentación es genérica: sirve para cualquier cuenta. Donde aparece {account} sustituye por el ID de tu cuenta, y donde aparece TU_TOKEN_AQUI pon el token que te facilita Vesta. Ambos son específicos de tu cuenta.

1. Resumen rápido#

Solo se exponen los inmuebles publicados en la web y activos. El resto del catálogo nunca se devuelve.

2. Autenticación#

Todas las peticiones requieren dos cosas:

1. El parámetro account={account} (identifica la agencia).
2. El token secreto de la cuenta, en la cabecera HTTP:

Authorization: Bearer TU_TOKEN_AQUI

🔑 El token te lo facilita Vesta por separado (no se publica en esta documentación). Es secreto y específico de tu cuenta — trátalo como una contraseña. El token de una cuenta no sirve para ninguna otra cuenta.

Para pruebas rápidas desde el navegador puedes usar ?account={account}&token=TU_TOKEN_AQUI, pero ⚠️ en producción usa siempre la cabecera Authorization: Bearer (los tokens en la URL acaban en logs/historiales).

3. Endpoint: Listado#

Devuelve todas las propiedades publicadas (tarjetas para el listado / grid).

GET https://vesta-crm.com/api/listings/inmovilla?account={account}
GET https://vesta-crm.com/api/listings/inmovilla?account={account}&localidad=nombre-de-la-localidad

Parámetros de query#

* Por cabecera o por query. Orden: destacados primero, luego por fecha de actualización.

Respuesta 200#

{
  "offset": 0,
  "pagination": 401,
  "totalItems": 401,
  "listaLocalidades": {
    "localidad-uno": "Localidad Uno",
    "localidad-dos": "Localidad Dos",
    "localidad-tres": "Localidad Tres"
  },
  "list": [
    {
      "id": 1000245715,
      "ref": "VESTA2026167226",
      "title": "Casa en Calle Mirador",
      "tipo": "casa",
      "tipoOperacion": "venta",
      "habitaciones": 7,
      "banyos": 7,
      "superficieConstruida": 718,
      "precioinmo": 4600000,
      "ciudad": "Ciudad Ejemplo",
      "zona": "Zona Ejemplo",
      "destacado": 1,
      "images": "https://….amazonaws.com/accounts/{account}/VESTA2026167226/imagen_01.jpg"
    }
  ]
}

Campos del listado#

4. Endpoint: Detalle (por referencia)#

GET https://vesta-crm.com/api/listings/inmovilla/{ref}?account={account}

Ejemplo: …/api/listings/inmovilla/VESTA2026167226?account={account}

Respuesta 200#

{
  "ref": "VESTA2026167226",
  "title": "Casa en Calle Mirador",
  "tipo": "casa",
  "subtipo": "Casa adosada",
  "tipoOperacion": "venta",
  "estado": "En Venta",

  "habitaciones": 7,
  "habdobles": 0,
  "banyos": "7",
  "planta": 0,
  "superficieConstruida": 718,
  "superficieUtil": 690,
  "superficieParcela": 1200,
  "m_parcela": "",
  "m_uties": "718.00",

  "anoConstruccion": 2025,
  "estadoConservacion": "Como nuevo",
  "energiaEscala": "A",
  "energiaValor": 32,
  "emisionesEscala": "A",
  "emisionesValor": 5,

  "direccion": "Calle Mirador",
  "puerta": "B",
  "cp": "08392",
  "ciudad": "Ciudad Ejemplo",
  "zona": "Zona Ejemplo",
  "latitud": "41.571279",
  "altitud": "2.485045",

  "precioinmo": 4600000,
  "descripcionPequena": "Espectacular casa…",
  "descriptiones": ["Descripción completa…"],
  "imagenes": ["https://….jpg", "https://….jpg"],
  "planos": [],
  "videos": [],
  "virtualTours": [],
  "caracteristicas": ["Superficie útil: 690 m²", "Antigüedad: 2025", "Ascensor", "Piscina privada"],

  "estadoOcupacion": "free",
  "esObraNueva": false
}

Campos del detalle#

Identidad y categoría

Habitaciones y superficies

Estado y energía

Ubicación (respeta la privacidad de cada inmueble — ver §7)

Precio y contenido

Específicos de operación (presentes solo cuando aplican)

⚠️ altitud contiene la longitud, no la altitud (heredado del feed original de Inmovilla). Para un mapa: lat = latitud, lng = altitud.

5. El campo caracteristicas#

Array plano de cadenas listas para mostrar, con dos tipos de entrada:

• Con valor — "Etiqueta: valor", p. ej. "Superficie útil: 90 m²", "IBI: 320 €", "Gastos comunidad: 45 €/mes", "Antigüedad: 2008".
• Solo etiqueta (amenidades activas) — "Ascensor", "Terraza", "Calefacción", "Jardín".

El conjunto depende del tipo de inmueble (un garaje no muestra habitaciones; un solar no muestra ascensor; un local muestra escaparate/fachada/salida de humos). ✅ Trátalo como contenido de presentación (renderiza cada cadena como un chip/fila); no lo parsees — para filtrar usa los campos estructurados (tipo, superficieUtil, anoConstruccion, energiaEscala, etc.).

6. Valores de los enumerados#

tipo (clave estable para filtrar):

piso · casa · local · solar · garaje · edificio · oficina · industrial · trastero

tipoOperacion:

venta · alquiler · traspaso · alquiler-opcion-compra · compartir-habitacion

estado (en el feed, casi siempre disponible): En Venta · En Alquiler (también Vendido / Alquilado si se publicaran).

subtipo es texto libre del catálogo de Vesta (p. ej. Ático, Dúplex, Casa adosada, Chalet, Nave industrial, Suelo residencial).

7. Privacidad de la ubicación (importante)#

Cada inmueble tiene un nivel de visibilidad configurado por el agente. El feed lo respeta:

cp, ciudad y zona se devuelven siempre. Si un inmueble no muestra coordenadas, geocodifica ciudad + zona para una ubicación aproximada en el mapa.

8. Códigos de error#

9. Caché#

10. Ejemplos de código#

En los ejemplos, sustituye {account} por el ID de tu cuenta y TU_TOKEN_AQUI por tu token.

cURL#

curl -H "Authorization: Bearer TU_TOKEN_AQUI" \
  "https://vesta-crm.com/api/listings/inmovilla?account={account}"

# Filtrado por localidad (la clave sale de listaLocalidades)
curl -H "Authorization: Bearer TU_TOKEN_AQUI" \
  "https://vesta-crm.com/api/listings/inmovilla?account={account}&localidad=nombre-de-la-localidad"

curl -H "Authorization: Bearer TU_TOKEN_AQUI" \
  "https://vesta-crm.com/api/listings/inmovilla/VESTA2026167226?account={account}"

JavaScript (fetch)#

const BASE = "https://vesta-crm.com/api/listings/inmovilla";
const ACCOUNT = 0; // ← el ID numérico de tu cuenta
const TOKEN = process.env.VESTA_FEED_TOKEN; // nunca en el front-end

async function getListado({ offset = 0, limit = 1000, localidad } = {}) {
  const params = new URLSearchParams({ account: ACCOUNT, offset, limit });
  if (localidad) params.set("localidad", localidad); // key_filtro de listaLocalidades
  const res = await fetch(`${BASE}?${params}`, {
    headers: { Authorization: `Bearer ${TOKEN}` },
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

// Desplegable del filtro: const { listaLocalidades } = await getListado();
// Object.entries(listaLocalidades) → [["nombre-de-la-localidad", "Nombre de la localidad"], …]

async function getDetalle(ref) {
  const res = await fetch(`${BASE}/${encodeURIComponent(ref)}?account=${ACCOUNT}`, {
    headers: { Authorization: `Bearer ${TOKEN}` },
  });
  if (res.status === 404) return null;
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

PHP#

<?php
$BASE = "https://vesta-crm.com/api/listings/inmovilla";
$ACCOUNT = 0; // ← el ID numérico de tu cuenta
$TOKEN = getenv("VESTA_FEED_TOKEN");

function vesta_feed_get($url, $token) {
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => ["Authorization: Bearer $token"],
    ]);
    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    return $code === 200 ? json_decode($body, true) : null;
}

$listado = vesta_feed_get("$BASE?account=$ACCOUNT", $TOKEN);
$detalle = vesta_feed_get("$BASE/" . rawurlencode("VESTA2026167226") . "?account=$ACCOUNT", $TOKEN);

// Desplegable del filtro de localidad:
// foreach ($listado["listaLocalidades"] as $key => $nombre) { … }
// Filtrar por localidad (enviar la clave, no el nombre):
$filtrado = vesta_feed_get("$BASE?account=$ACCOUNT&localidad=nombre-de-la-localidad", $TOKEN);

11. Migración desde un XML antiguo (Apinmo / Inmovilla)#

Si vienes de un feed XML (Apinmo, Inmovilla o similar), estas tablas mapean los campos antiguos a la Nueva API.

Listado (antes ↔ ahora)#

Detalle (antes ↔ ahora)#

Antes leías cada amenidad de un tag distinto del XML. Ahora vienen resueltas y formateadas en caracteristicas[], y los datos clave para filtrar (tipo, operación, superficies, año, energía) están como campos estructurados.

12. Notas#

• Solo se publican inmuebles marcados como publicar en web y activos.
• Filtro por localidad: monta el desplegable con listaLocalidades (clave → texto a mostrar) y envía la clave en ?localidad=. No envíes el nombre con espacios/acentos — la clave ya viene normalizada.
• Las imágenes incluyen la marca de agua de la agencia.
• El precio (precioinmo) es el de la operación principal.
• Para el mapa: lat = latitud, lng = altitud (cuando estén disponibles — ver §7).

Contacto / soporte: a través de Vesta CRM.

Pull an account's listings as a portal-ready Kyero-v3 XML feed. This is the outbound XML surface — a partner/portal reads it on a schedule. It is the same data as the JSON read feed, in XML.

• Base URL: https://vesta-crm.com
• Auth: per-account Bearer token (the same single token as every other Vesta API — see README)
• Endpoint:
  • GET /api/listings/feed/<portal> — stream the account's stored XML snapshot

catch-all — no separate route.

1. Endpoint & portals#

GET https://vesta-crm.com/api/listings/feed/<portal>
Authorization: Bearer <token>      (or ?token=<token>)

<portal> is one of:

An unknown portal returns 404.

2. Authentication#

The account is resolved from the token — the URL never carries the numeric account id, so feeds aren't enumerable. Send the token as a header (preferred) or ?token=:

Authorization: Bearer <token>

This is the same token used for the JSON read feed and the write API; there is only one secret per account. Accounts activate / view / rotate it in Ajustes → Portales → "API / Feeds".

3. Response#

200 OK streams the stored snapshot:

Content-Type: application/xml; charset=utf-8
Cache-Control: public, max-age=1800, s-maxage=1800

The snapshot is regenerated on Vesta's side whenever a listing changes, so polling more often than ~30 min gains nothing.

4. Errors#

5. Example#

curl 'https://vesta-crm.com/api/listings/feed/kyero' \
  -H 'Authorization: Bearer <TOKEN>' \
  -o vesta-feed.xml