API de BYRO — Documentación

Documentación de la API

Todo lo que necesitas para conectar tu sitio con BYRO.

Cómo empezar

La API de BYRO te permite mostrar tu inventario en tu sitio web y recibir los interesados directamente en el CRM, sin capturar nada dos veces.

Todo vive en la dirección de tu inmobiliaria:

https://tuinmobiliaria.byro.mx/api/v1

Cada inmobiliaria tiene su propia dirección y sus propias llaves. Las creas desde Configuración → API dentro de BYRO.

Autenticación

Cada petición lleva tu llave en la cabecera X-API-Key:

X-API-Key: byro_a1b2c3d4…

También se acepta Authorization: Bearer, porque es lo que mandan muchas herramientas por omisión.

Una llave por integración

Puedes crear tantas como necesites, cada una con sus propios permisos. Así la llave que le das a quien hace tu sitio web sólo puede leer propiedades y registrar interesados —no ve tus contactos ni tus comisiones—, y si esa persona deja de trabajar contigo revocas la suya sin romper las demás integraciones.

La llave se muestra una sola vez

Al crearla. Después BYRO sólo guarda una huella, no la llave: si nuestra base se filtrara, no habría nada que usar. Si la pierdes, crea otra y revoca la anterior.

Límite de peticiones

120 por minuto. Si lo excedes recibes un 429 y basta con esperar. El límite protege el servicio de todos: un bucle mal escrito en un sitio no debe afectar a los demás.

Listar propiedades

GET/propiedades

El inventario publicado, con filtros y paginación.

Devuelve sólo las propiedades publicadas. Los borradores, las vendidas y las archivadas no aparecen: lo que no está a la venta no debe salir en ningún sitio.

Parámetro	Tipo	Por omisión	Para qué
`pagina`	entero	1	Qué página traer.
`limite`	entero	20	Cuántas por página. Máximo 50.
`operacion`	texto	—	venta, renta o renta_temporal.
`tipo`	texto	—	casa, departamento, terreno… Consulta /catalogos.
`colonia`	texto	—	Busca dentro del nombre de la colonia.
`recamaras_min`	entero	—	Recámaras mínimas.
`precio_min`	número	—	Precio mínimo, en la moneda de la operación.
`precio_max`	número	—	Precio máximo.

Respuesta

{
    "datos": [
        {
            "codigo": "BYRO-A1B2C3",
            "titulo": "Casa en Venta en Lomas de Chapultepec",
            "tipo": "casa",
            "operaciones": [
                {
                    "tipo": "venta",
                    "precio": 25000000,
                    "moneda": "MXN"
                }
            ],
            "recamaras": 4,
            "banos": 4.5,
            "estacionamientos": 3,
            "m2_terreno": 450,
            "m2_construccion": 380,
            "colonia": "Lomas de Chapultepec",
            "municipio": "Miguel Hidalgo",
            "estado": "Ciudad de México",
            "foto": "https://tuinmobiliaria.byro.mx/uploads/propiedades/abc123_md.jpg",
            "actualizada": "2026-08-08 14:32:00"
        }
    ],
    "paginacion": {
        "pagina": 1,
        "limite": 20,
        "total": 137,
        "paginas": 7
    }
}

Ver una propiedad

GET/propiedades/{codigo}

El detalle completo, con todas las fotos y amenidades.

Se busca por el código global —el que empieza con BYRO—, no por un identificador interno: ése puede cambiar, el código no.

La ubicación exacta sólo viene si la propiedad la publica. Cuando el asesor decidió reservarla, se devuelve `{"aproximada": true}` en vez de la dirección: esa decisión vale igual en la API que en la ficha pública.

Respuesta

{
    "datos": {
        "codigo": "BYRO-A1B2C3",
        "titulo": "Casa en Venta en Lomas de Chapultepec",
        "descripcion": "Residencia de tres niveles con acabados de primera…",
        "tipo": "casa",
        "operaciones": [
            {
                "tipo": "venta",
                "precio": 25000000,
                "moneda": "MXN"
            }
        ],
        "recamaras": 4,
        "fotos": [
            {
                "chica": "https://tuinmobiliaria.byro.mx/uploads/propiedades/abc_sm.jpg",
                "mediana": "https://tuinmobiliaria.byro.mx/uploads/propiedades/abc_md.jpg",
                "grande": "https://tuinmobiliaria.byro.mx/uploads/propiedades/abc_lg.jpg"
            }
        ],
        "amenidades": [
            {
                "slug": "alberca",
                "nombre": "Alberca"
            }
        ],
        "ubicacion": {
            "calle": "Sierra Madre",
            "numero": "415",
            "latitud": 19.4285,
            "longitud": -99.2105
        }
    }
}

Registrar un interesado

POST/leads

Lo que llama el formulario de contacto de tu sitio.

Si la persona ya existe en el CRM, no se duplica: se le suma el interés en esta propiedad y se avisa al asesor que ya la atiende.

Hace falta el nombre y **al menos** un teléfono o un correo. Sin una forma de contacto, nadie podría responderle.

