API de Visitas — Túnel Subfluvial Gestor de Visitas - Túnel Subfluvial

Los endpoints de Visitas son el núcleo del sistema de gestión de visitas al Túnel Subfluvial. Cubren desde el dashboard operativo diario hasta el historial completo, validación de capacidad y transiciones de estado. Todos los endpoints requieren un encabezado Authorization: Bearer <token> válido.

GET /api/visitas

Devuelve todas las visitas agendadas para un día específico. Es el endpoint usado por el dashboard operativo. Si no se proporciona fecha, el servidor usa la fecha actual. Forma de la respuesta: { fecha, total, data: [...visitas] }

fecha

string

Fecha objetivo en formato YYYY-MM-DD. Por defecto usa la fecha actual del servidor si se omite.

fecha

string

La fecha consultada, en formato YYYY-MM-DD.

total

number

Cantidad total de visitas encontradas para esa fecha.

data

array

Array de objetos de visita para el día solicitado.

curl -X GET "https://api.example.com/api/visitas?fecha=2025-08-15" \
  -H "Authorization: Bearer <token>"

Estado	Significado
`200`	Éxito — lista de visitas devuelta
`401`	Token ausente o inválido
`500`	Error interno del servidor

GET /api/visitas/rango

Devuelve todas las visitas que caen dentro de un rango de fechas. Los parámetros desde y hasta son obligatorios; omitir cualquiera devuelve un error 400. La respuesta es un array plano de objetos de visita.

desde

string

required

Inicio del rango en formato YYYY-MM-DD.

hasta

string

required

Fin del rango en formato YYYY-MM-DD (inclusive).

(array)

array

Array plano de objetos de visita dentro del rango solicitado.

curl -X GET "https://api.example.com/api/visitas/rango?desde=2025-08-01&hasta=2025-08-31" \
  -H "Authorization: Bearer <token>"

Estado	Significado
`200`	Éxito — array de visitas devuelto
`400`	Falta el parámetro `desde` o `hasta`
`401`	Token ausente o inválido
`500`	Error interno del servidor

GET /api/visitas/historial

Devuelve el historial completo de visitas en forma paginada. Destinado a la vista “Visitantes e Instituciones”. Los resultados están ordenados cronológicamente; usá page y pageSize para navegar por conjuntos de datos grandes.

page

number

Número de página a recuperar. Por defecto 1.

pageSize

number

Cantidad de registros por página. Por defecto 50.

data

array

Array de objetos de visita para la página solicitada.

total

number

Cantidad total de visitas en todas las páginas.

page

number

Número de página actual devuelto.

pageSize

number

Tamaño de página usado en esta respuesta.

curl -X GET "https://api.example.com/api/visitas/historial?page=2&pageSize=25" \
  -H "Authorization: Bearer <token>"

Estado	Significado
`200`	Éxito — historial paginado devuelto
`401`	Token ausente o inválido
`500`	Error interno del servidor

GET /api/visitas/calendario

Devuelve datos de ocupación por día para un mes completo, utilizado para renderizar la vista de calendario mensual. Por defecto usa el año y mes actuales si no se proporcionan parámetros. La respuesta es un objeto indexado por número de día (1–31).

anio

number

Año en cuatro dígitos (ej. 2025). Por defecto el año actual.

mes

number

Número de mes de 1 (enero) a 12 (diciembre). Por defecto el mes actual.

(object)

object

Objeto indexado por número de día. Cada clave es un entero del 1 al 31; cada valor contiene visitas (personas), grupos, estado ('parcial', 'lleno' o 'inhabilitado') y texto descriptivo.

curl -X GET "https://api.example.com/api/visitas/calendario?anio=2025&mes=8" \
  -H "Authorization: Bearer <token>"

Estado	Significado
`200`	Éxito — datos de ocupación mensual devueltos
`401`	Token ausente o inválido
`500`	Error interno del servidor

GET /api/visitas/:id

Devuelve el detalle completo de una visita, incluyendo datos del gestor, grupo e institución asociados. Devuelve 404 si no existe ninguna visita con el ID indicado.

string

required

