API de datos de solo lectura y deep-link de activación para partners para integrar los agentes de IA de Host Logic en su PMS o plataforma de gestión de propiedades. Esta página documenta únicamente lo que está disponible hoy — una sección de Roadmap claramente identificada cubre lo que viene a continuación.
Obtenga su clave de API → consulte el uso de plazas y las señales de precios → incruste el enlace de activación del host en su interfaz. Ese es el flujo de integración completo disponible hoy.
Obtenga su clave de API
Conviértase en partner. Una vez aprobado, Host Logic crea su cuenta de partner y le envía un enlace de revelación de un solo uso con su clave de API hlk_. Guárdela de forma segura — no podrá volver a mostrarse después de revelarla.
Consulte el uso y las señales de precios
Llame a GET /partner-api/v1/usage para supervisar el consumo de plazas, y a GET /partner-api/v1/properties/{id}/pricing-signals para mostrar los datos de precios de Marcus dentro de su plataforma.
Incruste el enlace de activación
Añada un botón en su interfaz que abra el deep-link firmado con HMAC https://hostlogic.io/partner/{slug}/activate?token=…. El host elige los productos, su cuenta de Host Logic se aprovisiona y Laura queda lista.
curl https://api.hostlogic.io/partner-api/v1/usage \
-H "Authorization: Bearer hlk_your_key_here" \
-H "Accept: application/json"
# 200 OK — la clave es válida, la respuesta contiene su uso de plazas
# 401 Unauthorized — falta la clave o no es válida
# 403 Forbidden — la clave es válida, pero falta el ámbito requerido
# 429 Too Many Requests — límite de velocidad (120 req/min)Todas las solicitudes a la API requieren un token Bearer en el encabezado Authorization. Recibe su clave de API tras la aprobación como partner mediante un enlace de revelación de un solo uso — la clave en texto plano nunca se almacena en el servidor y no puede volver a mostrarse.
Las claves de API llevan el prefijo hlk_, están asociadas a su cuenta de partner y pueden rotarse sin interrupción del servicio. Cada clave incluye un conjunto de ámbitos que determinan qué endpoints puede llamar. Los primeros 12 caracteres de cada clave (el prefijo de la clave) se almacenan en texto plano para su identificación en los registros — el resto se hashea.
https://api.hostlogic.io/partner-api/v1
Sandbox / DEV:https://api-dev.hostlogic.io/partner-api/v1
120 solicitudes/minuto por clave de API. Si se supera, se devuelve 429 Too Many Requests.
metrics:read — concedido siempre; cubre el endpoint de uso.marcus:read — concedido cuando su acuerdo de partner incluye datos de Marcus (Revenue Manager); cubre los endpoints de propiedades y señales de precios.
| Código | Significado |
|---|---|
401 | Falta la clave de API o no es válida |
403 | La clave es válida, pero falta el ámbito requerido para este endpoint |
404 | Recurso no encontrado, o no pertenece a la cuenta de su partner |
429 | Límite de solicitudes superado — 120 req/min |
curl https://api.hostlogic.io/partner-api/v1/usage \
-H "Authorization: Bearer hlk_a8f3c2e1b4d5..." \
-H "Accept: application/json"curl https://api.hostlogic.io/partner-api/v1/usage \
-H "X-Enterprise-Key: hlk_a8f3c2e1b4d5..." \
-H "Accept: application/json"Los siguientes endpoints y patrones de integración están en producción hoy. Todo lo que se enumera aquí es real y puede invocarse con una clave de API válida.
/usage
Uso de plazas para su cuenta de partner. Alcance: metrics:read (siempre concedido). Consulte la referencia completa a continuación.
/properties
Lista de propiedades pertenecientes a sus hosts patrocinados. Alcance: marcus:read. Consulte la referencia completa a continuación.
/properties/{propertyId}/pricing-signals
Señales de precios de Marcus y ocupación próxima para una propiedad patrocinada. Alcance: marcus:read. Consulte la referencia completa a continuación.
Deep-link de activación de partner
URL firmada con HMAC que aprovisiona una cuenta de host patrocinado. Integrada en su interfaz como un botón. Consulte la referencia completa a continuación.
Devuelve el número de plazas activas del partner autenticado, con un desglose por host. Útil para conciliar la facturación o crear un panel de uso dentro de su plataforma.
metrics:read — concedido siempre a todas las claves de partner.
Este endpoint solo devuelve datos del partner autenticado. Nunca acepta un parámetro de consulta partner_id — la identidad proviene بالكامل de su clave de API.
El desglose utiliza IDs opacos de usuarios host y recuentos de plazas. Los correos electrónicos de los hosts se excluyen intencionadamente.
curl https://api.hostlogic.io/partner-api/v1/usage \
-H "Authorization: Bearer hlk_a8f3c2e1b4d5..." \
-H "Accept: application/json"{
"partner_id": 1,
"generated_at": "2026-06-01T10:30:00Z",
"active_seats": 7,
"hosts": [
{ "host_user_id": 42, "active_seats": 4 },
{ "host_user_id": 67, "active_seats": 3 }
]
}Devuelve todas las propiedades pertenecientes a los hosts que patrocina su cuenta de partner. Úselo para descubrir qué propiedades puede consultar para obtener señales de precios.
marcus:read — concedido cuando su acuerdo de partner incluye el plano de datos de Marcus Revenue Manager.
Cada entrada contiene el id interno de la propiedad (necesario para el endpoint de pricing-signals) y el name de la propiedad. Se excluye la PII del host más allá del nombre de la propiedad.
curl https://api.hostlogic.io/partner-api/v1/properties \
-H "Authorization: Bearer hlk_a8f3c2e1b4d5..." \
-H "Accept: application/json"{
"partner_id": 1,
"generated_at": "2026-06-01T10:30:00Z",
"properties": [
{ "id": 12, "name": "Harbour View Apartment" },
{ "id": 17, "name": "Old Town Studio" }
]
}Devuelve las señales de precios de Marcus y la ocupación próxima de una sola propiedad patrocinada. Utilice los valores de id de propiedad devueltos por GET /properties. Se devuelve un 404 si la propiedad no se encuentra o no pertenece a su cuenta de partner.
marcus:read
lookback_days (entero, valor predeterminado 90) — ventana del historial de reservas utilizada para calcular las señales.
El objeto signals contiene indicadores de precios y estadísticas de reservas. El conjunto exacto de campos puede evolucionar a medida que Marcus añada nuevas fuentes de datos. El ejemplo representativo a continuación muestra los campos disponibles en el lanzamiento — trate cualquier campo no reconocido como adicional.
curl "https://api.hostlogic.io/partner-api/v1/properties/12/pricing-signals?lookback_days=90" \
-H "Authorization: Bearer hlk_a8f3c2e1b4d5..." \
-H "Accept: application/json"{
"property_id": 12,
"signals": {
"occupancy_today": 0.75,
"avg_lead_time_days": 18.4,
"avg_stay_nights": 3.2,
"source_mix": {
"booking.com": 0.62,
"direct": 0.38
},
"total_reservations": 87
},
"occupancy_30d": {
"2026-06-01": 0.75,
"2026-06-02": 0.80
}
}En lugar de una llamada REST, los hosts patrocinados por partners se incorporan mediante un deep-link firmado. El host hace clic, llega a un marketplace sin precios donde selecciona productos, y su cuenta de Host Logic se aprovisiona — patrocinada y sin necesidad de un pago aparte.
https://hostlogic.io/partner/{slug}/activate?token=<hmac-signed-token>
Donde {slug} es el identificador único de su cuenta de partner (proporcionado durante la incorporación) y token es una carga útil firmada con HMAC y de corta duración que contiene claims de identidad del host.
Los tokens se firman con HMAC-SHA256 usando el signing_secret de su partner (separado de su API key). El formato es:
<base64url-payload>.<sha256-hmac>
La carga útil incluye claims de identidad del host, una marca de tiempo de expiración en el servidor (exp) y un nonce aleatorio para evitar la reutilización del token.
Predeterminado: 1 hora. Los tokens caducados se rechazan con un mensaje de error claro — los hosts deben solicitar un enlace nuevo. Host Logic recomienda generar los enlaces bajo demanda (por ejemplo, cuando un host hace clic en un botón de su interfaz) en lugar de almacenarlos.
Hoy, los tokens de activación los genera Host Logic mediante una herramienta de administración, a solicitud. La generación de tokens en autoservicio por parte del partner (generarlos programáticamente desde su propio backend) está en la hoja de ruta — véase más abajo.
https://hostlogic.io/partner/previo/activate
?token=eyJjb250YWN0X2VtYWlsIjoiaG9zdEBleGFtcGxlLmNvbSIsImV4cCI6MTc1MDAwMDAwMCwibm9uY2UiOiJhYjEyY2QzNCJ9.a1b2c3d4e5f6...<!-- Simple button — opens in a new tab -->
<a href="{{ $activationUrl }}" target="_blank" class="btn">
Set up AI Receptionist →
</a>{
"contact_email": "[email protected]",
"contact_name": "Hotel Adriatic",
"previo_hotel_id": "779307",
"requested_product_ids": ["laura-receptionist"],
"exp": 1750000000,
"nonce": "ab12cd34"
}| Paso | Qué sucede |
|---|---|
| 1. Token verificado | Host Logic valida la firma HMAC y comprueba la caducidad. Los tokens inválidos o caducados muestran una página de error clara. |
| 2. Marketplace | El host llega a un marketplace de productos sin precios, limitado a su acuerdo de partner. Selecciona qué productos activar. |
| 3. Cuenta aprovisionada | Se crea una cuenta de host patrocinada de Host Logic (o se vincula si el correo electrónico ya existe). Los productos se activan sin paso de pago. |
| 4. Incorporación | El host es guiado por el asistente de base de conocimientos de Laura (instrucciones de check-in, preguntas frecuentes, ofertas de upsell). Laura empieza a responder a los huéspedes una vez que se envía el asistente. |
Las siguientes capacidades están planificadas o en desarrollo. Se enumeran aquí por transparencia para que pueda planificar su hoja de ruta de integración. Ninguna de ellas se puede invocar hoy — construir sobre ellas ahora provocará errores.
Generación de tokens en autoservicio para partners
Un endpoint de API o un fragmento de SDK descargable que permite a su backend generar tokens de activación firmados sin intervención de Host Logic. Hoy los tokens se generan a solicitud mediante una herramienta de administración.
Scopes de escritura y endpoints mutadores
Scopes como marcus:write y pierre:write y endpoints REST para registrar propiedades (POST /properties), activar o desactivar unidades individuales y actualizar la configuración del partner.
Webhooks / eventos en tiempo real
Notificaciones push para incorporación completada, unidad activada/desactivada y umbrales de uso. Registre una URL de webhook y reciba cargas útiles firmadas.
Portal de autoservicio para partners
Un portal de autoservicio con control por bandera para gestionar API keys, ver el uso de plazas y configurar los orígenes permitidos de embed. Actualmente en beta privada.
Endpoint de mantenimiento de Pierre
GET /properties/{propertyId}/operational-state — estado de mantenimiento y operativo de una propiedad patrocinada. Está desarrollado, pero desactivado mediante una bandera de funcionalidad; requiere el ámbito pierre:read. Disponible para socios seleccionados previa solicitud.
Incorporación del asistente de configuración en iframe
Incorpore el asistente de configuración de Laura como un iframe en la interfaz de su PMS, con eventos postMessage para el progreso de los pasos y la finalización. Depende del lanzamiento del portal de autoservicio para socios.
Servidor MCP alojado para empresas
Un endpoint MCP alojado en mcp.hostlogic.io que proporciona acceso a herramientas de Claude Desktop / Cursor para datos con ámbito de socio. Arquitectura prevista; aún no está en producción para socios empresariales.
Los socios empresariales cuentan con un canal dedicado de Slack con el equipo de Host Logic. Escríbanos a [email protected] para comentar sus requisitos de integración y plazos.
Cuéntenos sobre su PMS, channel manager o producto de software para hostelería. Revisamos las solicitudes de socios en un plazo de 2 días laborables y le proporcionamos su clave de API y un canal de soporte dedicado.