Parámetro	Tipo	Por omisión	Para qué
`nombre`	texto	obligatorio	Nombre completo. Se separa solo en nombre y apellidos.
`telefono`	texto	—	Obligatorio si no mandas correo.
`email`	texto	—	Obligatorio si no mandas teléfono.
`mensaje`	texto	—	Lo que escribió la persona.
`propiedad`	texto	—	Código de la propiedad que le interesó.

Respuesta

{
    "datos": {
        "registrado": true,
        "mensaje": "Interesado registrado."
    }
}

Dónde hay inventario

GET/ubicaciones

Las zonas con propiedades, para el buscador de tu sitio.

Devuelve estados, municipios, colonias y fraccionamientos donde hay algo publicado, con cuántas propiedades tiene cada uno.

Sólo sale lo que de verdad tiene inventario: una lista con zonas vacías obliga a quien busca a probar una por una.

Cuando una zona está partida en secciones —Polanco I a V, Lomas de Chapultepec I a VIII— se añade una opción que las junta. Lleva `etiqueta` con el texto a mostrar y `nombre` con el valor a filtrar: se enseña «Polanco · todas las secciones» y se busca «Polanco», que por coincidencia parcial trae las cinco.

Parámetro	Tipo	Por omisión	Para qué
`q`	texto	—	Filtra por nombre. Desde dos letras. Sin él, devuelve todo.

Respuesta

{
    "datos": [
        {
            "nombre": "Polanco",
            "etiqueta": "Polanco · todas las secciones",
            "tipo": "colonia",
            "propiedades": 47
        },
        {
            "nombre": "Polanco V Sección",
            "tipo": "colonia",
            "propiedades": 16
        }
    ]
}

Avisar cuando entre algo

POST/alertas

Alguien pide que le avises de propiedades nuevas en una zona.

Registra a la persona como contacto —si ya existe, no se duplica— y guarda qué está buscando. Cuando se publique algo que encaje, le llega un correo con la propiedad y los datos de su asesor.

La zona se compara sin distinguir secciones: quien pide avisos de «Polanco» recibe lo de Polanco I, IV y V. También encaja contra el fraccionamiento y el municipio, porque en este segmento se busca por los tres indistintamente.

El correo es obligatorio: sin él no hay forma de avisar. Cada correo lleva su enlace de baja, así que no hace falta que lo gestiones.

Parámetro	Tipo	Por omisión	Para qué
`email`	texto	obligatorio	Adónde se manda el aviso.
`nombre`	texto	—	Se separa solo en nombre y apellidos.
`telefono`	texto	—	Para que el asesor pueda llamar.
`zona`	texto	obligatorio	Colonia, fraccionamiento o municipio.
`zona_nombre`	texto	—	Cómo se le enseña a la persona. Sin esto se usa `zona`.
`operacion`	texto	—	venta o renta. Sin esto, las dos.
`tipo`	texto	—	casa, departamento, terreno…
`precio_min`	número	—	Desde cuánto le interesa.
`precio_max`	número	—	Hasta cuánto.
`moneda`	texto	MXN	En qué moneda van los precios de arriba.
`origen`	texto	sitio	De dónde salió la petición, para tus informes.

Respuesta

{
    "datos": {
        "registrado": true,
        "mensaje": "Aviso registrado."
    }
}

Dejar de recibir avisos

GET/alertas/baja

El enlace que lleva cada correo al final.

Lo normal es que no tengas que llamarlo: el enlace va dentro de cada aviso y funciona solo. Está documentado por si quieres llevar a la persona a una página tuya en vez de a la de BYRO.

El token identifica la alerta y es de un solo uso. No hace falta que la persona entre a ninguna cuenta: pedírselo sería la forma más rápida de que marque el correo como no deseado.

Parámetro	Tipo	Por omisión	Para qué
`token`	texto	obligatorio	Viene en el enlace del correo.

Respuesta

{
    "datos": {
        "baja": true
    }
}

Entrar como cliente

POST/acceso

Para que alguien recupere sus propiedades guardadas.

Comprueba el correo y la contraseña de un contacto. Sirve si tu sitio ofrece una zona privada donde la persona vuelve a ver lo que marcó.

La respuesta no dice si el correo existe cuando falla: con un mensaje distinto para «no existe» y «contraseña mal», cualquiera podría averiguar qué correos están en tu base probando uno a uno.

Parámetro	Tipo	Por omisión	Para qué
`email`	texto	obligatorio	El correo del contacto.
`password`	texto	obligatorio	Su contraseña.

Respuesta

{
    "datos": {
        "ok": true,
        "contacto_id": 482
    }
}

Lo que alguien marcó como favorito

POST/contactos/{id}/guardadas

Guarda en el CRM las propiedades que un cliente marcó en tu sitio.

Los favoritos viven en el navegador de la persona. Mandándolos aquí, su asesor ve qué le interesó sin tener que preguntárselo, y puede llamar sabiendo de qué hablar.

Se manda la lista entera cada vez, no los cambios: así da igual si alguna petición se pierde por el camino.

Parámetro	Tipo	Por omisión	Para qué
`codigos`	lista	obligatorio	Los códigos de las propiedades marcadas.

Respuesta

