API

Todo lo que la aplicación hace con una villa, una reserva o un cliente es accesible por HTTP. Un script — o un agente — trabaja con los mismos datos que la interfaz, bajo las mismas reglas, sin sesión de navegador.

Esta página es el mapa: la autenticación, la forma de cada respuesta, y cada endpoint con la página que lo detalla. Cada endpoint tiene su propia página: una llamada, sus parámetros, sus respuestas y lo que rechaza.

Autenticación

Cada petición a /api/v1 lleva una clave API en la cabecera x-api-key. Una clave se crea desde Cuenta → Claves API y pertenece a una sola organización: esa organización es todo el alcance de la clave.

bash
curl -H "x-api-key: $VILLASLOT_API_KEY" \
  "https://villaslot.app/api/v1/me"

La organización nunca va en la petición

Ni en el cuerpo, ni en la URL, ni en una cabecera. Viene de la clave y de nada más. Un recurso que pertenece a otra organización responde 404, exactamente igual que un identificador que no existe.

La clave actúa como la persona que la creó

Una clave no es una segunda identidad con sus propios poderes. Lleva los derechos del miembro que la creó, en la organización para la que se creó. Nada es posible por la API que esa misma persona no pudiera hacer en la interfaz — y no se rechaza nada que sí pudiera hacer.

Una clave deja de funcionar cuando su portador deja la organización. Ningún acceso huérfano sobrevive a una salida: la clave responde 401 a partir de ese momento, exactamente como si se hubiera revocado. Revocar la clave de alguien que se ha ido es, por tanto, limpieza, no una corrección de seguridad.

Dos preguntas deciden cada llamada, y las dos tienen que superarse:

PreguntaLa decideRespuesta si falla
¿El portador sigue siendo miembro, y con qué rol?El portador de la clave y su rol401 / 403
¿El recurso pertenece a la organización de la clave?La organización de la clave404

Quién puede hacer qué

OperaciónRol mínimo en la organización
Leer cualquier cosamember
Crear y corregir clientes, crear y gestionar reservasmember
Crear, renombrar, archivar una villa, su foto, su horario, sus tarifasadmin
Cambiar las reglas de reserva de la organizaciónadmin

Ese reparto no es una decisión de la API: es la propia matriz de permisos del producto. Un miembro suele ser quien tiene al cliente al teléfono, y el producto reserva la configuración de las villas al propietario y a los administradores de la organización.

Sobre de respuesta

CasoCuerpo
Éxito{"success": true, "data": …}
Lista paginada{"success": true, "data": [...], "pagination": {"total", "page", "limit", "totalPages"}}
Error{"error": "…"}
Error de validación{"error": "…", "details": [ … field-level issues … ]}
Rechazo de negocio{"error": "…", "detail": { … reason, names, amounts … }}
EstadoCuándo
200Lectura o cambio realizado
201Recurso creado
401Clave ausente o no válida, o clave cuyo portador ha dejado la organización
403El portador es un miembro legítimo, pero su rol es demasiado bajo
404Recurso desconocido, o recurso de otra organización
409Conflicto de estado — una franja ocupada, un estado que ha cambiado, un límite del plan alcanzado
413Un lote por encima de su límite; el mensaje indica el límite
422Parámetros o cuerpo no válidos — details enumera los campos afectados
429Límite de peticiones de la clave superado (120 peticiones por minuto)
500Error inesperado del servidor

Un recurso de otra organización responde 404, nunca 403. Un 403 confirmaría que el identificador existe. La misma respuesta para un identificador desconocido y para uno que no tienes permiso para leer — no puedes distinguirlos, y esa es la idea. El 403 está reservado a la otra pregunta: estás en la organización correcta, pero tu rol es demasiado bajo.

Unidades y convenciones

  • Los importes son enteros en la unidad menor de la moneda de la organización. 1500000 en IDR son 15 000 rupias; 4500 en EUR son 45,00 €. Nunca dividas entre 100 sin conocer la moneda.
  • Los instantes están en ISO 8601 y en UTC (startAt, endAt, createdAt).
  • Los días y las horas son locales de la organización: una reserva se crea con date (YYYY-MM-DD) y startMinute (minutos desde la medianoche local). Lee settings.timezone en GET /api/v1/me.
  • El horario de apertura son minutos locales semanales, con dayOfWeek de 0 domingo … 6 sábado.

Cada endpoint

MétodoRutaQué haceRol
GET/api/v1/meMi contextomember
GET/api/v1/propertiesListar las villasmember
POST/api/v1/propertiesCrear una villaadmin
GET/api/v1/properties/{propertyId}Leer una villamember
PATCH/api/v1/properties/{propertyId}Renombrar una villaadmin
POST/api/v1/properties/{propertyId}/archiveArchivar una villaadmin
POST/api/v1/properties/{propertyId}/photoSubir una fotoadmin
GET/api/v1/properties/{propertyId}/opening-hoursLeer el horario de aperturamember
PUT/api/v1/properties/{propertyId}/opening-hoursReemplazar el horario de aperturaadmin
GET/api/v1/properties/{propertyId}/ratesLeer la cuadrícula de tarifasmember
PUT/api/v1/properties/{propertyId}/ratesReemplazar la cuadrícula de tarifasadmin
GET/api/v1/properties/{propertyId}/availabilityLeer la disponibilidadmember
GET/api/v1/bookingsListar las reservasmember
POST/api/v1/bookingsCrear una reservamember
GET/api/v1/bookings/{bookingId}Leer una reservamember
POST/api/v1/bookings/{bookingId}/confirmConfirmar una reservamember
POST/api/v1/bookings/{bookingId}/completeCompletar una reservamember
POST/api/v1/bookings/{bookingId}/cancelCancelar una reservamember
POST/api/v1/bookings/{bookingId}/rescheduleReprogramar una reservamember
GET/api/v1/customersListar los clientesmember
POST/api/v1/customersCrear un clientemember
POST/api/v1/customers/bulkImportar clientesmember
GET/api/v1/customers/{customerId}Leer un clientemember
PATCH/api/v1/customers/{customerId}Modificar un clientemember
GET/api/v1/settings/bookingLeer las reglas de reservamember
PATCH/api/v1/settings/bookingModificar las reglas de reservaadmin

Límite de peticiones

El límite lo lleva la clave, no la IP: 120 peticiones por minuto. Una clave por encima de su límite responde 429 en todos los endpoints. Espera y vuelve a intentarlo — no se ha hecho nada.

Por dónde empezar

Llama primero a GET /api/v1/me: convierte una simple clave en un contexto — la organización que abre, el rol que lleva, la zona horaria y la moneda de las que dependen todas las demás llamadas, y cuánto espacio deja el plan.

Después, el camino habitual: buscar o crear el cliente, pedir la disponibilidad de una villa, y crear la reserva. Toda la secuencia, con sus rechazos, se recorre en Crear una reserva.