El identificador único de la visita.

string

Identificador único de la visita.

fecha

string

Fecha de la visita en formato YYYY-MM-DD.

tipo

string

Tipo de visita: Salón de visitas o Salón + Sala de Comando.

estado

string

Estado actual de la visita: Agendada, Cancelada o Realizada.

gestor

object

Objeto gestor anidado con datos de contacto.

grupo

object

Detalles del grupo incluyendo nombre de institución y cantidad de visitantes.

curl -X GET "https://api.example.com/api/visitas/42" \
  -H "Authorization: Bearer <token>"

Estado	Significado
`200`	Éxito — detalle completo de la visita devuelto
`401`	Token ausente o inválido
`404`	No se encontró ninguna visita con ese ID

POST /api/visitas

Registra una nueva visita en el sistema. El servicio ejecuta todas las validaciones de negocio —días inhábiles, límite de aforo diario y solapamiento de horario— antes de confirmar la inserción en una transacción de base de datos. El cuerpo de la solicitud tiene tres secciones: visita (datos de la cita), grupo (información del grupo visitante) y gestor_id o nuevoGestor (coordinador de la visita). Sección visita:

visita.fecha

string

required

Fecha programada en formato YYYY-MM-DD.

visita.hora_inicio

string

required

Hora de inicio de la visita (ej. "09:00").

visita.tipo

string

required

Tipo de visita: Salón de visitas o Salón + Sala de Comando.

visita.cantidad_personas

number

required

Cantidad esperada de visitantes. Debe ser un número mayor a cero.

visita.tiene_cruce_tunel

boolean

Indica si la visita incluye cruce del túnel. Por defecto false.

visita.tiene_discapacidad

boolean

Indica si el grupo requiere accesibilidad. Por defecto false.

visita.discapacidad_detalle

string

Detalle de accesibilidad requerida. Obligatorio si tiene_discapacidad es true.

Sección grupo — para grupos tipo Institución:

grupo.tipo_visitante

string

required

Debe ser "Institución".

grupo.nivel_educativo

string

required

Nivel educativo del grupo. Valores permitidos: Infantes, Primario, Secundario, Terciario, Universitario, Adultos Mayores.

grupo.institucion_id

string

ID de una institución existente. Requerido si no se envía nuevaInstitucion.

grupo.nuevaInstitucion

object

Objeto con nombre (requerido) y campos opcionales telefono, email, localidad, provincia, pais para crear una institución nueva.

grupo.observaciones

string

Notas opcionales sobre el grupo.

Sección grupo — para grupos tipo Particulares:

grupo.tipo_visitante

string

required

Debe ser "Particulares".

grupo.tipo_grupo

string

required

Tipo de grupo: Menores, Adultos o Mixto.

grupo.nombre

string

required

Nombre del grupo.

grupo.telefono

string

required

Teléfono de contacto (ej. 0343-4000000).

grupo.email

string

required

Email de contacto.

grupo.localidad

string

required

Localidad del grupo.

grupo.provincia

string

required

Provincia del grupo.

grupo.pais

string

País del grupo. Por defecto "Argentina".

grupo.observaciones

string

Notas opcionales sobre el grupo.

Sección gestor:

gestor_id

string

ID de un gestor existente. Requerido si no se envía nuevoGestor.

nuevoGestor

object

Objeto con nombre (requerido) y campos opcionales empresa_institucion, telefono, email, localidad, provincia, pais para crear un gestor nuevo en la misma transacción.

mensaje

string

Mensaje de confirmación: "Visita registrada con éxito".

visita_id

string

El ID de la visita recién creada.

curl -X POST "https://api.example.com/api/visitas" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "gestor_id": "a1b2c3d4",
    "visita": {
      "fecha": "2025-09-10",
      "hora_inicio": "09:00",
      "tipo": "Salón de visitas",
      "cantidad_personas": 30
    },
    "grupo": {
      "tipo_visitante": "Institución",
      "nivel_educativo": "Secundario",
      "institucion_id": "e5f6g7h8"
    }
  }'

