Detalles de la especificación XML usada en Kyero.com para importar detalles de las propiedades de otros sistemas de Kyero.com
Esta página enumera las especificaciones de un suministrador de datos XML para enviar información a Kyero.com. (English version)
Última modificación 18 August 2020 - V3.6
Contenidos
- Para empezar
- Sinopsis
- Directrices y Convenciones
- Sumario de la estructura de suministro de datos
- Acerca de la programación de los caracteres
- Probar la estructura
- Probar la programación de los caracteres
- Presentar un suministro de datos para ser validado
- Automatizar las actualizaciones de los inmuebles
- Obtención de ayuda
- Información de las Versiones
1. Para empezar
- Consultar estas notas detalladas , este ejemplo de suministro de datos y definición de esquema XML (XSD)
- Crea tu suministrador de datos (secciones 2 - 5)
- Pruébalo (secciones 6 y 7)
- Preséntalo a Kyero.com para su validación final (sección 8)
2. Sinopsis
Tu suministrador de datos XML contiene toda la información para la cuenta de un anunciante Kyero.com. Hacemos coincidir el suministrador de datos URL que nos diste con una cuenta de anunciante en cuanto validamos y aprobamos el suministrador de datos.
Cada URL de suministrador de datos puede contener tan sólo información de los inmuebles de una cuenta de Kyero o agente inmobiliario. Si estás creando suministradores de datos para varios agentes inmobiliarios, cada uno de ellos deberá encontrarse disponible en un único URL
Si deseas proteger un suministrador de datos con una contraseña para que no esté disponible públicamente, debes simplemente proveer el URL del suministrador de datos en uno de los formatos siguientes.
No podemos aceptar el URL de un suministrador de datos que requiera cualquier intervención manual (como por ejemplo hacer clic en un botón para confirmar) ya que nuestro proceso de suministrador de datos de inmuebles es completamente automático.
Tu suministrador de datos de inmuebles debe ser un suministrador de datos absoluto de toda la información de los inmuebles y no uno que incremente. Cada vez que procesamos un suministrador de datos, lo evaluamos junto a cada otro inmueble en esa cuenta en la base de datos de Kyero. Tu suministrador de datos debe contener TODOS los inmuebles que quieras AÑADIR o ACTUALIZAR. No debe contener ningún inmueble que quieras ELIMINAR.
Cuando un inmueble es AÑADIDO a tu base de datos, habrá un nuevo registro de inmueble para el mismo en tu suministrador de datos. Será INSERTADO en nuestra base de datos y procesaremos y almacenaremos todas las imágenes relacionadas.
Si un inmueble es ACTUALIZADO en tu base de datos, el tag <date> en tu suministrador de datos cambiará. Cuando vemos un cambio en el tag <date> el inmueble será ACTUALIZADO en nuestra base de datos y procesamos todas las imágenes relacionadas.
Si un inmueble es ELIMINADO de tu base de datos, no quedará ningún registro de ésta en tu suministrador de datos. ELIMINAMOS los inmuebles y toda imagen relacionada de nuestra base de datos cuando no hay evidencia de ningún inmueble que coincida con tu suministrador de datos .
Para insertar, actualizar o eliminar correctamente, debemos identificar consistentemente cada inmueble como una entidad única en tu suministrador de datos. Esto lo haremos utilizando el tag <id> el cual debe consistentemente y únicamente identificar cada una de tus inmuebles.
3. Directrices y convenciones
Debes codificar tu suministrador de datos para fragmentar nuevos tags en nuevas líneas (nuestro parser sólo puede manipular un límite de carácter de una sola línea) – además, es mucho más fácil para nosotros leer y solucionar problemas con tu suministrador de datos. Usa \n en el documento que crea tu output XML. Cuando revises el output XML en un editor de textos – deberás ver cada tag en una nueva línea.
Para forzar saltos de línea en los textos de las descripciones de los inmuebles puedes usar la entidad numérica UTF-8 .
En las notas detalladas te diremos qué tags debes utilizar, que pueden contener y si un tag es obligatorio u opcional.
- Tags XML son así: <beds> 4</beds>
- Comentarios son así: // optional numeric
Un tag puede ser 'opcional' or 'obligatorio' y puede contener caracteres 'alfa','alfanuméricos' or 'numérico'. El tag <date> es la única excepción en la que se debe formatear como datetime AAAA-MM-DD HH:MM:SS
Si a un tag se le permite estar vacío (tags opcionales) – se le puede codificar de cuatro formas diferentes:
- <beds></beds>
- <beds>0</beds> (donde se permiten los valores numéricos)
- <beds />
- (no tag)
Todos los tags son sensibles a las mayúsculas y a las minúsculas y DEBEN escribirse siempre en minúsculas: <DESC> NO es lo mismo que <desc>
No incluyas una imagen URL 'sin imagen' o 'fotografía a venir' para inmuebles que no tienen fotografías.
No utilices tags [[CDATA]] en tu suministrador de datos como una 'solución rápida' para los problemas de programación de caracteres. Ver sección Acerca de la programación de los caracteres.
4. Sumario de la estructura del suministrador de datos
La estructura de un de un inmueble propiamente detallada se encuentra a mano derecha del margen de esta página. Tu suministrador de datos contendrá múltiples inmuebles al repetir la estructura adjunta con <property></property> para cada una.
Cuando construyas el suministrador de datos, véanse las notas detalladas y el ejemplo de suministrador de datos xml.
5. Acerca de la programación de los caracteres
Hay cinco caracteres que deben ser programados si quieres utilizarlos en tu suministrador de datos. Esto es porque tienen funciones predefinidas en XML (puedes utilizar también sus entidades numéricas).
- < - El símbolo menos que (<) - <
- > - El símbolo más que (>) - >
- & - El ampersand (&) - &
- ' - La comilla o el apóstrofe (') - '
- " - Las dos comillas (") - "
- - Para forzar saltos de linea en las descripciones.
¿Cuándo deben ser programados y cuándo deben dejarse tal cual?
Por ejemplo: <image id="9"> - las comillas no han sido programadas porque están delimitando un atributo XML dentro de un tag XML.
<desc>Una casa "hermosa" </desc> - las comillas están programadas porque forman parte de una cadena de caracteres de un texto.
<property> no debería ser programado como <property> o <property>
El texto bed & breakfast debe ser programado como bed & breakfast o bed & breakfast - en el primer ejemplo utilizando una entidad XML y, en el segundo, una entidad numérica.
En este ejemplo, la entidad XML & es el mismo que su equivalente HTML. Sin embargo, en general, las entidades HTML no deberían ser utilizadas en tu suministrador de datos. No deberían haber entidades HTML, tags o formatos en un suministrador de datos.
Antes de presentar un suministrador de datos a Kyero.com, pruébalo utilizando este validador de caracteres, seleccionando UTF-8 como el esquema de programación.
¿Estás confundido con la programación de caracteres? - Joel on Software tiene un artículo muy interesante sobre el tema. (en inglés)
6. Probar la estructura
En cuanto tengas un suministrador de datos listo para procesar, pruébalo primero abriéndolo en un explorador Mozilla ( Firefox, no Internet Explorer).
Si Firefox lo presenta en pantalla con éxito, no contiene errores estructurales XML fundamentales. De lo contrario, Firefox te dará el número de línea del suministrador de datos que contiene el primer error. Firefox también te expondrá los problemas de programación de los caracteres básicos.
Una vez hayas visto el suministrador de datos en Firefox, visita el validador XML. Puedes probarlo con este ejemplo de suministrador de datos
Cuando tengas un archivo XML estructuralmente normal, estarás listo para probar la programación de caracteres.
7. Probar la programación de los caracteres
Visita este validador de caracteres W3.org para validar tu suministrador de datos URL.
Selecciona el tipo de programación como: UTF-8 (Unicode, worldwide), haz clic en Validate.
Desgraciadamente, aún cuando el suministrador de datos está programado correctamente, seguirás recibiendo errores. En el inicio de la página de resultados, suministrador de datos correctamente validado se mostrará:
Result: Failed validation, 1 error (Resultado: Validación ha fallado, 1 error)
Desplazarse al final de la página de resultados, bajo el banner de:
This page is not Valid XML! (Esta página no es XML válida!) verás el siguiente error:Error Line 2 column 1: no document type declaration (Error línea 2 columna 1: declaración no este tipo de documento.)
Esto se puede ignorar sin ningún problema. Igualmente puedes ignorar las tres advertencias:
- Missing "charset" attribute for "text/xml" document (Falta "charset" atributo para documento de"texto/xml")
- Character Encoding Override in effect! (Anulación manual de la programación de caracteres funciona!)
- No DOCTYPE found! Attempting validation with XHTML 1.0 Transitional (No se ha encontrado DOCTYPE! Intento de validar con XHTML 1.0 en transición)
(Puedes verificar estos errores aceptables utilizando este ejemplo de suministrador de datos.)
Todos los errores deben ser investigados y resueltos antes de presentar un suministrador de datos a Kyero.
8. Presentar un suministrador de datos para ser validado
En cuanto tengas un suministrador de datos que supere la validación de la programación y la validación del esquema XML, abre un nuevo ticket de soporte con tu suministrador de datos URL. (No te olvides de decirnos para que cuenta de anunciante en Kyero.com es el suministrador de datos).
Validaremos el suministrador de datos en un sistema de desarrollo y te proporcionaremos nuestros comentarios habitualmente el mismo día hábil.
Por favor no cometas un ticket para un suministrador de datos que tenga errores estructurales o de programación de caracteres. Volveremos a este documento y las especificaciones y pruebas detalladas aquí.
9. Automatizar las actualizaciones de los inmuebles
En cuanto hayamos probado con éxito tu suministrador de datos lo procesaremos manualmente en el sistema en vivo de Kyero.com y te informaremos cuando los inmuebles se puedan revisar.
Cuando los inmuebles están en línea, procesaremos tu suministrador de datos cada día aproximadamente a las 01:30 CET
Suministrador de datos que no se ajustan a nuestra especificación o mostrar un comportamiento adverso puede ser actualizado una vez por semana o se detiene.
Es importante recordar que debes SIEMPRE utilizar tu sistema original de administración de inmuebles para administrar tus inmuebles, NO tu cuenta Kyero.com. Cuando procesamos tu suministrador de datos, REEMPLAZAMOS la información que se encuentra en tu cuenta Kyero.com.
Esto significa que si cambias detalles de los inmuebles utilizando tu cuenta Kyero.com, éstos cambios se perderán cuando procesemos tu próximo suministrador de datos. Sin embargo, los inmuebles marcadas 'incompleto' son una excepción a esta regla general.
Cuando procesamos tu suministrador de datos, el inmueble se marcará como 'incompleto' si no reconocemos cada uno de los siguientes fragmentos de información:
- Precio
- Provincia
- Ciudad
- Tipo de inmueble
Un inmueble incompleto no puede ser visto por el público en Kyero. Para que esté en activo, debe ser actualizado bien desde la cuenta Kyero.com o desde tu sistema inicial de administración de inmuebles.
Cuando hagas cambios en los inmuebles marcados ‘incompleto’ desde tu cuenta Kyero.com, estos cambios serán retenidos – aún cuando volvamos a procesar tu suministrador de datos
En vez de 'arreglar' los inmuebles incompletos, la mejor forma de actuar es evitar que un inmueble sea marcado como 'incompleto' desde el principio. Para conseguir esto, asegúrate simplemente de que tu sistema de administración de inmuebles contenga todos los campos de información obligatorios.
El sistema Kyero.com utiliza la base de datos oficial de correos para determinar la localidad exacta del inmueble. Por esta razón, puede ser que encuentres pequeñas diferencias entre la localidad utilizada en tu sistema administración de inmuebles y la que usamos en Kyero.com
Si el sistema Kyero no reconoce donde se encuentra una localidad dada, marcará el inmueble 'incompleto'. Si actualizas la localidad con tu sistema de administración de inmuebles, el inmueble será actualizado correctamente en Kyero.com.
Cojemos el tipo de inmueble de tu sistema de administración de inmuebles cuando esto sea posible. Si no está o no se puede reconocer por el sistema de Kyero.com, el inmueble se marcará 'incompleto'. Si actualizas el tipo de inmueble con el sistema de administración de inmuebles, garantizarás que el inmueble se actualiza correctamente en Kyero.com
El sistema Kyero tiene dos tipos de inmuebles, las ventas y los alquileres de largo plazo. Cuando el precio de un inmueble es detallado como 'por mes' se mostrará en la sección 'alquiler a largo plazo'.
Puede ser posible que un inmueble esté en venta Y en alquiler en tu sistema de administración de inmuebles. El sistema Kyero no reconoce esta característica y te sugerimos que crees un duplicado del inmueble en tu sistema de administración de inmuebles, que marques uno como inmueble en alquiler y el otro inmueble en venta.
El sistema Kyero.com tan sólo contiene inmuebles en España. Los que se encuentran fuera del territorio español o bien que no contienen información de su localidad no serán importados a Kyero.com. Si te encuentras con que falta un inmueble en Kyero.com, verifica que tu sistema de administración de inmuebles utiliza una localidad en España y que no esté marcado 'incompleto' en tu cuenta Kyero.com.
El sistema Kyero puede tener un máximo de cincuenta fotografías por inmueble. Si un inmueble contiene más de cincuenta fotografías en tu sistema de administración de inmuebles, será importado a Kyero.com utilizando tan sólo las cincuenta primeras fotografías.
10. Obtención de ayuda
Si tienes algún problema o pregunta que no haya sido explicada aquí, o si encuentras un error en nuestra documentación, por favor no dudes en abrir un ticket de soporte para ponerte en contacto con nosotros.
11. Información de las Versiones
18/08/2020 - V3.6
- añadido subnodo 'tags' a <images>
08/04/2020 - v3.5
- añadido nodo <video_url>
- añadido nodo <virtual_tour_url>
- añadido nodo <catastral>
- añadido nodo <country>
01/06/2016 - V3.3
- 'week' eliminado del nodo <price_freq>
11/03/2016 - V3.2
- Revisado el esquema XSD para ajustar los idiomas eliminados
- Revisado el esquema XSD para ajustar los nodos obligatorios
- Revisado el esquema XSD para eliminar el nodo <title> de las imagenes
- Actualizado el validador de feeds XML para reflejar los últimos cambios y permitir probar fees desde un archivo
- Longitud máxima de la etiqueta <ref> aumentada de 15 a 255
- Eliminados algunos idiomas: pl, ro
- La etiqueta <desc> ahora es obligatoria cuando no hay ninguna característica (<features>)
10/02/2015 - V3.1
- Aumentado el número máximo de imágenes por propiedad de 10 a 50
- Eliminados algunos idiomas: bg, cs, el, et, hu, id, ja, hi, ko, lt, lv, sk, sl, th, tr, uk, vi, zh
06/01/2014 - V3
- <feed_version> cambiado a 3
- V3 igualadas las especificaciones importacion y exportación
- 'new_build' eliminado del nodo <price_freq>
- añadido un nodo <new_build> separado
- reducido el nodo <currency> a los valores EUR, GBP y USD
- eliminados los subnodos de idioma del novo <type>
- añadido nodo <surface_area>
- añadido nodo <location>
- añadido nodo <energy_rating>
- añadido nodo <url>
- añadido subnodos de idioma al nodo <desc>
- añadido el nodo <notes>
- aumentado el tamaño mínimo obligatorio de las imágenes
- eliminado el atributo <primary> de las imágenes
- eliminado el atributo <title> de las imágenes
17/01/2013 - V2.20
- Eliminados los títulos de las imágenes. Si están presentes se descartaran. Kyero soporta ahora demasiado idiomas para que esto sea práctico de manejar.
- Feed de ejemplo y XSD actualizado
16/12/2008 - V2.19
- Añadida la opción 'new_build' al nodo <price_freq> para dar cabida a las nuevas propiedades y ventas sobre plano.
- <price_freq>sale</price_freq> seguirá usándose para las ventas
27/11/2008 - V2.18
- <feed_version> cambiado a 2_1
- Añadido nodo <features> para activar las traducciones automáticas de las características de las propiedades.
- Añadidos los nodos de idiomas <da>, <it>, <pt> y <ru> en el nodo <desc> para permitir traducciones completas de cada idioma
10/09/2007 - V2.17
- Especificación revisada para comprobar la validación de caracteres con el validador actualizado de W3C
02/05/2007 - V2.16
- Especificación revisada para eliminar el atributo <primary> de las imágenes. Añadida una nota para ordenar las imágenes según prioridad
19/04/2007 - V2.15
- Revisada la sección 5 para utilizar para utilizar 3 entidades numéricas
- Añadido un enlace al artículo Joel on Software sobre codificación de caracteres.
30/03/2007 - V2.14
- Simplificado el esquema validador de XML, revised direcciones web, corregidos números de versiones en este documento
06/12/2006 - V2.13
- Notas revisadas en la sección 6 sobre validación - Ahora usando XSD online y feed URL en lugar de subir archivos.
- Eliminada referencia a la validación de caracteres de un archivo subido en la sección 7. Eliminadas referencias al archivo XSD.
23/11/2006 - V2.12
- Notas revisadas haciendo los nodos <beds>, <baths>, <pool>, <built> & <plot> obligatorios
12/10/2006 - V2.11
- Revisado el esquema XSD para permitir tipos de propiedades que contengan caracteres '/' y '-'
12/10/2006 - V2.10
- Revisado el esquema XSD para permitir tipos de propiedades que contengan espacios
28/09/2006 - V2.09
- Revisado el esquema XSD para comprobar que el tipo de propiedad no sea vacío
11/07/2006 - V2.08
- Revisado el esquema XSD para comprobar que los nodos <feed_version> y <ref> sean válidos
07/07/2006 - V2.07
- Revisadas las notas sobre forzar saltos de línea con n
23/06/2006 - V2.06
- Revisadas las notas sobre codificación de caracteres UTF-8. Eliminadas las tablas UTF-8 y ASCII
14/06/2006 - V2.05
- Creada esta página y los documentos asociados
- Cambiado la codificación de caracteres a UTF-8
- Añadidos procedimientos para probar el esquema y la codificación de caracteres
- Eliminada la opción de subida por FTP
12/05/2006 - V2.04
- Cambiadas las notas del nodo <date> para especificar un formato de fecha standard
19/04/2006 - V2.03
- Añadidas notas al nodo <desc> sobre saltos de linea
07/02/2006 - V2.02
- Añadidos los nodos <surface_area>, <built> y <plot> a los registros de propiedad
24/11/2005 - V2.01
- Añadidas notas sobre codificar & como &
- no usar etiqueta CDATA
- añadida nota sobre la etiqueta w3.org Description tag siendo ahora opcional
- Añadida nota sobre el formato de los precios
- Añadida nota sobre los nodos <leasehold> y <part_ownership> siendo de aplicación solo cuando <price_freq> esta marcado como 'sale'
- Añadido el nodo <primary> a las notas sobre imagenes
- Añadida nota sobre todos los nodos deben ir en minuscula
- Cambiado el nodo <Kyero> a <kyero>
27/05/2005 - V2.00
- Borrador inicial de la importacion V2