Guía de Desarrollo

API (v1.01)

Introducción

Spothia comparte su API pública para socios. Permite integrarse fácilmente con sitios de terceros mediante la publicación y gestión de anuncios, y la comunicación con los usuarios de Spothia a través del sistema de mensajería interna. La documentación de la API es la misma para todos los países.

Creando la App

Aquí aprenderas a crear y administrar tus aplicaciones.

Crear la aplicación

Para crear la aplicación tenes que ir a la Consola de Apps y crear la nueva App.

Para crear tu aplicación, tenes proporcionar la siguiente información:

Nombre: el nombre de tu aplicación
Logotipo: un logotipo opcional que se visualizará en los detalles de los anuncios en nuestro Sitio. Tene en cuenta que solo aceptamos png, jpeg o webp cuadrado con una resolución máxima de 400x400 píxeles
URL: la URL de tu sitio web donde queres que se dirijan los usuarios cuando vean tu aplicación

Para realizar solicitudes a la API necesitaras:

Client Id: una cadena generada para identificar la aplicación
API Key: una cadena generada para autenticar la aplicación

Información sensible

El Client Id y API Key que te hemos proporcionado son información privada. Es muy importante que nunca los compartas con nadie. Recomendamos almacenarlos en variables de entorno.

Ya terminaste

Ahora podes ver tu nueva aplicación en la Consola de Apps:

Descripción general de las API

¿Qué APIs proporcionamos?

Visión general

Todas las API están disponibles a través de endpoint REST y aceptan JSON como el tipo de contenido para las solicitudes y las respuestas correspondientes. Todos los endpoint implementan el mismo mecanismo de autenticación.

La estructura genérica para un endpoint de API es: https://api.spothia.com/<api>/

Por ejemplo, el endpoint para administrar anuncios: https://api.spothia.com/announs/

APIs disponibles

Echa un vistazo a las API disponibles actualmente:

API	Path
AnunciosPermite gestionar los anuncios	/announs
EmpresasPermite gestionar los perfiles de las empresas (próximamente)	/partners
SucursalesPermite gestionar las sucursales de las empresas (próximamente)	/branchs
UsuariosPermite gestionar los usuarios (próximamente)	/contacts

Hacer solicitudes de API

Reglas y convenciones comunes para nuestras API

Lo esencial

Nuestras APIs están disponibles a través de HTTPS, exponiendo operaciones invocables con los verbos HTTP comunes POST, PUT y DELETE, con su comportamiento esperado correspondiente, es decir:

POST: para crear datos
PUT: para actualizar los datos
DELETE: para borrar datos

Endpoint base

La URL base de la API es https://api.spothia.com/<api>/.

Solo se admiten solicitudes HTTPS.

Autenticación

Todas las solicitudes requieren un encabezado con el Client Id y la API Key. Podes encontrar tu Client Id y API Key en el detalle de la aplicación en la Consola de Apps. Estas claves se utilizan para identificar la Aplicación y sirven como método de Autorización de primer nivel. Además, algunas llamadas a la API pueden requerir soporte de autorización OAuth2 o autorización básica.

Consulta la siguiente sección de esta guía para obtener más información sobre el proceso de autorización.

Solicitudes

Cualquier solicitud POST, PUT o DELETE debe tener su tipo de contenido establecido en application/json y el payload debe enviarse en el cuerpo de la solicitud.

Aquí hay un ejemplo de una invocación genérica de cURL, con la carga contenida en payload.json:

cURL
Java

api_key=YOUR_API_KEY client_id=YOUR_CLIENT_ID curl --request PUT \ --header "Authorization: key=$api_key" \ --header "Content-Type: application/json" \ --url "https://api.spothia.com/<api>/?client=$client_id" \ --data @payload.json

URL url = new URL("https://api.spothia.com/<api>/?client=" + getClientId()); HttpURLConnection httpURLConnection = (HttpURLConnection) url.openConnection(); httpURLConnection.setRequestProperty("Authorization", "key=" + getApiKey()); httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8"); return httpURLConnection

Respuestas