{
    "datos": {
        "guardadas": 4
    }
}

Resolver un enlace compartido

POST/share/{codigo}

Cuando un asesor manda una propiedad por WhatsApp.

El asesor comparte un enlace con su firma. Al abrirlo, tu sitio llama aquí con el token y recibe de quién es ese enlace, para enseñar su teléfono y no el de la central.

De paso se anota la apertura, así que el asesor ve en el CRM que su enlace se abrió y cuándo.

Es POST y no GET porque registra algo: un GET se guardaría en la caché del navegador o de la red, y la segunda apertura no llegaría nunca.

Manda la dirección y el navegador de quien abrió. Sin eso, todas las aperturas parecen venir del mismo visitante —tu propio servidor— y las vistas previas de WhatsApp cuentan como aperturas reales.

Parámetro	Tipo	Por omisión	Para qué
`token`	texto	obligatorio	Viene en el enlace que compartió el asesor.
`ip`	texto	—	La de quien abrió, no la de tu servidor.
`user_agent`	texto	—	Su navegador. Sirve para filtrar vistas previas.

Respuesta

{
    "datos": {
        "asesor": {
            "nombre": "Gabriela García",
            "telefono": "55 1234 5678"
        },
        "aperturas": 3
    }
}

Si el sistema responde

GET/health

Para monitorizar BYRO desde fuera.

Comprueba que PHP responde, que la base contesta y que se puede escribir en disco. Devuelve 200 con `ok`, o 503 con `degraded` si algo falla.

Apúntalo en un servicio de monitorización. Vigilar sólo la portada no basta: puede cargar perfectamente mientras la base no responde, y el fallo se descubre cuando alguien del equipo no puede trabajar.

No hace falta llave: un monitor que necesita credenciales es un monitor que deja de funcionar el día que caducan.

Respuesta

{
    "status": "ok",
    "checks": {
        "database": "ok",
        "storage": "ok"
    }
}

Catálogos

GET/catalogos

Los valores válidos para filtrar.

Devuelve sólo lo que de verdad se usa en el inventario. Ofrecer un catálogo entero de opciones que ninguna propiedad tiene llenaría los filtros de tu sitio con categorías vacías.

Respuesta

{
    "datos": {
        "operaciones": [
            "venta",
            "renta",
            "renta_temporal"
        ],
        "tipos": [
            "casa",
            "departamento",
            "terreno"
        ],
        "amenidades": [
            {
                "slug": "alberca",
                "nombre": "Alberca"
            }
        ],
        "monedas": [
            "MXN",
            "USD"
        ]
    }
}

Errores

Todos vienen con la misma forma, y con un código legible además del número: te permite distinguir la causa sin depender del texto, que puede cambiar.

{
  "error": {
    "codigo": "sin_permiso",
    "mensaje": "Esta llave no tiene el permiso \"leads.crear\"."
  }
}

HTTP	Código	Qué pasó
`401`	`sin_llave`	No mandaste la cabecera X-API-Key.
`401`	`llave_invalida`	La llave no existe o fue revocada.
`403`	`sin_permiso`	La llave no tiene el permiso que esa ruta exige.
`404`	`no_encontrada`	No hay ninguna propiedad publicada con ese código.
`422`	`falta_nombre`	Falta el nombre del interesado.
`422`	`falta_contacto`	Falta teléfono y correo: hace falta al menos uno.
`422`	`email_invalido`	El correo no tiene formato válido.
`422`	`propiedad_no_encontrada`	El código de propiedad que mandaste no existe.
`429`	`demasiadas_peticiones`	Excediste el límite por minuto. Espera y reintenta.
`500`	`error_interno`	Algo falló de nuestro lado. Si persiste, avísanos.

Ejemplos

Cambia TU_LLAVE por la tuya y funcionan tal cual.

// Listar propiedades en venta
const r = await fetch('https://tuinmobiliaria.byro.mx/api/v1/propiedades?operacion=venta&limite=12', {
  headers: { 'X-API-Key': 'TU_LLAVE' }
});

const { datos, paginacion } = await r.json();

datos.forEach(p => {
  console.log(p.codigo, p.titulo, p.operaciones[0].precio);
});

<?php
// Listar propiedades en venta
$ch = curl_init('https://tuinmobiliaria.byro.mx/api/v1/propiedades?operacion=venta&limite=12');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: TU_LLAVE'],
]);

$r = json_decode(curl_exec($ch), true);
curl_close($ch);

foreach ($r['datos'] as $p) {
    echo $p['codigo'], ' — ', $p['titulo'], PHP_EOL;
}

# Listar propiedades en venta
curl 'https://tuinmobiliaria.byro.mx/api/v1/propiedades?operacion=venta&limite=12' \
  -H 'X-API-Key: TU_LLAVE'

# Registrar un interesado
curl -X POST 'https://tuinmobiliaria.byro.mx/api/v1/leads' \
  -H 'X-API-Key: TU_LLAVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "nombre": "María González",
    "email": "maria@ejemplo.com",
    "telefono": "5512345678",
    "mensaje": "Me interesa agendar una visita",
    "propiedad": "BYRO-A1B2C3"
  }'