API Integration Guide

Documentación oficial de la API REST de HUB HOMES PR. Conecta tu CRM, sync de listings, o construye integraciones personalizadas.

Introducción

La API REST de HUB HOMES permite gestionar listings, búsquedas y consultar el catálogo público de propiedades. Endpoints diseñados para ser simples, predecibles y consistentes con estándares REST.

Respuestas siempre en formato application/json con UTF-8.

Autenticación

HUB HOMES usa autenticación basada en sesión vía Supabase Auth. Para endpoints de escritura (POST, PATCH, DELETE) debes incluir el token de sesión en cookies o como Authorization: Bearer header.

Obtener un access token

Primero autentícate vía Supabase Auth con email + contraseña. El token resultante se usa en las siguientes llamadas.

curl

curl -X POST "https://iyyxaainmwbsficwtxrw.supabase.co/auth/v1/token?grant_type=password" \
  -H "apikey: <NEXT_PUBLIC_SUPABASE_ANON_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"email":"agente@example.com","password":"tu-password"}'

# Respuesta:
# {
#   "access_token": "eyJhbGc...",
#   "refresh_token": "v1.MR...",
#   "expires_in": 3600,
#   "user": { ... }
# }

Usar el token en requests

curl

curl https://hubhomespr.com/api/listings \
  -H "Authorization: Bearer eyJhbGc..."

javascript

const res = await fetch('https://hubhomespr.com/api/listings', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
  },
});
const { data } = await res.json();

💡 Los endpoints GET de listings son públicos y no requieren token. Los endpoints POST/PATCH/DELETE requieren un usuario autenticado con rol agent, seller, o admin.

Base URL

Todos los endpoints comparten la misma base:

text

https://hubhomespr.com/api

Endpoints de Listings

GET/api/listings

Lista listings activos con filtros opcionales por tipo, ciudad, precio y habitaciones. Endpoint público (no requiere autenticación).

Query parameters

Parámetro	Tipo	Descripción
`type`	string	"sale" o "rent"
`city`	string	Búsqueda parcial por ciudad (ILIKE)
`min_price`	number	Precio mínimo
`max_price`	number	Precio máximo
`bedrooms`	number	Mínimo de habitaciones
`limit`	number	Resultados por página (default 20, máx 100)
`offset`	number	Paginación (default 0)

Ejemplo

curl

curl "https://hubhomespr.com/api/listings?type=sale&city=san+juan&min_price=200000&limit=10"

Respuesta

json

{
  "data": [
    {
      "id": "7237caa8-1982-4e11-b3a1-...",
      "title": "4 hab · 4 baños · DAVENPORT",
      "price": 850000,
      "type": "sale",
      "status": "active",
      "bedrooms": 4,
      "bathrooms": 4,
      "area_sqft": 2760,
      "address": "3012 KENSINGTON AVE",
      "city": "DAVENPORT",
      "state": "FL",
      "zip": "33837",
      "lat": 28.196,
      "lng": -81.602,
      "source": "stellar_mls",
      "mls_number": "MFR698602127",
      "brokerage_name": "Ricardo Reyes Realty",
      "brokerage_license": "C-17327",
      "media": [
        { "id": "...", "url": "https://...", "order": 0, "type": "photo" }
      ],
      "created_at": "2026-05-15T..."
    }
  ],
  "count": null
}

GET/api/listings/:id

Obtiene una propiedad por UUID. Incluye fotos y datos del agente. Endpoint público.

curl

curl https://hubhomespr.com/api/listings/7237caa8-1982-4e11-b3a1-f3a563fdf9c2

javascript

const res = await fetch('https://hubhomespr.com/api/listings/' + listingId);
const { data } = await res.json();
console.log(data.title, data.price);

POST/api/listings

Crea un nuevo listing. Requiere autenticación. El listing se crea bajo el usuario autenticado (profile_id se asigna automáticamente).

Body (JSON)

Campo	Tipo	Requerido
`title`	string	✓
`type`	"sale" \| "rent"	✓
`price`	number	✓
`bedrooms`	number	✓
`bathrooms`	number	✓
`area_sqft`	number	✓
`address`	string	✓
`city`	string	✓
`zip`	string	—
`lat`	number	—
`lng`	number	—
`description_es`	string	—
`status`	"draft" \| "active"	— (default: draft)

Ejemplo

curl

curl -X POST https://hubhomespr.com/api/listings \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Casa moderna en Bayamón",
    "type": "sale",
    "price": 350000,
    "bedrooms": 3,
    "bathrooms": 2,
    "area_sqft": 1800,
    "address": "Calle Principal 123",
    "city": "Bayamón",
    "zip": "00956",
    "status": "active"
  }'

javascript

const res = await fetch('https://hubhomespr.com/api/listings', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Casa moderna en Bayamón',
    type: 'sale',
    price: 350000,
    bedrooms: 3,
    bathrooms: 2,
    area_sqft: 1800,
    address: 'Calle Principal 123',
    city: 'Bayamón',
    zip: '00956',
    status: 'active',
  }),
});
const { data } = await res.json();
console.log('Listing creado:', data.id);

PATCH/api/listings/:id

Actualiza un listing existente. Solo el dueño del listing puede modificarlo (profile_id debe coincidir). Pasa solo los campos que quieras cambiar.

curl

curl -X PATCH https://hubhomespr.com/api/listings/UUID \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"price": 340000, "status": "active"}'

DELETE/api/listings/:id

Elimina un listing. Solo el dueño puede eliminarlo. Esta acción es irreversible.

curl

curl -X DELETE https://hubhomespr.com/api/listings/UUID \
  -H "Authorization: Bearer eyJhbGc..."

# Respuesta:
# { "success": true }

Códigos de error

Status	Significado
`200`	OK — petición exitosa
`201`	Created — recurso creado exitosamente
`400`	Bad Request — body inválido o falta un campo
`401`	Unauthorized — falta token o token expirado
`403`	Forbidden — no tienes permiso para esta acción (ej. modificar listing ajeno)
`404`	Not Found — recurso no existe
`409`	Conflict — duplicado o conflicto de estado
`500`	Internal Server Error — falla del servidor

Todos los errores devuelven JSON con la estructura:

json

{
  "error": "Mensaje descriptivo del error"
}

Rate limits

Para proteger la plataforma, los endpoints tienen los siguientes límites por defecto:

Endpoints públicos (GET): 100 requests por minuto por IP
Endpoints autenticados (POST/PATCH/DELETE): 30 requests por minuto por usuario
Plan Premium API: límites aumentados — consulta con tech@hubhomespr.com

Cuando excedas el límite, recibirás un status 429 Too Many Requests. Implementa backoff exponencial en tu cliente.

Changelog

v1.0 — Mayo 2026 — Endpoints iniciales: listings (GET / POST / PATCH / DELETE), búsqueda, suscripciones.

¿Listo para integrar?

Si tienes un CRM o sistema propio y quieres conectar a HUB HOMES, contáctanos para coordinar la integración y obtener acceso prioritario.

Solicitar integración