Las respuestas, cuando están presentes, se envían en formato JSON (tipo de contenido aplicación/json).

El formato de respuesta general de todas las APIs es el siguiente:

JSON

{ "code": 200, "msg": "Mensaje variable" }

El Código de estado HTTP siempre será 200. En el campo code se pueden esperar los siguientes códigos.

Códigos de estado de éxito

Código	Nombre	Descripción
200	Ok	Para las operaciones más exitosas
201	Creado	Operación exitosa que crea datos
202	Aceptado	La solicitud ha sido aceptada para el procesamiento pero el procesamiento aún no se ha completado
204	Sin contenido	Operaciones exitosas que no devuelven ningún contenido (DELETE, por ejemplo)

Códigos de estado de error

Código	Nombre	Descripción
400	Solicitud incorrecta	Solicitud con formato incorrecto (por ejemplo, tamaño demasiado grande)
401	No autorizado	El cliente no está autorizado (por ejemplo, falta el encabezado de la clave API)
402	No autenticado	El cliente no está autenticado (credenciales de autenticación no válidas)
403	Prohibido	El cliente está prohibido (por ejemplo, clave de API no válida)
404	Extraviado	El recurso solicitado no se pudo encontrar
409	Conflicto	Su solicitud entra en conflicto con los datos existentes (por ejemplo, al intentar actualizar un anuncio que aún no se creó)
500	error de servidor interno	Error del servidor durante el procesamiento (por ejemplo, servicio no disponible u otras condiciones anormales)

Autorizar una aplicación

A continuación tendrás los conceptos básicos de la autorización de tu aplicación

Visión general

La API autoriza a una aplicación a acceder a un recurso protegido de Spothia.

Flujo de autorización

Ejemplo

Tomaremos como ejemplo a RealEstateSite como la inmobiliaria que publica anuncios de inmuebles. Y PublisherSite como el sitio o aplicación que publica los anuncios de RealStateSite en sitios de terceros.

En caso de estar previamente registrada, RealEstateSite debe autorizar la aplicación de PublisherSite para publicar sus anuncios en Spothia.

Después de almacenar el Client Id y el API Key que se proporcionaron por la Consola de Apps, es hora de autorizar a PublisherSite para publicar anuncios de RealEstateSite.

Autorizar tu aplicación

Al iniciar el flujo de autorización, tu aplicación debe ser legible y ser identificada univocamente para que puedan identificarla y autorizarla a acceder a los datos de cuenta y/o ejecutar acciones en nombre de la inmobiliaria.

Para iniciar el flujo, tenes que ir a la Consola de Apps, obtener la URL de autorización de App y enviarsela a la inmobiliaria (RealEstateSite) para su posterior aprobación o rechazo.

Al hacer click en Autorización tendrás acceso a la URL para enviar a la inmobiliaria.

Un usuario Administrador de RealEstateSite deberá acceder a la URL de autorización de App para visualizar las siguientes opciones:

En caso de ser aprobado, tu App podrá publicar anuncios para RealEstateSite.

Visualizando tu App

Todos los avisos que han sido publicados con tu aplicación, visualizarán dentro del detalle del anuncio, tu aplicación, logo y brindaran acceso a la URL de la misma de la siguiente manera:

Publicando anuncios

Cómo publicar anuncios

Visión general

La publicación de anuncios es probablemente la razón principal por la que estás aquí. A estas alturas ya deberías tener una aplicación registrada, saber cómo realizar solicitudes y tener autorización de las inmobiliarias para poder publicar anuncios. Veamos cómo publicar un anuncio.

Flujo de trabajo básico

Para publicar un anuncio necesita la siguiente información:

Datos del anuncio: los datos reales del anuncio (ejemplo a continuación)
Datos de la inmobiliaria: los datos que permiten identificar univocamente la inmobiliaria
Datos del usuario: detos donde recibiran los mensajes

JSON

