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
Alta de API

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:

Grilla de APIs

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:

APIPath
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:

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:

{ "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ódigoNombreDescripción
200OkPara las operaciones más exitosas
201CreadoOperación exitosa que crea datos
202AceptadoLa solicitud ha sido aceptada para el procesamiento pero el procesamiento aún no se ha completado
204Sin contenidoOperaciones exitosas que no devuelven ningún contenido (DELETE, por ejemplo)

Códigos de estado de error

CódigoNombreDescripción
400Solicitud incorrectaSolicitud con formato incorrecto (por ejemplo, tamaño demasiado grande)
401No autorizadoEl cliente no está autorizado (por ejemplo, falta el encabezado de la clave API)
402No autenticadoEl cliente no está autenticado (credenciales de autenticación no válidas)
403ProhibidoEl cliente está prohibido (por ejemplo, clave de API no válida)
404ExtraviadoEl recurso solicitado no se pudo encontrar
409ConflictoSu solicitud entra en conflicto con los datos existentes (por ejemplo, al intentar actualizar un anuncio que aún no se creó)
500error de servidor internoError 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.

Desplagable de autorización de API

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

URL de autorización de API

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

Autorización de API

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:

Visualización de API

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
{ "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" }, "sale": true, "sale_price": { "value": 250000, "currency": "USD" }, "rental": false, "temporal_rental": false, "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:

{ "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:

CampoDescripción
idEspecifica el valor univoco del aviso dentro de Spothia.com.
partnerCuando envias un aviso y la inmobiliaria no existe, se devuelve este valor univoco de la inmobiliaria dentro de Spothia.com.
branchCuando envias un aviso y la sucursal de la inmobiliaria no existe, se devuelve este valor univoco de la sucursal dentro de Spothia.com.
contactCuando 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.

CampoDescripción
partnerPartner / OpcionalEstablece la inmobiliaría que publica el anuncio. Si se especifica se visualiza el logo de la inmobiliaria. Ver Datos de la inmobiliaria
branchBranch / OpcionalEstablece la sucursal de la inmobiliaría que publica el anuncio. Si se establece, Partner es obligatorio. Ver Datos de la sucursal
contactContact / ObligatorioEstablece los datos de contacto del anuncio. Ver Datos de contacto
titleString / RequeridoEs el título del anuncio.
descriptionString / RequeridoEs la descripción del anuncio.
commentsString / OpcionalEs un comentario oculto del anuncio. Solo visible desde Back-End.
categoryString / RequeridoEs la categoría principal del anuncio. Ver Tabla de categorías
subcategoryString / Requerido / Depende si la categoría tiene sub-itemsEs la sub categoría del anuncio. Ver Tabla de categorías
priorityNumber / OpcionalEs la prioridad que asigna la inmobiliaria al anuncio. Solo visible desde Back-End.
  • 1 Baja
  • 2 Normal (valor por defecto)
  • 3 Alta
saleBoolean / RequeridoEspecifica si el anuncio es una venta.
sale_pricePrice / Requerido si es ventaEspecifica el precio y moneda de venta del anuncio. Ver Datos del precio
rentalBoolean / RequeridoEspecifica si el anuncio es por alquiler.
rental_pricePrice / Requerido si es alquilerEspecifica el precio y moneda del alquiler del anuncio. Ver Datos del precio
temporal_rentalBoolean / RequeridoEspecifica si el anuncio es por alquiler temporal.
temporal_rental_pricePrice / Requerido si es alquiler temporalEspecifica el precio y moneda del alquiler temporal del anuncio. Ver Datos del precio
expensesPrice / OpcionalEspecifica el precio y moneda de las expensas del anuncio. Ver Datos del precio
addressBoolean / 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
countryString / RequeridoEspecifica el país donde se encuentra la propiedad. Ver Tabla de localizaciones
stateString / RequeridoEspecifica la provincia donde se encuentra la propiedad. Ver Tabla de localizaciones
cityString / OpcionalEspecifica la ciudad donde se encuentra la propiedad. Ver Tabla de localizaciones
neighborhoodString / OpcionalEspecifica el barrio donde se encuentra la propiedad. Ver Tabla de localizaciones
streetString / OpcionalEspecifica la calle donde se encuentra la propiedad.
street_numberString / OpcionalEspecifica la altura de la calle donde se encuentra la propiedad.
floorString / OpcionalEspecifica el piso donde se encuentra la propiedad.
deptString / OpcionalEspecifica el departamento donde se encuentra la propiedad.
zipcodeString / OpcionalEspecifica el código postal donde se encuentra la propiedad.
latString / RequeridoEspecifica la latitud donde se encuentra la propiedad. Por ej: -34.6120059
lonString / RequeridoEspecifica la longitud donde se encuentra la propiedad. Por ej: -58.43009400
disposalString / OpcionalEspecifica la disposición de la propiedad. Ver Tabla de disposiciones
orientationString / OpcionalEspecifica la orientación de la propiedad. Ver Tabla de orientaciones
overall_statusString / OpcionalEspecifica el estado general de la propiedad. Ver Tabla de estados general
total_metersNumber / OpcionalEspecifica la cantidad total de metros cuadrados de la propiedad.
covered_metersNumber / OpcionalEspecifica la cantidad de metros cuadrados cubiertos de la propiedad.
environmentsNumber / OpcionalEspecifica los ambientes de la propiedad.
bedroomsNumber / OpcionalEspecifica los dormitorios de la propiedad.
bathroomsNumber / OpcionalEspecifica los baños de la propiedad.
toiletsNumber / OpcionalEspecifica los toilettes de la propiedad.
garagesNumber / OpcionalEspecifica las cocheras de la propiedad.
dependenceBoolean / Opcional / false por defectoEspecifica si la propiedad tiene dependencia.
professional_fitBoolean / Opcional / false por defectoEspecifica si la propiedad es apto profesional.
by_ownerBoolean / Opcional / false por defectoEspecifica si la transacción es por dueño directo.
apt_creditBoolean / Opcional / false por defectoEspecifica si la propiedad es apto crédito.
offers_financingBoolean / Opcional / false por defectoEspecifica si se ofrece financiamiento.
issue_invoiceBoolean / Opcional / false por defectoEspecifica si se emite factura.
accept_insuranceBoolean / Opcional / false por defectoEspecifica si se acepta seguro de caución.
accept_petsBoolean / Opcional / False por defectoEspecifica si se aceptan mascotas.
imagesImage Array / OpcionalEspecifica las imágenes del anuncio. Ver Datos de la imagen
plansImage Array / OpcionalEspecifica las imágenes con planos del anuncio. Ver Datos de la imagen
videosVideo Array / OpcionalEspecifica los videos del anuncio. Ver Datos del video
codeString / OpcionalCampo para ser utilizado por los integradores para especificar su identificador univoco.
idNumerico / 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.

CampoDescripción
account_typeString / OpcionalEstablece el tipo de cuenta de la inmobiliaria. Ver Tabla de tipos de cuenta
nameString / RequeridoEs el nombre comercial de la inmobiliaria.
business_nameString / RequeridoEs el nombre legal de la inmobiliaria.
tax_typeString / OpcionalEspecifica el tipo de inscripción de la inmobiliaria. Ver Tabla de tipos de inscripciones
tax_idString / OpcionalEspecifica el identificador legal de la inmobiliaria (Por ej.: CUIT).
imageImage / OpcionalEspecifica el logo de la inmobiliaria. Ver Datos de la imagen
emailString / OpcionalEspecifica la dirección de email de la inmobiliaria.
websiteString / OpcionalEspecifica el sitio web de la inmobiliaria.
phonePhone / OpcionalEspecifica el teléfono principal de la inmobiliaria. Ver Datos del teléfono
faxPhone / OpcionalEspecifica el teléfono de fax de la inmobiliaria. Ver Datos del teléfono
mobilePhone / OpcionalEspecifica el celular principal de la inmobiliaria. Ver Datos del teléfono
whatsappBoolean / OpcionalEspecifica si mobile tiene habilitado Whatsapp.
codeString / OpcionalCampo para ser utilizado por los integradores para especificar su identificador univoco.
idNumerico / 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.

CampoDescripción
nameString / RequeridoEs el nombre de la sucursal.
countryString / RequeridoEspecifica el país donde se encuentra la sucursal. Ver Tabla de localizaciones
stateString / RequeridoEspecifica la provincia donde se encuentra la sucursal. Ver Tabla de localizaciones
cityString / OpcionalEspecifica la ciudad donde se encuentra la sucursal. Ver Tabla de localizaciones
neighborhoodString / OpcionalEspecifica el barrio donde se encuentra la sucursal. Ver Tabla de localizaciones
streetString / OpcionalEspecifica la calle donde se encuentra la sucursal de la inmobiliaria.
street_numberString / OpcionalEspecifica la altura de la calle donde se encuentra la sucursal de la inmobiliaria.
floorString / OpcionalEspecifica el piso donde se encuentra la sucursal de la inmobiliaria.
deptString / OpcionalEspecifica el departamento donde se encuentra la sucursal de la inmobiliaria.
zipcodeString / OpcionalEspecifica el código postal donde se encuentra la sucursal de la inmobiliaria.
latString / RequeridoEspecifica la latitud donde se encuentra la sucursal. Por ej: -34.6120059
lonString / RequeridoEspecifica la longitud donde se encuentra la sucursal. Por ej: -58.43009400
emailString / OpcionalEspecifica la dirección de email de la sucursal.
phonePhone / OpcionalEspecifica el teléfono principal de la sucursal. Ver Datos del teléfono
faxPhone / OpcionalEspecifica el teléfono de fax de la sucursal. Ver Datos del teléfono
mobilePhone / OpcionalEspecifica el celular principal de la sucursal. Ver Datos del teléfono
whatsappBoolean / OpcionalEspecifica si mobile tiene habilitado Whatsapp.
codeString / OpcionalCampo para ser utilizado por los integradores para especificar su identificador univoco.
idNumerico / 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.

CampoDescripción
nameString / RequeridoEs el nombre de la persona de contacto.
last_nameString / OpcionalEs el apellido de la persona de contacto.
imageImage / OpcionalEspecifica el avatar del contacto. Ver Datos de la imagen
emailString / RequeridoEspecifica la dirección de email del contacto.
phonePhone / OpcionalEspecifica el teléfono principal del contacto. Ver Datos del teléfono
mobilePhone / OpcionalEspecifica el celular principal del contacto. Ver Datos del teléfono
whatsappBoolean / OpcionalEspecifica si mobile tiene habilitado Whatsapp.
countryString / RequeridoEspecifica el país donde se encuentra radicada la persona de contacto. Ver Tabla de países
languageString / OpcionalEspecifica el idioma principal de la persona de contacto. Ver Tabla de lenguajes
codeString / OpcionalCampo para ser utilizado por los integradores para especificar su identificador univoco.
idNumerico / 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.

CampoDescripción
valueNumber / RequeridoEspecifica el valor del precio.
currencyString / RequeridoEspecifica la moneda del precio. Ver Tabla de monedas

Datos de la imagen

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

CampoDescripción
urlString / RequeridoEspecifica la URL de la imagen.
captionString / 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.

CampoDescripción
urlString / 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.

CampoDescripción
prefixNumber / RequeridoEspecifica el prefijo del número teléfonico. Largo máximo de 5 posiciones.
numberNumber / 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.

ValorDescripción

Tabla de monedas

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

ValorDescripció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"}




Contacto

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