Estado	Significado
`201`	Visita creada — devuelve `{ mensaje, visita_id }`
`400`	Validación fallida: día inhábil, aforo superado, datos inválidos
`401`	Token ausente o inválido

PUT /api/visitas/:id

Edita los datos de una visita existente. Si se modifican fecha, hora_inicio o cantidad_personas, el servicio re-ejecuta todas las validaciones de capacidad y disponibilidad antes de persistir. Los valores de estado inválidos son rechazados a nivel de controller antes de llegar al servicio.

string

required

El identificador único de la visita a actualizar.

fecha

string

Nueva fecha de la visita en formato YYYY-MM-DD.

hora_inicio

string

Nueva hora de inicio (ej. "10:00").

tipo

string

Tipo de visita: Salón de visitas o Salón + Sala de Comando.

estado

string

Nuevo estado: debe ser Agendada, Cancelada o Realizada.

cantidad_personas

number

Cantidad de visitantes actualizada.

tiene_cruce_tunel

boolean

Indica si la visita incluye cruce del túnel.

tiene_discapacidad

boolean

Indica si el grupo requiere accesibilidad.

discapacidad_detalle

string

Detalle de accesibilidad actualizado.

observaciones

string

Notas actualizadas sobre el grupo.

gestor_id

string

ID del gestor de reemplazo.

nuevoGestor

object

Objeto con nombre y campos opcionales para crear un gestor nuevo durante la edición.

institucion_id

string

ID de la institución de reemplazo (solo visitas tipo Institución).

nuevaInstitucion

object

Objeto con nombre y campos opcionales para crear una institución nueva durante la edición.

mensaje

string

Mensaje de confirmación: "Visita modificada exitosamente".

visita

object

El objeto de visita completo y actualizado tal como fue persistido en la base de datos.

curl -X PUT "https://api.example.com/api/visitas/42" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "estado": "Realizada",
    "observaciones": "Visita completada sin inconvenientes"
  }'

Estado	Significado
`200`	Visita actualizada — devuelve `{ mensaje, visita }`
`400`	Valor de `estado` inválido, conflicto de capacidad u otro error de validación
`401`	Token ausente o inválido

PATCH /api/visitas/:id/cancelar

Cancela una visita y registra el motivo en el log de auditoría. El campo motivo describe el motivo de la cancelación. Devuelve 404 si la visita no existe y 409 si ya fue cancelada previamente.

string

required

El identificador único de la visita a cancelar.

motivo

string

El motivo de la cancelación, almacenado en el log de auditoría.

mensaje

string

Mensaje de confirmación: "Visita cancelada exitosamente".

visita

object

El objeto de visita actualizado con estado igual a Cancelada.

curl -X PATCH "https://api.example.com/api/visitas/42/cancelar" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "motivo": "El grupo no pudo asistir por condiciones climáticas" }'

Estado	Significado
`200`	Visita cancelada — devuelve `{ mensaje, visita }`
`401`	Token ausente o inválido
`404`	`"Visita no encontrada"` — no existe ninguna visita con ese ID
`409`	`"La visita ya se encuentra cancelada"` — la visita ya tiene estado `Cancelada`
`500`	Error inesperado del servidor

Visión General

Endpoints

API de Visitas — Túnel Subfluvial Gestor de Visitas

GET /api/visitas

GET /api/visitas/rango

GET /api/visitas/historial

GET /api/visitas/calendario

GET /api/visitas/:id

POST /api/visitas

PUT /api/visitas/:id

PATCH /api/visitas/:id/cancelar

Build docs developers (and LLMs) love

Visión General

Endpoints

Documentation Index

​GET /api/visitas

​GET /api/visitas/rango

​GET /api/visitas/historial

​GET /api/visitas/calendario

​GET /api/visitas/:id

​POST /api/visitas

​PUT /api/visitas/:id

​PATCH /api/visitas/:id/cancelar

Build docs developers (and LLMs) love

GET /api/visitas

GET /api/visitas/rango

GET /api/visitas/historial

GET /api/visitas/calendario

GET /api/visitas/:id

POST /api/visitas

PUT /api/visitas/:id

PATCH /api/visitas/:id/cancelar