{ "title": "Departamento moderno en caballito con amenities", "description": "Lorem Ipsum es simplemente el texto de relleno de las imprentas y archivos de texto. Lorem Ipsum ha sido el texto de relleno estándar.", "category": "Casa", "subcategory": "Condominio", "priority": 2, "partner": { "name": "RealEstateSite", "business_name": "RealEstateSite SA", "image": { "url": "https://i.imgur.com/WozSfdQg.jpg" } }, "contact": { "name": "Juan Martinez", "email": "juan@martinez.com", "image": { "url": "https://i.imgur.com/WozSfdQg.jpg" }, "country": "Argentina" }, "operation": "sale", "price": { "value": 250000, "currency": "USD", "show": true }, "expenses": { "value": 5000, "currency": "ARS" }, "address": true, "country": "Argentina", "state": "Ciudad de Buenos Aires", "city": "Caballito", "street": "Rio de Janeiro", "street_number": "293", "floor": "PB", "dept": "A", "lat":"-34.6120059", "lon":"-58.43009400", "images": [ { "url": "https://i.imgur.com/WozSfdQg.jpg", "caption": "Baño" }, { "url": "https://i.imgur.com/3YNg1bI.jpg", "caption": "Cocina" } ], "plans": [ { "url": "https://i.imgur.com/WozSfdQg.jpg", "caption": "Baño" } ], "videos": [ { "url":"https://youtu.be/ySLc8gZ3oEc" } ] }

La respuesta más completa que podes obtener cuando envias un alta de aviso es la siguiente:

JSON

{ "code": 200, "msg": { "id": 50, "partner": 7, "branch": 23, "contact": 102 } }

Todos estos códigos pueden servirte para realizar futuros llamados haciendo referencia a cada una de las entidades particulares. Cada uno de estos campos en la respuesta representan los siguientes elementos:

Campo	Descripción
id	Especifica el valor univoco del aviso dentro de Spothia.com.
partner	Cuando envias un aviso y la inmobiliaria no existe, se devuelve este valor univoco de la inmobiliaria dentro de Spothia.com.
branch	Cuando envias un aviso y la sucursal de la inmobiliaria no existe, se devuelve este valor univoco de la sucursal dentro de Spothia.com.
contact	Cuando envias un aviso y la persona de contacto no existe, se devuelve este valor univoco de la persona dentro de Spothia.com.

Datos del anuncio

A continuación podes verificar la estructura completa del anuncio y una descripción de cada campo. Además de esto, un anuncio también puede contener una serie de atributos (en el campo atributos.valor), que se pueden consultar en la API de taxonomía.

