API administrativa de Configuracion
La superficie administrativa vive bajo:
/api/external/v1/admin/configuration
Sus 74 operaciones se encuentran en estado preview. Los contratos ya definen scopes, tenant, campos permitidos, correlacion, idempotencia y concurrencia optimista; todavia no deben usarse en produccion hasta completar sus validaciones de disponibilidad.
Scopes
| Scope | Uso |
|---|---|
configuration:read | Listar y consultar catalogos. |
configuration:write | Crear, actualizar y eliminar catalogos. |
scheduling:read | Consultar programas, reglas, relaciones, festivos y bloqueos. |
scheduling:write | Modificar la configuracion de agenda. |
scheduling:generate | Materializar slots desde una regla. |
El token determina organizacion, empresa y actor. La API rechaza headers o campos que intenten sustituir ese contexto.
Catalogos
Cada recurso tiene listado, detalle, creacion, actualizacion y eliminacion protegida por version:
- Sedes.
- Profesionales.
- Especialidades.
- Tipos de cita.
- Tipos de consulta.
- Definiciones de oportunidad.
- Pagadores.
- Contratos.
- Fuentes de solicitud.
- Motivos de cancelacion.
- Motivos de inasistencia.
Los DTO son cerrados y no exponen metadata, identificadores de tenant ni campos internos de auditoria.
Configuracion de agenda
La referencia incluye programas, reglas recurrentes, asignacion de profesionales, tipos de cita por profesional, festivos, bloqueos y generacion de slots. Las fechas operativas usan America/Bogota.
Mutaciones seguras
Toda operacion POST, PUT, PATCH o DELETE requiere Idempotency-Key. Las operaciones sobre recursos existentes tambien requieren expectedVersion; una version obsoleta produce 409 sin aplicar cambios.
Cada familia de operaciones debe superar sus validaciones funcionales, de aislamiento multiempresa y de autenticacion antes de promoverse a estable.