API y webhooksConectá Alojando con tu propio sistema

Cómo empezar

1. En el panel, entrá a Configuración → API y webhooks y creá una clave. Se muestra una sola vez: guardala en un lugar seguro.
2. Mandala en cada pedido, en el encabezado Authorization como Bearer.
3. Probá con el pedido de abajo: te devuelve tus alojamientos.

curl https://alojando.app/api/v1/alojamientos \
  -H "Authorization: Bearer alj_live_…"

Qué se puede leer

Así se ve una reserva

{
  "id": "ical_cmv0bqsl0004hhbeengd9zff4",
  "alojamiento": { "id": "cmf2…", "nombre": "Depto Palermo 3B" },
  "canal": "airbnb",
  "canal_nombre": "Airbnb",
  "estado": "confirmada",
  "check_in": "2026-11-20",
  "check_out": "2026-11-24",
  "noches": 4,
  "huespedes": 2,
  "huesped": { "nombre": "Ana Pérez", "email": null, "telefono": "+54 9 11 5555-0000" },
  "codigo_confirmacion": "HMXXXXXXXX",
  "importe": {
    "moneda": "USD", "total": 412, "alojamiento": 372, "limpieza": 40,
    "huesped_adicional": null, "ajuste": null, "comision_portal_pct": 15.5
  },
  "pago": { "estado": null },
  "creada_en": "2026-10-14T13:02:11.000Z",
  "cancelada_en": null
}

El check_out es el día de salida (esa noche no se cuenta). Un dato que no tenemos va en null: por ejemplo, un calendario externo por iCal no trae importes ni datos del huésped, y no los completamos con estimaciones.

Webhooks

En el mismo panel agregás la dirección de tu servidor y elegís los eventos. Los cambios se revisan cada 5 minutos y cada aviso llega como un POST con un cuerpo JSON:

{
  "id": "evt_5f0c…",
  "evento": "reserva.creada",
  "creado_en": "2026-10-14T13:05:00.000Z",
  "datos": { "reserva": { … } }
}

Verificá la firma. Cada aviso trae el encabezado X-Alojando-Firma con la forma t=<unix>,v1=<hex>: un HMAC-SHA256 de "<t>.<cuerpo>" con el secreto del webhook (empieza con whsec_). Calculalo sobre el cuerpo tal como llegó, antes de parsearlo, y descartá los avisos con un t de más de 5 minutos.

import { createHmac, timingSafeEqual } from 'crypto'

// cuerpo: el cuerpo crudo (string), tal como llegó
function firmaValida(cuerpo, encabezado, secreto) {
  const partes = Object.fromEntries(encabezado.split(',').map((p) => p.split('=')))
  const t = Number(partes.t)
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false
  const esperada = createHmac('sha256', secreto).update(`${t}.${cuerpo}`).digest('hex')
  const a = Buffer.from(esperada)
  const b = Buffer.from(partes.v1 || '')
  return a.length === b.length && timingSafeEqual(a, b)
}

Reintentos. Respondé con un código 2xx en menos de 10 segundos. Si no, reintentamos al minuto, a los 5 y 30 minutos, a las 2, 6, 12 y 24 horas. El encabezado X-Alojando-Envio es el mismo en todos los reintentos: usalo para no procesar dos veces el mismo aviso. Un webhook que falla 50 veces seguidas se pausa y se reactiva desde el panel. Con "Mandar prueba" verificás la conexión en el acto.

Límites y reglas

• Es solo lectura: desde la API no se crean ni se modifican reservas.
• Hasta 120 pedidos por minuto por clave. Si te pasás, la respuesta es 429 con el encabezado Retry-After.
• Las fechas van en AAAA-MM-DD y los momentos en ISO 8601 (UTC).
• Los errores tienen siempre la misma forma: { "error": { "codigo", "mensaje" } }.
• Cada clave lee los datos de UN negocio, incluidos nombre, mail y teléfono de los huéspedes. Tratala como una contraseña; si se filtra, revocala desde el panel.