Campo	Descripción
partner	Partner / OpcionalEstablece la inmobiliaría que publica el anuncio. Si se especifica se visualiza el logo de la inmobiliaria. Ver Datos de la inmobiliaria
branch	Branch / OpcionalEstablece la sucursal de la inmobiliaría que publica el anuncio. Si se establece, `Partner` es obligatorio. Ver Datos de la sucursal
contact	Contact / ObligatorioEstablece los datos de contacto del anuncio. Ver Datos de contacto
title	String / RequeridoEs el título del anuncio.
description	String / RequeridoEs la descripción del anuncio.
comments	String / OpcionalEs un comentario oculto del anuncio. Solo visible desde Back-End.
category	String / RequeridoEs la categoría principal del anuncio. Ver Tabla de categorías
subcategory	String / Requerido / Depende si la categoría tiene sub-itemsEs la sub categoría del anuncio. Ver Tabla de categorías
priority	Number / OpcionalEs la prioridad que asigna la inmobiliaria al anuncio. Solo visible desde Back-End. 1 Baja 2 Normal (valor por defecto) 3 Alta
operation	String / RequeridoEspecifica el tipo de operación: sale Venta rental Alquiler temporal_rental Alquiler por Temporada developer Desarrollo Inmobiliario
price	Price / RequeridoEspecifica el precio y moneda de venta del anuncio. Ver Datos del precio
expenses	Price / OpcionalEspecifica el precio y moneda de las expensas del anuncio. Ver Datos del precio
address	Boolean / RequeridoEspecifica si se visualiza la ubicación de la propiedad. true Ubicación exacta de la propiedad false No se visualiza la ubicación null Se muestra la ubicación aproximada de la propiedad
country	String / RequeridoEspecifica el país donde se encuentra la propiedad. Ver Tabla de localizaciones
state	String / RequeridoEspecifica la provincia donde se encuentra la propiedad. Ver Tabla de localizaciones
city	String / OpcionalEspecifica la ciudad donde se encuentra la propiedad. Ver Tabla de localizaciones
neighborhood	String / OpcionalEspecifica el barrio donde se encuentra la propiedad. Ver Tabla de localizaciones
street	String / OpcionalEspecifica la calle donde se encuentra la propiedad.
street_number	String / OpcionalEspecifica la altura de la calle donde se encuentra la propiedad.
floor	String / OpcionalEspecifica el piso donde se encuentra la propiedad.
dept	String / OpcionalEspecifica el departamento donde se encuentra la propiedad.
zipcode	String / OpcionalEspecifica el código postal donde se encuentra la propiedad.
lat	String / RequeridoEspecifica la latitud donde se encuentra la propiedad. Por ej: -34.6120059
lon	String / RequeridoEspecifica la longitud donde se encuentra la propiedad. Por ej: -58.43009400
disposal	String / OpcionalEspecifica la disposición de la propiedad. Ver Tabla de disposiciones
orientation	String / OpcionalEspecifica la orientación de la propiedad. Ver Tabla de orientaciones
overall_status	String / OpcionalEspecifica el estado general de la propiedad. Ver Tabla de estados general
total_meters	Number / OpcionalEspecifica la cantidad total de metros cuadrados de la propiedad.
covered_meters	Number / OpcionalEspecifica la cantidad de metros cuadrados cubiertos de la propiedad.
environments	Number / OpcionalEspecifica los ambientes de la propiedad.
bedrooms	Number / OpcionalEspecifica los dormitorios de la propiedad.
bathrooms	Number / OpcionalEspecifica los baños de la propiedad.
toilets	Number / OpcionalEspecifica los toilettes de la propiedad.
garages	Number / OpcionalEspecifica las cocheras de la propiedad.
dependence	Boolean / Opcional / false por defectoEspecifica si la propiedad tiene dependencia.
professional_fit	Boolean / Opcional / false por defectoEspecifica si la propiedad es apto profesional.
by_owner	Boolean / Opcional / false por defectoEspecifica si la transacción es por dueño directo.
apt_credit	Boolean / Opcional / false por defectoEspecifica si la propiedad es apto crédito.
offers_financing	Boolean / Opcional / false por defectoEspecifica si se ofrece financiamiento.
issue_invoice	Boolean / Opcional / false por defectoEspecifica si se emite factura.
accept_insurance	Boolean / Opcional / false por defectoEspecifica si se acepta seguro de caución.
accept_pets	Boolean / Opcional / False por defectoEspecifica si se aceptan mascotas.
images	Image Array / OpcionalEspecifica las imágenes del anuncio. Ver Datos de la imagen
plans	Image Array / OpcionalEspecifica las imágenes con planos del anuncio. Ver Datos de la imagen
videos	Video Array / OpcionalEspecifica los videos del anuncio. Ver Datos del video
code	String / OpcionalCampo para ser utilizado por los integradores para especificar su identificador univoco.
id	Numerico / OpcionalEspecifica el identificador univoco de Spothia para el anuncio. Se utiliza para operaciones de modificación y eliminación.

Datos de la inmobiliaria

A continuación podes verificar la estructura completa de la inmobiliaria y una descripción de cada campo.

