{ "openapi": "3.1.0", "info": { "title": "Gesti\u00f3n Hotelera API", "version": "1.0.0", "description": "# API REST \u2014 Sistema de Gesti\u00f3n Hotelera\n\nAPI versionada bajo **`\/api\/v1`** para administrar hoteles, consultar cat\u00e1logos maestros y configurar la distribuci\u00f3n de habitaciones por tipo y acomodaci\u00f3n.\n\n## Arquitectura\n\n- **Backend:** Laravel 13 \u00b7 PHP 8.4 \u00b7 arquitectura hexagonal (Domain \/ Application \/ Infrastructure).\n- **Persistencia:** PostgreSQL.\n- **Contrato:** JSON sobre HTTP; colecciones envueltas en `{ \"data\": [...] }` (Laravel API Resources).\n- **Autenticaci\u00f3n:** no requerida en esta prueba t\u00e9cnica (endpoints p\u00fablicos).\n\n## Convenciones\n\n| Aspecto | Detalle |\n|--------|---------|\n| **Base URL** | `{APP_URL}\/api\/v1` |\n| **Content-Type** | `application\/json` en peticiones con cuerpo |\n| **Identificadores** | Enteros autoincrementales |\n| **Errores de validaci\u00f3n (422)** | `{ \"message\": \"...\", \"errors\": { \"campo\": [\"...\"] } }` |\n| **Errores de dominio (404\/422)** | `{ \"message\": \"Descripci\u00f3n legible del error\" }` |\n| **Eliminaciones exitosas** | HTTP `204` sin cuerpo |\n\n## Cat\u00e1logos\n\nDatos sembrados al desplegar (`CatalogSeeder`). Son de solo lectura v\u00eda API.\n\n### Tipos de habitaci\u00f3n\n\n| Slug | Nombre |\n|------|--------|\n| `estandar` | Est\u00e1ndar |\n| `junior` | Junior |\n| `suite` | Suite |\n\n### Reglas tipo \u2194 acomodaci\u00f3n\n\n| Tipo | Acomodaciones permitidas |\n|------|--------------------------|\n| **Est\u00e1ndar** | Sencilla, Doble |\n| **Junior** | Triple, Cu\u00e1druple |\n| **Suite** | Sencilla, Doble, Triple |\n\nUse `GET \/room-types\/{roomTypeId}\/accommodations` para obtener solo las acomodaciones v\u00e1lidas de un tipo antes de crear o editar configuraciones.\n\n## Hoteles\n\nUn hotel tiene: nombre, direcci\u00f3n, ciudad (`city_id`), **NIT \u00fanico** (formato `12345678-9`) y **m\u00e1ximo de habitaciones** (`max_rooms`).\n\nAl consultar un hotel se incluyen:\n\n- `configured_rooms` \u2014 suma de cantidades en configuraciones.\n- `available_rooms` \u2014 `max_rooms - configured_rooms`.\n- `room_configurations` \u2014 detalle de cada combinaci\u00f3n tipo\/acomodaci\u00f3n.\n\n## Configuraciones de habitaci\u00f3n\n\nCada configuraci\u00f3n asocia a un hotel:\n\n- `room_type_id` \u2014 tipo de habitaci\u00f3n.\n- `accommodation_id` \u2014 acomodaci\u00f3n (debe ser compatible con el tipo).\n- `quantity` \u2014 n\u00famero de habitaciones de esa combinaci\u00f3n.\n\n### Reglas de negocio\n\n1. **Unicidad:** no puede repetirse la misma tripleta `(hotel_id, room_type_id, accommodation_id)`.\n2. **Capacidad:** la suma de `quantity` de todas las configuraciones del hotel no puede superar `max_rooms`.\n3. **Compatibilidad:** la acomodaci\u00f3n debe estar permitida para el tipo seleccionado.\n4. **NIT \u00fanico:** dos hoteles no pueden compartir el mismo NIT.\n5. **Reducci\u00f3n de cupo:** no se puede bajar `max_rooms` por debajo de las habitaciones ya configuradas.\n\n## Flujo recomendado (SPA \/ integraci\u00f3n)\n\n1. `GET \/cities` \u2014 poblar selector de ciudad.\n2. `GET \/room-types` \u2014 tipos disponibles.\n3. `POST \/hotels` \u2014 crear hotel.\n4. `GET \/room-types\/{id}\/accommodations` \u2014 acomodaciones v\u00e1lidas al agregar habitaciones.\n5. `POST \/hotels\/{hotelId}\/room-configurations` \u2014 agregar configuraciones.\n6. `GET \/hotels\/{id}` \u2014 ver resumen con totales.\n\n## Documentaci\u00f3n adicional\n\n- Especificaci\u00f3n OpenAPI manual: `\/documentacion\/openapi`\n- Diagramas UML: `\/documentacion\/uml`\n- C\u00f3digo fuente: [github.com\/izi-dev\/prueba-hotel](https:\/\/github.com\/izi-dev\/prueba-hotel)" }, "servers": [ { "url": "https:\/\/fvargas.dezeo.cloud\/api\/v1", "description": "Producci\u00f3n" }, { "url": "https:\/\/fvargas.dezeo.cloud\/api\/v1", "description": "Local" } ], "tags": [ { "name": "Cat\u00e1logos", "description": "Consulta de datos maestros: ciudades, tipos de habitaci\u00f3n y acomodaciones. Incluye el filtrado de acomodaciones v\u00e1lidas por tipo." }, { "name": "Hoteles", "description": "CRUD de hoteles con validaci\u00f3n de NIT \u00fanico, ciudad existente y control del cupo m\u00e1ximo de habitaciones." }, { "name": "Configuraciones", "description": "Gesti\u00f3n de la distribuci\u00f3n de habitaciones por hotel seg\u00fan tipo, acomodaci\u00f3n y cantidad, respetando reglas de negocio." } ], "paths": { "\/v1\/cities": { "get": { "operationId": "catalogs.cities.index", "description": "Devuelve el cat\u00e1logo completo de ciudades disponibles para asociar a un hotel.", "summary": "Listar ciudades", "tags": [ "Cat\u00e1logos" ], "responses": { "200": { "description": "`CityCollection`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CityCollection" } }, "required": [ "data" ] } } } } } } }, "\/v1\/room-types": { "get": { "operationId": "catalogs.roomTypes.index", "description": "Devuelve los tipos de habitaci\u00f3n del sistema: Est\u00e1ndar, Junior y Suite.", "summary": "Listar tipos de habitaci\u00f3n", "tags": [ "Cat\u00e1logos" ], "responses": { "200": { "description": "`RoomTypeCollection`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/RoomTypeCollection" } }, "required": [ "data" ] } } } } } } }, "\/v1\/room-types\/{roomTypeId}\/accommodations": { "get": { "operationId": "catalogs.roomTypes.accommodations", "description": "Lista solo las acomodaciones permitidas para el tipo indicado seg\u00fan las reglas de negocio (Est\u00e1ndar\u2192Sencilla\/Doble, Junior\u2192Triple\/Cu\u00e1druple, Suite\u2192Sencilla\/Doble\/Triple).", "summary": "Acomodaciones por tipo de habitaci\u00f3n", "tags": [ "Cat\u00e1logos" ], "parameters": [ { "name": "roomTypeId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`AccommodationCollection`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AccommodationCollection" } }, "required": [ "data" ] } } } } } } }, "\/v1\/accommodations": { "get": { "operationId": "catalogs.accommodations.index", "description": "Devuelve todas las acomodaciones (Sencilla, Doble, Triple, Cu\u00e1druple). Para filtrar por tipo use el endpoint anidado bajo `room-types`.", "summary": "Listar acomodaciones", "tags": [ "Cat\u00e1logos" ], "responses": { "200": { "description": "`AccommodationCollection`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AccommodationCollection" } }, "required": [ "data" ] } } } } } } }, "\/v1\/hotels": { "get": { "operationId": "hotels.index", "description": "Devuelve todos los hoteles registrados con resumen de habitaciones configuradas y disponibles.", "summary": "Listar hoteles", "tags": [ "Hoteles" ], "responses": { "200": { "description": "`HotelCollection`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/HotelCollection" } }, "required": [ "data" ] } } } } } }, "post": { "operationId": "hotels.store", "description": "Registra un hotel nuevo. El NIT debe ser \u00fanico en todo el sistema y tener el formato `12345678-9`.", "summary": "Crear hotel", "tags": [ "Hoteles" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreHotelRequest" } } } }, "responses": { "201": { "description": "Hotel creado correctamente.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Hotel" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/v1\/hotels\/{id}": { "get": { "operationId": "hotels.show", "description": "Devuelve el detalle del hotel, incluyendo configuraciones de habitaci\u00f3n y totales calculados.", "summary": "Obtener hotel", "tags": [ "Hoteles" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`Hotel`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Hotel" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/HotelNotFoundException" } } }, "put": { "operationId": "hotels.update", "description": "Modifica los datos del hotel. No se puede reducir `max_rooms` por debajo del total de habitaciones ya configuradas ni reutilizar un NIT de otro hotel.", "summary": "Actualizar hotel", "tags": [ "Hoteles" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateHotelRequest" } } } }, "responses": { "200": { "description": "`Hotel`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Hotel" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/HotelNotFoundException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "hotels.destroy", "description": "Elimina el hotel y todas sus configuraciones de habitaci\u00f3n asociadas.", "summary": "Eliminar hotel", "tags": [ "Hoteles" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Hotel eliminado correctamente.", "content": { "application\/json": { "schema": { "type": "string" } } } }, "404": { "$ref": "#\/components\/responses\/HotelNotFoundException" } } } }, "\/v1\/hotels\/{hotelId}\/room-configurations": { "get": { "operationId": "hotels.roomConfigurations.index", "description": "Devuelve todas las configuraciones de habitaci\u00f3n asociadas al hotel indicado.", "summary": "Listar configuraciones de habitaci\u00f3n", "tags": [ "Configuraciones" ], "parameters": [ { "name": "hotelId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`HotelRoomConfigurationCollection`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/HotelRoomConfigurationCollection" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/HotelNotFoundException" } } }, "post": { "operationId": "hotels.roomConfigurations.store", "description": "Asigna un tipo de habitaci\u00f3n, acomodaci\u00f3n y cantidad a un hotel. Valida compatibilidad tipo-acomodaci\u00f3n, unicidad de la combinaci\u00f3n y cupo m\u00e1ximo del hotel.", "summary": "Crear configuraci\u00f3n de habitaci\u00f3n", "tags": [ "Configuraciones" ], "parameters": [ { "name": "hotelId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreRoomConfigurationRequest" } } } }, "responses": { "201": { "description": "Configuraci\u00f3n creada correctamente.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/HotelRoomConfiguration" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/HotelNotFoundException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/v1\/hotels\/{hotelId}\/room-configurations\/{configurationId}": { "put": { "operationId": "hotels.roomConfigurations.update", "description": "Modifica tipo, acomodaci\u00f3n o cantidad de una configuraci\u00f3n existente, aplicando las mismas reglas de negocio que en la creaci\u00f3n.", "summary": "Actualizar configuraci\u00f3n de habitaci\u00f3n", "tags": [ "Configuraciones" ], "parameters": [ { "name": "hotelId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "configurationId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateRoomConfigurationRequest" } } } }, "responses": { "200": { "description": "`HotelRoomConfiguration`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/HotelRoomConfiguration" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/HotelNotFoundException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "hotels.roomConfigurations.destroy", "description": "Elimina una configuraci\u00f3n del hotel. La configuraci\u00f3n debe existir y pertenecer al hotel indicado en la URL.", "summary": "Eliminar configuraci\u00f3n de habitaci\u00f3n", "tags": [ "Configuraciones" ], "parameters": [ { "name": "hotelId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "configurationId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Configuraci\u00f3n eliminada correctamente.", "content": { "application\/json": { "schema": { "type": "string" } } } }, "404": { "$ref": "#\/components\/responses\/RoomConfigurationNotFoundException" } } } } }, "components": { "schemas": { "AccommodationCollection": { "type": "array", "items": { "$ref": "#\/components\/schemas\/AccommodationResource" }, "title": "AccommodationCollection" }, "AccommodationResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "title": "AccommodationResource" }, "CityCollection": { "type": "array", "items": { "$ref": "#\/components\/schemas\/CityResource" }, "title": "CityCollection" }, "CityResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "title": "CityResource" }, "Hotel": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Identificador \u00fanico del hotel." }, "name": { "type": "string", "description": "Nombre comercial." }, "address": { "type": "string", "description": "Direcci\u00f3n f\u00edsica." }, "city_id": { "type": "integer", "description": "ID de la ciudad asociada." }, "city_name": { "type": [ "string", "null" ], "description": "Nombre de la ciudad (desnormalizado)." }, "nit": { "type": "string", "description": "NIT \u00fanico con formato `12345678-9`." }, "max_rooms": { "type": "integer", "description": "Cupo m\u00e1ximo de habitaciones del hotel." }, "configured_rooms": { "description": "Suma de cantidades en todas las configuraciones.", "anyOf": [ { "type": "integer" }, { "type": "number" } ] }, "available_rooms": { "type": "string", "description": "Habitaciones a\u00fan disponibles para configurar (`max_rooms - configured_rooms`)." }, "room_configurations": { "type": "array", "description": "Detalle de configuraciones por tipo y acomodaci\u00f3n.", "items": { "$ref": "#\/components\/schemas\/HotelRoomConfiguration" } } }, "required": [ "id", "name", "address", "city_id", "city_name", "nit", "max_rooms", "configured_rooms", "available_rooms", "room_configurations" ], "title": "Hotel" }, "HotelCollection": { "type": "array", "items": { "$ref": "#\/components\/schemas\/Hotel" }, "title": "HotelCollection" }, "HotelRoomConfiguration": { "type": "object", "properties": { "id": { "type": "integer", "description": "Identificador de la configuraci\u00f3n." }, "hotel_id": { "type": "integer", "description": "Hotel al que pertenece." }, "room_type_id": { "type": "integer", "description": "Tipo de habitaci\u00f3n configurado." }, "room_type_name": { "type": [ "string", "null" ], "description": "Nombre del tipo de habitaci\u00f3n." }, "accommodation_id": { "type": "integer", "description": "Acomodaci\u00f3n configurada." }, "accommodation_name": { "type": [ "string", "null" ], "description": "Nombre de la acomodaci\u00f3n." }, "quantity": { "type": "integer", "description": "Cantidad de habitaciones de esta combinaci\u00f3n." } }, "required": [ "id", "hotel_id", "room_type_id", "room_type_name", "accommodation_id", "accommodation_name", "quantity" ], "title": "HotelRoomConfiguration" }, "HotelRoomConfigurationCollection": { "type": "array", "items": { "$ref": "#\/components\/schemas\/HotelRoomConfiguration" }, "title": "HotelRoomConfigurationCollection" }, "RoomTypeCollection": { "type": "array", "items": { "$ref": "#\/components\/schemas\/RoomTypeResource" }, "title": "RoomTypeCollection" }, "RoomTypeResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "title": "RoomTypeResource" }, "StoreHotelRequest": { "type": "object", "description": "Solicitud HTTP para crear un hotel.\n\nValida los datos de entrada del endpoint `POST \/api\/v1\/hotels`.", "properties": { "name": { "type": "string", "description": "Nombre comercial del hotel. @example Hotel Bogot\u00e1 Plaza", "maxLength": 255 }, "address": { "type": "string", "description": "Direcci\u00f3n f\u00edsica del establecimiento. @example Carrera 7 # 71-21", "maxLength": 500 }, "city_id": { "type": "integer", "description": "Identificador de la ciudad (`GET \/api\/v1\/cities`). @example 1" }, "nit": { "type": "string", "description": "NIT \u00fanico con formato d\u00edgitos-d\u00edgito verificador. @example 900123456-7", "pattern": "^\\d+-\\d$", "maxLength": 20 }, "max_rooms": { "type": "integer", "description": "Cupo m\u00e1ximo total de habitaciones que puede configurarse. @example 120", "minimum": 1 } }, "required": [ "name", "address", "city_id", "nit", "max_rooms" ], "title": "StoreHotelRequest" }, "StoreRoomConfigurationRequest": { "type": "object", "description": "Solicitud HTTP para crear una configuraci\u00f3n de habitaci\u00f3n.", "properties": { "room_type_id": { "type": "integer", "description": "Tipo de habitaci\u00f3n (`GET \/api\/v1\/room-types`). @example 1" }, "accommodation_id": { "type": "integer", "description": "Acomodaci\u00f3n compatible con el tipo (`GET \/api\/v1\/room-types\/{id}\/accommodations`). @example 2" }, "quantity": { "type": "integer", "description": "Cantidad de habitaciones de esta combinaci\u00f3n. @example 10", "minimum": 1 } }, "required": [ "room_type_id", "accommodation_id", "quantity" ], "title": "StoreRoomConfigurationRequest" }, "UpdateHotelRequest": { "type": "object", "description": "Solicitud HTTP para actualizar un hotel.", "properties": { "name": { "type": "string", "description": "Nombre comercial del hotel. @example Hotel Bogot\u00e1 Plaza", "maxLength": 255 }, "address": { "type": "string", "description": "Direcci\u00f3n f\u00edsica del establecimiento. @example Carrera 7 # 71-21", "maxLength": 500 }, "city_id": { "type": "integer", "description": "Identificador de la ciudad (`GET \/api\/v1\/cities`). @example 1" }, "nit": { "type": "string", "description": "NIT \u00fanico con formato d\u00edgitos-d\u00edgito verificador. @example 900123456-7", "pattern": "^\\d+-\\d$", "maxLength": 20 }, "max_rooms": { "type": "integer", "description": "Cupo m\u00e1ximo; no puede ser menor que las habitaciones ya configuradas. @example 120", "minimum": 1 } }, "required": [ "name", "address", "city_id", "nit", "max_rooms" ], "title": "UpdateHotelRequest" }, "UpdateRoomConfigurationRequest": { "type": "object", "description": "Solicitud HTTP para actualizar una configuraci\u00f3n de habitaci\u00f3n.", "properties": { "room_type_id": { "type": "integer", "description": "Tipo de habitaci\u00f3n (`GET \/api\/v1\/room-types`). @example 1" }, "accommodation_id": { "type": "integer", "description": "Acomodaci\u00f3n compatible con el tipo. @example 2" }, "quantity": { "type": "integer", "description": "Nueva cantidad de habitaciones para esta combinaci\u00f3n. @example 15", "minimum": 1 } }, "required": [ "room_type_id", "accommodation_id", "quantity" ], "title": "UpdateRoomConfigurationRequest" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "HotelNotFoundException": { "description": "El hotel solicitado no existe.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Descripci\u00f3n legible del error de negocio." } }, "required": [ "message" ] } } } }, "RoomConfigurationNotFoundException": { "description": "La configuraci\u00f3n de habitaci\u00f3n no existe o no pertenece al hotel indicado.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Descripci\u00f3n legible del error de negocio." } }, "required": [ "message" ] } } } } } } }