# API v1 Los endpoints del catálogo — propiedades y asesores — con su paginación, sus filtros y sus errores. REST sobre `/api/v1/*`. Requiere una llave de scope `api_v1`. Ver [Llaves de API](/desarrolladores/llaves-api/). ## Endpoints | Método | Ruta | Qué devuelve | | ------ | ----------------------------------- | ---------------------------------------------- | | `GET` | `/api/v1/properties` | Propiedades publicadas del espacio de trabajo. | | `GET` | `/api/v1/properties/{idOrSlug}` | Una propiedad. | | `POST` | `/api/v1/properties/{uid}/favorite` | Registra un favorito. | | `GET` | `/api/v1/agents` | Asesores con perfil público. | | `GET` | `/api/v1/agents/{idOrUsername}` | Un asesor. | :::note `GET /api/v1/properties` devuelve **solo las propiedades publicadas y visibles en la web**. Una que existe pero no está publicada no aparece, y la respuesta no la distingue de una que no existe. ::: ## Paginación Tamaño de página fijo: **10**. Toda respuesta de listado trae `meta`: ```json { "data": [], "meta": { "page": 1, "page_size": 10, "total": 47, "total_pages": 5 } } ``` ## Filtros de propiedades Los que más se usan: | Parámetro | Tipo | Qué hace | | -------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------- | | `page` | entero | Página, base 1 | | `search` | texto | Busca en el nombre | | `listing_type` | texto | `project` \| `single_property` | | `property_status` | CSV | `new`, `used`, `remodeled`, `pre_sale`, `under_construction`, `ready_for_delivery`, `delivered`, `in_planning` | | `offer_types` | CSV | `sale`, `rent` | | `property_type_key` | CSV | `villa`, `apartment`, `penthouse`, `land`… | | `city` / `city_id` | CSV | Por nombre o por id | | `province` / `state_id` | CSV | Por nombre o por id | | `sector_id` | CSV | Por id | | `organization_id` | UUID | Por desarrolladora | | `min_price` / `max_price` | número | Sobre el precio de referencia | | `min_rooms` / `min_bathrooms` / `min_parking` | entero | Filtra sobre las tipologías | | `furnishing` | texto | `sin_amoblamiento`, `semi_amoblado`, `linea_blanca`, `full_amoblado` | | `tags` | CSV | Solapamiento con el arreglo de etiquetas | | `featured`, `confotur`, `first_home_bonus`, `safe` | `1` | Solo las marcadas | | `delivery_date_from` / `delivery_date_to` | `YYYY-MM-DD` | Rango de entrega: entra el proyecto con alguna etapa que entrega dentro del rango | | `sort_field` | `price` \| `name` | Orden (por defecto, más recientes primero) | | `sort_dir` | `asc` | Solo aplica con `sort_field` | Los filtros por nombre y por id se pueden combinar entre sí: `city` junto con `city_id`, o `province` junto con `state_id`. ## Formas de pago en la respuesta La propiedad trae sus **formas de pago visibles** y cuál es la principal. Una variante retirada (no visible) no viaja, y si la principal está retirada, se reporta como principal la primera visible — de modo que el listado nunca vuelve sin ninguna marcada. ## Fecha de entrega y etapas Un proyecto entrega por **etapas** (por ejemplo, «Torre A» en 2026 y «Torre B» en 2028), y cada una trae su propia fecha. La respuesta incluye `delivery_stages`, la lista completa en el orden en que se leen, con `name`, `delivery_date` (vacía si todavía no se anunció) e `is_default`. `delivery_date` sigue estando y significa lo mismo: la fecha de entrega del proyecto, que es la de la etapa principal. Los filtros `delivery_date_from` / `delivery_date_to` devuelven un proyecto cuando **alguna** de sus etapas entrega dentro del rango. ## Errores | Código | Causa | | ------ | ------------------------------------------------------------- | | `401` | Llave ausente, inválida, revocada o sin el permiso del método | | `404` | No existe (o no está publicado) | | `429` | Límite de peticiones excedido | | `500` | Error interno | Cuerpo: `{ "error": "" }` ## Límite de peticiones 60 por minuto y por llave. Toda respuesta trae: ``` X-RateLimit-Limit: 60 X-RateLimit-Remaining: 58 X-RateLimit-Reset: 1750200060 ``` Al excederlo, `429` con `Retry-After` en segundos. --- Índice completo del centro de ayuda: https://help.linkerestate.com/llms.txt