Campo	Descripción
account_type	String / OpcionalEstablece el tipo de cuenta de la inmobiliaria. Ver Tabla de tipos de cuenta
name	String / RequeridoEs el nombre comercial de la inmobiliaria.
business_name	String / RequeridoEs el nombre legal de la inmobiliaria.
tax_type	String / OpcionalEspecifica el tipo de inscripción de la inmobiliaria. Ver Tabla de tipos de inscripciones
tax_id	String / OpcionalEspecifica el identificador legal de la inmobiliaria (Por ej.: CUIT).
image	Image / OpcionalEspecifica el logo de la inmobiliaria. Ver Datos de la imagen
email	String / OpcionalEspecifica la dirección de email de la inmobiliaria.
website	String / OpcionalEspecifica el sitio web de la inmobiliaria.
phone	Phone / OpcionalEspecifica el teléfono principal de la inmobiliaria. Ver Datos del teléfono
fax	Phone / OpcionalEspecifica el teléfono de fax de la inmobiliaria. Ver Datos del teléfono
mobile	Phone / OpcionalEspecifica el celular principal de la inmobiliaria. Ver Datos del teléfono
whatsapp	Boolean / OpcionalEspecifica si `mobile` tiene habilitado Whatsapp.
code	String / OpcionalCampo para ser utilizado por los integradores para especificar su identificador univoco.
id	Numerico / OpcionalEspecifica el identificador univoco de Spothia para el anuncio. Se utiliza para operaciones de modificación y eliminación.

Datos de la sucursal

A continuación podes verificar la estructura completa de la sucursal y una descripción de cada campo.

Campo	Descripción
name	String / RequeridoEs el nombre de la sucursal.
country	String / RequeridoEspecifica el país donde se encuentra la sucursal. Ver Tabla de localizaciones
state	String / RequeridoEspecifica la provincia donde se encuentra la sucursal. Ver Tabla de localizaciones
city	String / OpcionalEspecifica la ciudad donde se encuentra la sucursal. Ver Tabla de localizaciones
neighborhood	String / OpcionalEspecifica el barrio donde se encuentra la sucursal. Ver Tabla de localizaciones
street	String / OpcionalEspecifica la calle donde se encuentra la sucursal de la inmobiliaria.
street_number	String / OpcionalEspecifica la altura de la calle donde se encuentra la sucursal de la inmobiliaria.
floor	String / OpcionalEspecifica el piso donde se encuentra la sucursal de la inmobiliaria.
dept	String / OpcionalEspecifica el departamento donde se encuentra la sucursal de la inmobiliaria.
zipcode	String / OpcionalEspecifica el código postal donde se encuentra la sucursal de la inmobiliaria.
lat	String / RequeridoEspecifica la latitud donde se encuentra la sucursal. Por ej: -34.6120059
lon	String / RequeridoEspecifica la longitud donde se encuentra la sucursal. Por ej: -58.43009400
email	String / OpcionalEspecifica la dirección de email de la sucursal.
phone	Phone / OpcionalEspecifica el teléfono principal de la sucursal. Ver Datos del teléfono
fax	Phone / OpcionalEspecifica el teléfono de fax de la sucursal. Ver Datos del teléfono
mobile	Phone / OpcionalEspecifica el celular principal de la sucursal. Ver Datos del teléfono
whatsapp	Boolean / OpcionalEspecifica si `mobile` tiene habilitado Whatsapp.
code	String / OpcionalCampo para ser utilizado por los integradores para especificar su identificador univoco.
id	Numerico / OpcionalEspecifica el identificador univoco de Spothia para el anuncio. Se utiliza para operaciones de modificación y eliminación.

Datos de contacto

A continuación podes verificar la estructura completa del contacto y una descripción de cada campo.

Campo	Descripción
name	String / RequeridoEs el nombre de la persona de contacto.
last_name	String / OpcionalEs el apellido de la persona de contacto.
image	Image / OpcionalEspecifica el avatar del contacto. Ver Datos de la imagen
email	String / RequeridoEspecifica la dirección de email del contacto.
phone	Phone / OpcionalEspecifica el teléfono principal del contacto. Ver Datos del teléfono
mobile	Phone / OpcionalEspecifica el celular principal del contacto. Ver Datos del teléfono
whatsapp	Boolean / OpcionalEspecifica si `mobile` tiene habilitado Whatsapp.
country	String / RequeridoEspecifica el país donde se encuentra radicada la persona de contacto. Ver Tabla de países
language	String / OpcionalEspecifica el idioma principal de la persona de contacto. Ver Tabla de lenguajes
code	String / OpcionalCampo para ser utilizado por los integradores para especificar su identificador univoco.
id	Numerico / OpcionalEspecifica el identificador univoco de Spothia para el anuncio. Se utiliza para operaciones de modificación y eliminación.

Datos del precio

A continuación podes verificar la estructura completa del precio y una descripción de cada campo.

Campo	Descripción
value	Number / RequeridoEspecifica el valor del precio.
currency	String / RequeridoEspecifica la moneda del precio. Ver Tabla de monedas
show	Boolean / OpcionalEspecifica si se muestra el precio de la operación. Verdadero por defecto.

Datos de la imagen

A continuación podes verificar la estructura completa de la imagen y una descripción de cada campo.

Campo	Descripción
url	String / RequeridoEspecifica la URL de la imagen.
caption	String / OpcionalEspecifica el epígrafe de la imagen.

Datos del video

A continuación podes verificar la estructura completa del video y una descripción de cada campo.

Campo	Descripción
url	String / RequeridoEspecifica la URL del video. Se aceptan videos de YouTube.com y Vimeo.com.

Datos del teléfono

A continuación podes verificar la estructura completa del teléfono y una descripción de cada campo.

Campo	Descripción
prefix	Number / RequeridoEspecifica el prefijo del número teléfonico. Largo máximo de 5 posiciones.
number	Number / RequeridoEspecifica el número de teléfono. Largo máximo de 10 posiciones.

Tablas de valores

Verifica los valores posibles de todas las tablas que manejamos en nuestra API.

Tabla de categorias

A continuación podes verificar la tabla completa de categorías y sub categorías. Siendo que el campo category se corresponde al primer nivel del árbol y subcategory a los sub elementos.

Ejemplo

Para enviar una propiedad que es un Condomino, tendras que informar: {category: "Casa", subcategory: "Condominio"}

Para enviar una Cochera, tendras que informar: {category: "Cochera", subcategory: null}

Valor

Tabla de disposiciones

A continuación podes verificar la tabla completa de categorías.

Valor

Tabla de orientaciones

A continuación podes verificar la tabla completa de orientaciones.

Valor

Tabla de estados general

A continuación podes verificar la tabla completa de estados general.

Valor

Tabla de tipos de cuenta

A continuación podes verificar la tabla completa de tipos de cuenta.

Valor

Tabla de tipos de inscripciones

A continuación podes verificar la tabla completa de tipos de inscripciones.

Valor

Tabla de idiomas

A continuación podes verificar la tabla completa de idiomas.

Valor	Descripción

Tabla de monedas

A continuación podes verificar la tabla completa de monedas.

Valor	Descripción

Tabla de localizaciones

A continuación podes verificar la tabla completa de localizaciones. Los datos obligatorios a informar son country y state.

Ejemplo

Para enviar una propiedad que se encuentra en Caballito, Ciudad de Buenos Aires, Argentina, tendras que informar: {country: "Argentina", state: "Ciudad de Buenos Aires", city: "Caballito"}

Country

State

City

Neighborhood

Contacto

Si usted está experimentando dificultades por el uso de este Sitio, por favor contáctenos.

¡Bienvenido a Spothia!

Guía de Desarrollo

Introducción

Creando la App

Crear la aplicación

Información sensible

Ya terminaste

Descripción general de las API

Visión general

APIs disponibles

Hacer solicitudes de API

Lo esencial

Endpoint base

Autenticación

Solicitudes

Respuestas

Códigos de estado de éxito

Códigos de estado de error

Autorizar una aplicación

Visión general

Flujo de autorización

Ejemplo

Autorizar tu aplicación

Visualizando tu App

Publicando anuncios

Visión general

Flujo de trabajo básico

Datos del anuncio

Datos de la inmobiliaria

Datos de la sucursal

Datos de contacto

Datos del precio

Datos de la imagen

Datos del video

Datos del teléfono

Tablas de valores

Tabla de categorias

Ejemplo

Tabla de disposiciones

Tabla de orientaciones

Tabla de estados general

Tabla de tipos de cuenta

Tabla de tipos de inscripciones

Tabla de idiomas

Tabla de monedas

Tabla de localizaciones

Ejemplo

Contacto