{ "baseUrl": "https://citamedica.magnosoft.com.co/api/external/v1", "components": { "examples": { "Appointment": { "value": { "confirmationNumber": "0001", "endsAt": "2026-08-03T09:30:00-05:00", "id": "60000000-0000-4000-8000-000000000001", "patientId": "20000000-0000-4000-8000-000000000001", "serviceId": "30000000-0000-4000-8000-000000000003", "startsAt": "2026-08-03T09:00:00-05:00", "status": "PENDING", "version": 1 } }, "AppointmentCancelled": { "value": { "confirmationNumber": "0001", "endsAt": "2026-08-03T09:30:00-05:00", "id": "60000000-0000-4000-8000-000000000001", "patientId": "20000000-0000-4000-8000-000000000001", "serviceId": "30000000-0000-4000-8000-000000000003", "startsAt": "2026-08-03T09:00:00-05:00", "status": "CANCELLED", "version": 2 } }, "Patient": { "value": { "documentNumber": "900000001", "documentType": "CC", "email": "paciente@example.invalid", "fullName": "Paciente Ejemplo", "id": "20000000-0000-4000-8000-000000000001", "phone": "3000000000", "status": "ACTIVE", "updatedAt": "2026-07-27T15:00:00.000Z", "version": 1 } }, "PatientCreate": { "value": { "consentGrantedAt": "2026-07-26T14:00:00-05:00", "documentNumber": "900000001", "documentType": "CC", "email": "paciente@example.invalid", "fullName": "Paciente Ejemplo", "phone": "3000000000" } }, "PatientResolutionMatched": { "value": { "matched": true, "patient": { "documentNumber": "900000001", "documentType": "CC", "email": "paciente@example.invalid", "fullName": "Paciente Ejemplo", "id": "20000000-0000-4000-8000-000000000001", "phone": "3000000000", "status": "ACTIVE", "updatedAt": "2026-07-27T15:00:00.000Z", "version": 1 } } }, "Problem400": { "value": { "code": "INVALID_REQUEST", "correlationId": "10000000-0000-4000-8000-000000000001", "detail": "Revise los parametros enviados.", "status": 400, "title": "Solicitud invalida", "type": "https://magnosoft.com.co/problems/invalid-request" } }, "Problem401": { "value": { "code": "INVALID_ACCESS_TOKEN", "correlationId": "10000000-0000-4000-8000-000000000001", "status": 401, "title": "Autenticacion requerida", "type": "https://magnosoft.com.co/problems/unauthorized" } }, "Problem403": { "value": { "code": "INSUFFICIENT_SCOPE", "correlationId": "10000000-0000-4000-8000-000000000001", "status": 403, "title": "Permiso insuficiente", "type": "https://magnosoft.com.co/problems/forbidden" } }, "Problem404": { "value": { "code": "RESOURCE_NOT_FOUND", "correlationId": "10000000-0000-4000-8000-000000000001", "status": 404, "title": "Recurso no encontrado", "type": "https://magnosoft.com.co/problems/not-found" } }, "Problem409": { "value": { "code": "CONCURRENT_MODIFICATION", "correlationId": "10000000-0000-4000-8000-000000000001", "detail": "El recurso cambio; consulte su estado antes de reintentar.", "status": 409, "title": "Conflicto de estado", "type": "https://magnosoft.com.co/problems/conflict" } }, "Problem410": { "value": { "code": "OPTION_EXPIRED", "correlationId": "10000000-0000-4000-8000-000000000001", "status": 410, "title": "Opcion vencida", "type": "https://magnosoft.com.co/problems/option-expired" } }, "Problem422": { "value": { "code": "VALIDATION_FAILED", "correlationId": "10000000-0000-4000-8000-000000000001", "errors": [ { "code": "INVALID_DATE", "field": "serviceDate", "message": "Debe ser una fecha ISO 8601 valida." } ], "status": 422, "title": "Validacion fallida", "type": "https://magnosoft.com.co/problems/validation" } }, "Problem429": { "value": { "code": "RATE_LIMIT_EXCEEDED", "correlationId": "10000000-0000-4000-8000-000000000001", "status": 429, "title": "Demasiadas solicitudes", "type": "https://magnosoft.com.co/problems/rate-limit" } } }, "headers": { "CorrelationId": { "description": "Identificador de correlacion aceptado o generado por el servidor.", "name": "X-Correlation-Id", "required": true, "schema": { "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, "IdempotencyReplayed": { "description": "Indica si se devolvio el resultado confirmado de una solicitud anterior.", "name": "Idempotency-Replayed", "required": true, "schema": { "example": false, "type": "boolean" } }, "RetryAfter": { "description": "Segundos minimos antes de reintentar tras exceder el limite.", "name": "Retry-After", "required": true, "schema": { "example": 30, "minimum": 1, "type": "integer" } } }, "parameters": { "AppointmentId": { "description": "Identificador opaco de la cita dentro del tenant autenticado.", "in": "path", "name": "appointmentId", "required": true, "schema": { "default": "", "example": "60000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, "BlockId": { "description": "UUID del bloqueo dentro del alcance autenticado.", "in": "path", "name": "blockId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, "CatalogActive": { "description": "Filtra por estado administrable del recurso.", "in": "query", "name": "active", "required": false, "schema": { "default": "", "type": "boolean" } }, "CatalogId": { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, "CatalogSearch": { "description": "Busqueda textual allowlisted sobre codigo y nombre.", "in": "query", "name": "search", "required": false, "schema": { "default": "", "maxLength": 100, "minLength": 1, "type": "string" } }, "CatalogSort": { "description": "Orden estable permitido para catalogos.", "in": "query", "name": "sort", "required": false, "schema": { "default": "code", "enum": [ "code", "name", "-code", "-name" ], "type": "string" } }, "CorrelationId": { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, "Cursor": { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, "ExpectedVersion": { "description": "Version observada antes de eliminar el recurso existente.", "in": "query", "name": "expectedVersion", "required": true, "schema": { "$ref": "#/components/schemas/ExpectedVersion" } }, "HolidayId": { "description": "UUID del festivo dentro del alcance autenticado.", "in": "path", "name": "holidayId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, "IdempotencyKey": { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } }, "Limit": { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, "PatientId": { "description": "Identificador opaco del paciente dentro del tenant autenticado.", "in": "path", "name": "patientId", "required": true, "schema": { "default": "", "example": "20000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, "PatientIdQuery": { "description": "Identificador opaco del paciente dentro del tenant autenticado.", "in": "query", "name": "patientId", "required": true, "schema": { "default": "", "example": "20000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, "PractitionerId": { "description": "UUID del profesional dentro del alcance autenticado.", "in": "path", "name": "practitionerId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, "ProgramId": { "description": "UUID del programa dentro del alcance autenticado.", "in": "path", "name": "programId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, "RuleId": { "description": "UUID de la regla dentro del alcance autenticado.", "in": "path", "name": "ruleId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } }, "responses": { "BadGateway": { "$ref": "#/components/responses/Problem502" }, "BadRequest": { "$ref": "#/components/responses/Problem400" }, "Conflict": { "$ref": "#/components/responses/Problem409" }, "Forbidden": { "$ref": "#/components/responses/Problem403" }, "Gone": { "$ref": "#/components/responses/Problem410" }, "InternalServerError": { "$ref": "#/components/responses/Problem500" }, "NotFound": { "$ref": "#/components/responses/Problem404" }, "Problem400": { "content": { "application/problem+json": { "examples": { "invalidRequest": { "$ref": "#/components/examples/Problem400" } }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Solicitud mal formada o parametro invalido.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "Problem401": { "content": { "application/problem+json": { "examples": { "unauthorized": { "$ref": "#/components/examples/Problem401" } }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Token ausente, invalido, vencido o con audience incorrecta.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "Problem403": { "content": { "application/problem+json": { "examples": { "forbidden": { "$ref": "#/components/examples/Problem403" } }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Service principal autenticado sin el scope requerido.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "Problem404": { "content": { "application/problem+json": { "examples": { "notFound": { "$ref": "#/components/examples/Problem404" } }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Recurso inexistente o no visible dentro del tenant autenticado.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "Problem409": { "content": { "application/problem+json": { "examples": { "conflict": { "$ref": "#/components/examples/Problem409" } }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Conflicto de concurrencia, capacidad o reutilizacion de idempotencia.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "Problem410": { "content": { "application/problem+json": { "examples": { "gone": { "$ref": "#/components/examples/Problem410" } }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Option token vencido o recurso temporal que ya no puede consumirse.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "Problem422": { "content": { "application/problem+json": { "examples": { "invalidField": { "$ref": "#/components/examples/Problem422" } }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "JSON valido que incumple una regla de validacion del contrato.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "Problem429": { "content": { "application/problem+json": { "examples": { "rateLimit": { "$ref": "#/components/examples/Problem429" } }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Limite de solicitudes excedido para el service principal.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "Problem500": { "content": { "application/problem+json": { "examples": { "internal": { "value": { "code": "INTERNAL_ERROR", "correlationId": "10000000-0000-4000-8000-000000000001", "status": 500, "title": "Error interno", "type": "https://magnosoft.com.co/problems/internal-error" } } }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Falla interna segura sin detalles de implementacion.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "Problem502": { "content": { "application/problem+json": { "examples": { "upstream": { "value": { "code": "UPSTREAM_FAILURE", "correlationId": "10000000-0000-4000-8000-000000000001", "detail": "Downstream service unavailable", "status": 502, "title": "UPSTREAM FAILURE", "type": "https://magnosoft.com.co/problems/upstream-failure" } } }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Falla segura al comunicarse con el servicio interno autoritativo.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "TooManyRequests": { "$ref": "#/components/responses/Problem429" }, "Unauthorized": { "$ref": "#/components/responses/Problem401" }, "UnprocessableEntity": { "$ref": "#/components/responses/Problem422" } }, "schemas": { "Appointment": { "additionalProperties": false, "properties": { "confirmationNumber": { "example": "0001", "pattern": "^[0-9]{4,}$", "type": "string" }, "endsAt": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "patientId": { "format": "uuid", "type": "string" }, "serviceId": { "format": "uuid", "type": "string" }, "startsAt": { "format": "date-time", "type": "string" }, "status": { "$ref": "#/components/schemas/AppointmentStatus" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "id", "confirmationNumber", "patientId", "serviceId", "startsAt", "endsAt", "status", "version" ], "type": "object" }, "AppointmentCancel": { "additionalProperties": false, "properties": { "comment": { "maxLength": 500, "minLength": 1, "type": "string" }, "expectedVersion": { "minimum": 1, "type": "integer" }, "reasonId": { "format": "uuid", "type": "string" } }, "required": [ "reasonId", "expectedVersion" ], "type": "object" }, "AppointmentCreate": { "additionalProperties": false, "properties": { "eligibilityDecisionId": { "format": "uuid", "type": "string" }, "optionToken": { "maxLength": 2048, "minLength": 20, "type": "string" }, "patientId": { "format": "uuid", "type": "string" }, "serviceId": { "format": "uuid", "type": "string" }, "visitType": { "enum": [ "FIRST_TIME", "CONTROL" ], "type": "string" } }, "required": [ "patientId", "serviceId", "optionToken", "visitType" ], "type": "object" }, "AppointmentEvent": { "additionalProperties": false, "properties": { "appointmentId": { "format": "uuid", "type": "string" }, "correlationId": { "maxLength": 200, "minLength": 1, "type": "string" }, "id": { "format": "uuid", "type": "string" }, "newStatus": { "$ref": "#/components/schemas/AppointmentStatus" }, "occurredAt": { "format": "date-time", "type": "string" }, "previousStatus": { "type": [ "string", "null" ] }, "source": { "maxLength": 50, "minLength": 1, "type": "string" }, "type": { "pattern": "^[A-Z][A-Z0-9_]+$", "type": "string" } }, "required": [ "id", "appointmentId", "type", "occurredAt", "previousStatus", "newStatus", "correlationId", "source" ], "type": "object" }, "AppointmentEventPage": { "additionalProperties": false, "properties": { "hasMore": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/AppointmentEvent" }, "maxItems": 100, "type": "array" }, "nextCursor": { "$ref": "#/components/schemas/PageCursor" } }, "required": [ "items", "nextCursor", "hasMore" ], "type": "object" }, "AppointmentPage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/Appointment" }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ], "type": "object" }, "AppointmentReschedule": { "additionalProperties": false, "properties": { "expectedVersion": { "minimum": 1, "type": "integer" }, "optionToken": { "maxLength": 2048, "minLength": 20, "type": "string" } }, "required": [ "optionToken", "expectedVersion" ], "type": "object" }, "AppointmentStatus": { "enum": [ "PENDING", "CONFIRMED", "CHECKED_IN", "ATTENDED", "CANCELLED", "NO_SHOW" ], "type": "string" }, "AppointmentTypeCreate": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "durationMinutes": { "maximum": 480, "minimum": 5, "type": "integer" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "opportunityDefinitionId": { "$ref": "#/components/schemas/Uuid" } }, "required": [ "code", "name", "durationMinutes", "opportunityDefinitionId", "active" ], "type": "object" }, "AppointmentTypeDetail": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "durationMinutes": { "maximum": 480, "minimum": 5, "type": "integer" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "opportunityDefinitionId": { "$ref": "#/components/schemas/Uuid" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "durationMinutes", "opportunityDefinitionId", "active", "version" ], "type": "object" }, "AppointmentTypePage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/AppointmentTypeSummary" }, "maxItems": 100, "type": "array" }, "nextCursor": { "$ref": "#/components/schemas/PageCursor" } }, "required": [ "items", "nextCursor" ], "type": "object" }, "AppointmentTypeSummary": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "durationMinutes": { "maximum": 480, "minimum": 5, "type": "integer" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "opportunityDefinitionId": { "$ref": "#/components/schemas/Uuid" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "durationMinutes", "opportunityDefinitionId", "active", "version" ], "type": "object" }, "AppointmentTypeUpdate": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "durationMinutes": { "maximum": 480, "minimum": 5, "type": "integer" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "opportunityDefinitionId": { "$ref": "#/components/schemas/Uuid" } }, "required": [ "expectedVersion" ], "type": "object" }, "AsyncResource": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "status": { "enum": [ "ACTIVE", "RECEIVED", "OPEN" ], "type": "string" } }, "required": [ "id", "status", "createdAt" ], "type": "object" }, "AvailabilityOption": { "additionalProperties": false, "properties": { "endsAt": { "format": "date-time", "type": "string" }, "expiresAt": { "format": "date-time", "type": "string" }, "locationId": { "format": "uuid", "type": "string" }, "optionToken": { "description": "Token opaco, temporal y ligado al tenant.", "maxLength": 2048, "minLength": 20, "type": "string" }, "practitionerId": { "format": "uuid", "type": "string" }, "startsAt": { "format": "date-time", "type": "string" } }, "required": [ "optionToken", "startsAt", "endsAt", "locationId", "practitionerId", "expiresAt" ], "type": "object" }, "AvailabilityPage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/AvailabilityOption" }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ], "type": "object" }, "CancellationReasonCreate": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "requiresComment": { "type": "boolean" } }, "required": [ "code", "name", "requiresComment", "active" ], "type": "object" }, "CancellationReasonDetail": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "requiresComment": { "type": "boolean" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "requiresComment", "active", "version" ], "type": "object" }, "CancellationReasonPage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/CancellationReasonSummary" }, "maxItems": 100, "type": "array" }, "nextCursor": { "$ref": "#/components/schemas/PageCursor" } }, "required": [ "items", "nextCursor" ], "type": "object" }, "CancellationReasonSummary": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "requiresComment": { "type": "boolean" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "requiresComment", "active", "version" ], "type": "object" }, "CancellationReasonUpdate": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "requiresComment": { "type": "boolean" } }, "required": [ "expectedVersion" ], "type": "object" }, "ConsultationTypeCreate": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "description": { "maxLength": 500, "type": "string" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "code", "name", "active" ], "type": "object" }, "ConsultationTypeDetail": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "description": { "maxLength": 500, "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "active", "version" ], "type": "object" }, "ConsultationTypePage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/ConsultationTypeSummary" }, "maxItems": 100, "type": "array" }, "nextCursor": { "$ref": "#/components/schemas/PageCursor" } }, "required": [ "items", "nextCursor" ], "type": "object" }, "ConsultationTypeSummary": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "description": { "maxLength": 500, "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "active", "version" ], "type": "object" }, "ConsultationTypeUpdate": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "description": { "maxLength": 500, "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "expectedVersion" ], "type": "object" }, "ContractCreate": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "payerId": { "$ref": "#/components/schemas/Uuid" }, "validFrom": { "format": "date", "type": "string" }, "validTo": { "format": "date", "type": "string" } }, "required": [ "code", "name", "payerId", "validFrom", "validTo", "active" ], "type": "object" }, "ContractDetail": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "payerId": { "$ref": "#/components/schemas/Uuid" }, "updatedAt": { "format": "date-time", "type": "string" }, "validFrom": { "format": "date", "type": "string" }, "validTo": { "format": "date", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "payerId", "validFrom", "validTo", "active", "version" ], "type": "object" }, "ContractPage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/ContractSummary" }, "maxItems": 100, "type": "array" }, "nextCursor": { "$ref": "#/components/schemas/PageCursor" } }, "required": [ "items", "nextCursor" ], "type": "object" }, "ContractSummary": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "payerId": { "$ref": "#/components/schemas/Uuid" }, "updatedAt": { "format": "date-time", "type": "string" }, "validFrom": { "format": "date", "type": "string" }, "validTo": { "format": "date", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "payerId", "validFrom", "validTo", "active", "version" ], "type": "object" }, "ContractUpdate": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "payerId": { "$ref": "#/components/schemas/Uuid" }, "validFrom": { "format": "date", "type": "string" }, "validTo": { "format": "date", "type": "string" } }, "required": [ "expectedVersion" ], "type": "object" }, "ContractedService": { "additionalProperties": false, "properties": { "appointmentTypeId": { "format": "uuid", "type": "string" }, "code": { "maxLength": 50, "minLength": 1, "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "maxLength": 160, "minLength": 1, "type": "string" }, "requiresPreauthorization": { "type": "boolean" } }, "required": [ "id", "code", "name", "appointmentTypeId", "requiresPreauthorization" ], "type": "object" }, "ContractedServicePage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/ContractedService" }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ], "type": "object" }, "DecisionReason": { "additionalProperties": false, "properties": { "code": { "pattern": "^[A-Z][A-Z0-9_]+$", "type": "string" }, "message": { "maxLength": 240, "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "DeletionResult": { "additionalProperties": false, "properties": { "deleted": { "const": true, "type": "boolean" }, "id": { "$ref": "#/components/schemas/Uuid" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "deleted", "version" ], "type": "object" }, "EligibilityRequest": { "additionalProperties": false, "properties": { "contractId": { "format": "uuid", "type": "string" }, "patientId": { "format": "uuid", "type": "string" }, "payerId": { "format": "uuid", "type": "string" }, "serviceDate": { "format": "date", "type": "string" }, "serviceId": { "format": "uuid", "type": "string" } }, "required": [ "patientId", "payerId", "contractId", "serviceId", "serviceDate" ], "type": "object" }, "EligibilityResult": { "additionalProperties": false, "properties": { "decisionId": { "format": "uuid", "type": "string" }, "eligible": { "type": "boolean" }, "evaluatedAt": { "format": "date-time", "type": "string" }, "reasons": { "items": { "$ref": "#/components/schemas/DecisionReason" }, "maxItems": 20, "type": "array" }, "validUntil": { "format": "date-time", "type": "string" } }, "required": [ "eligible", "decisionId", "evaluatedAt", "validUntil", "reasons" ], "type": "object" }, "ExpectedVersion": { "example": 1, "minimum": 1, "type": "integer" }, "FieldError": { "additionalProperties": false, "properties": { "code": { "pattern": "^[A-Z][A-Z0-9_]+$", "type": "string" }, "field": { "maxLength": 120, "type": "string" }, "message": { "maxLength": 240, "type": "string" } }, "required": [ "field", "code", "message" ], "type": "object" }, "LocationCreate": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "address": { "maxLength": 240, "minLength": 3, "type": "string" }, "cityCode": { "maxLength": 5, "minLength": 5, "pattern": "^[0-9]{5}", "type": "string" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "departmentCode": { "maxLength": 2, "minLength": 2, "pattern": "^[0-9]{2}", "type": "string" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "code", "name", "address", "cityCode", "departmentCode", "active" ], "type": "object" }, "LocationDetail": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "address": { "maxLength": 240, "minLength": 3, "type": "string" }, "cityCode": { "maxLength": 5, "minLength": 5, "pattern": "^[0-9]{5}", "type": "string" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "departmentCode": { "maxLength": 2, "minLength": 2, "pattern": "^[0-9]{2}", "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "address", "cityCode", "departmentCode", "active", "version" ], "type": "object" }, "LocationPage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/LocationSummary" }, "maxItems": 100, "type": "array" }, "nextCursor": { "$ref": "#/components/schemas/PageCursor" } }, "required": [ "items", "nextCursor" ], "type": "object" }, "LocationSummary": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "address": { "maxLength": 240, "minLength": 3, "type": "string" }, "cityCode": { "maxLength": 5, "minLength": 5, "pattern": "^[0-9]{5}", "type": "string" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "departmentCode": { "maxLength": 2, "minLength": 2, "pattern": "^[0-9]{2}", "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "address", "cityCode", "departmentCode", "active", "version" ], "type": "object" }, "LocationUpdate": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "type": "boolean" }, "address": { "maxLength": 240, "minLength": 3, "type": "string" }, "cityCode": { "maxLength": 5, "minLength": 5, "pattern": "^[0-9]{5}", "type": "string" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "departmentCode": { "maxLength": 2, "minLength": 2, "pattern": "^[0-9]{2}", "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "expectedVersion" ], "type": "object" }, "NoShowReasonCreate": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "requiresComment": { "type": "boolean" } }, "required": [ "code", "name", "requiresComment", "active" ], "type": "object" }, "NoShowReasonDetail": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "requiresComment": { "type": "boolean" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "requiresComment", "active", "version" ], "type": "object" }, "NoShowReasonPage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/NoShowReasonSummary" }, "maxItems": 100, "type": "array" }, "nextCursor": { "$ref": "#/components/schemas/PageCursor" } }, "required": [ "items", "nextCursor" ], "type": "object" }, "NoShowReasonSummary": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "requiresComment": { "type": "boolean" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "requiresComment", "active", "version" ], "type": "object" }, "NoShowReasonUpdate": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "requiresComment": { "type": "boolean" } }, "required": [ "expectedVersion" ], "type": "object" }, "OpportunityDefinitionCreate": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "description": { "maxLength": 500, "type": "string" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "protected": { "readOnly": true, "type": "boolean" } }, "required": [ "code", "name", "active" ], "type": "object" }, "OpportunityDefinitionDetail": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "description": { "maxLength": 500, "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "protected": { "readOnly": true, "type": "boolean" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "active", "version" ], "type": "object" }, "OpportunityDefinitionPage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/OpportunityDefinitionSummary" }, "maxItems": 100, "type": "array" }, "nextCursor": { "$ref": "#/components/schemas/PageCursor" } }, "required": [ "items", "nextCursor" ], "type": "object" }, "OpportunityDefinitionSummary": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "description": { "maxLength": 500, "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "protected": { "readOnly": true, "type": "boolean" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "active", "version" ], "type": "object" }, "OpportunityDefinitionUpdate": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "description": { "maxLength": 500, "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "protected": { "readOnly": true, "type": "boolean" } }, "required": [ "expectedVersion" ], "type": "object" }, "PageCursor": { "example": null, "maxLength": 512, "type": [ "string", "null" ] }, "Pagination": { "additionalProperties": false, "properties": { "nextCursor": { "$ref": "#/components/schemas/PageCursor" } }, "required": [ "nextCursor" ], "type": "object" }, "Patient": { "additionalProperties": false, "properties": { "documentNumber": { "description": "Se retorna solo a clientes expresamente autorizados por scope.", "type": "string" }, "documentType": { "type": "string" }, "email": { "format": "email", "type": "string" }, "fullName": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "phone": { "type": "string" }, "status": { "enum": [ "ACTIVE", "INACTIVE", "DECEASED" ], "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "id", "documentType", "documentNumber", "fullName", "phone", "status", "version", "updatedAt" ], "type": "object" }, "PatientCreate": { "additionalProperties": false, "properties": { "consentGrantedAt": { "format": "date-time", "type": "string" }, "documentNumber": { "maxLength": 40, "minLength": 3, "type": "string" }, "documentType": { "maxLength": 20, "minLength": 1, "type": "string" }, "email": { "format": "email", "maxLength": 254, "type": "string" }, "fullName": { "maxLength": 160, "minLength": 3, "type": "string" }, "phone": { "maxLength": 30, "minLength": 7, "type": "string" } }, "required": [ "documentType", "documentNumber", "fullName", "phone", "consentGrantedAt" ], "type": "object" }, "PatientResolution": { "additionalProperties": false, "properties": { "matched": { "type": "boolean" }, "patient": { "oneOf": [ { "$ref": "#/components/schemas/Patient" }, { "type": "null" } ] } }, "required": [ "matched" ], "type": "object" }, "PatientUpdate": { "additionalProperties": false, "properties": { "email": { "format": "email", "maxLength": 254, "type": "string" }, "expectedVersion": { "minimum": 1, "type": "integer" }, "fullName": { "maxLength": 160, "minLength": 3, "type": "string" }, "phone": { "maxLength": 30, "minLength": 7, "type": "string" } }, "required": [ "fullName", "phone", "expectedVersion" ], "type": "object" }, "PayerCreate": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "taxId": { "maxLength": 30, "minLength": 5, "type": "string" } }, "required": [ "code", "name", "taxId", "active" ], "type": "object" }, "PayerDetail": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "taxId": { "maxLength": 30, "minLength": 5, "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "taxId", "active", "version" ], "type": "object" }, "PayerPage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/PayerSummary" }, "maxItems": 100, "type": "array" }, "nextCursor": { "$ref": "#/components/schemas/PageCursor" } }, "required": [ "items", "nextCursor" ], "type": "object" }, "PayerSummary": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "taxId": { "maxLength": 30, "minLength": 5, "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "taxId", "active", "version" ], "type": "object" }, "PayerUpdate": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "taxId": { "maxLength": 30, "minLength": 5, "type": "string" } }, "required": [ "expectedVersion" ], "type": "object" }, "PractitionerAppointmentTypeConfiguration": { "additionalProperties": false, "properties": { "appointmentTypeIds": { "items": { "$ref": "#/components/schemas/Uuid" }, "type": "array", "uniqueItems": true }, "practitionerId": { "$ref": "#/components/schemas/Uuid" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "practitionerId", "appointmentTypeIds", "version" ], "type": "object" }, "PractitionerAppointmentTypeReplacement": { "additionalProperties": false, "properties": { "appointmentTypeIds": { "items": { "$ref": "#/components/schemas/Uuid" }, "type": "array", "uniqueItems": true }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" } }, "required": [ "appointmentTypeIds", "expectedVersion" ], "type": "object" }, "PractitionerCreate": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "email": { "format": "email", "maxLength": 254, "type": "string" }, "fullName": { "maxLength": 160, "minLength": 3, "type": "string" }, "locationIds": { "items": { "$ref": "#/components/schemas/Uuid" }, "minItems": 1, "type": "array", "uniqueItems": true }, "phone": { "maxLength": 30, "minLength": 7, "type": "string" }, "specialtyIds": { "items": { "$ref": "#/components/schemas/Uuid" }, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "code", "fullName", "email", "locationIds", "specialtyIds", "active" ], "type": "object" }, "PractitionerDetail": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "email": { "format": "email", "maxLength": 254, "type": "string" }, "fullName": { "maxLength": 160, "minLength": 3, "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "locationIds": { "items": { "$ref": "#/components/schemas/Uuid" }, "minItems": 1, "type": "array", "uniqueItems": true }, "phone": { "maxLength": 30, "minLength": 7, "type": "string" }, "specialtyIds": { "items": { "$ref": "#/components/schemas/Uuid" }, "minItems": 1, "type": "array", "uniqueItems": true }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "fullName", "email", "locationIds", "specialtyIds", "active", "version" ], "type": "object" }, "PractitionerPage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/PractitionerSummary" }, "maxItems": 100, "type": "array" }, "nextCursor": { "$ref": "#/components/schemas/PageCursor" } }, "required": [ "items", "nextCursor" ], "type": "object" }, "PractitionerSummary": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "email": { "format": "email", "maxLength": 254, "type": "string" }, "fullName": { "maxLength": 160, "minLength": 3, "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "locationIds": { "items": { "$ref": "#/components/schemas/Uuid" }, "minItems": 1, "type": "array", "uniqueItems": true }, "phone": { "maxLength": 30, "minLength": 7, "type": "string" }, "specialtyIds": { "items": { "$ref": "#/components/schemas/Uuid" }, "minItems": 1, "type": "array", "uniqueItems": true }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "fullName", "email", "locationIds", "specialtyIds", "active", "version" ], "type": "object" }, "PractitionerUpdate": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "email": { "format": "email", "maxLength": 254, "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "fullName": { "maxLength": 160, "minLength": 3, "type": "string" }, "locationIds": { "items": { "$ref": "#/components/schemas/Uuid" }, "minItems": 1, "type": "array", "uniqueItems": true }, "phone": { "maxLength": 30, "minLength": 7, "type": "string" }, "specialtyIds": { "items": { "$ref": "#/components/schemas/Uuid" }, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "expectedVersion" ], "type": "object" }, "PreauthorizationCreate": { "additionalProperties": false, "properties": { "contractId": { "format": "uuid", "type": "string" }, "externalReference": { "maxLength": 100, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" }, "patientId": { "format": "uuid", "type": "string" }, "payerId": { "format": "uuid", "type": "string" }, "serviceId": { "format": "uuid", "type": "string" } }, "required": [ "patientId", "payerId", "contractId", "serviceId", "externalReference" ], "type": "object" }, "Problem": { "additionalProperties": false, "properties": { "code": { "pattern": "^[A-Z][A-Z0-9_]+$", "type": "string" }, "correlationId": { "format": "uuid", "type": "string" }, "detail": { "description": "Explicacion segura sin PII ni secretos.", "maxLength": 500, "type": "string" }, "errors": { "items": { "$ref": "#/components/schemas/FieldError" }, "maxItems": 50, "type": "array" }, "instance": { "format": "uri-reference", "type": "string" }, "status": { "maximum": 599, "minimum": 400, "type": "integer" }, "title": { "maxLength": 160, "minLength": 1, "type": "string" }, "type": { "description": "URI estable que identifica la clase de problema.", "format": "uri", "type": "string" } }, "required": [ "type", "title", "status", "code", "correlationId" ], "type": "object" }, "ProgramPractitionerAssignment": { "additionalProperties": false, "properties": { "practitionerIds": { "items": { "$ref": "#/components/schemas/Uuid" }, "type": "array", "uniqueItems": true }, "programId": { "$ref": "#/components/schemas/Uuid" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "programId", "practitionerIds", "version" ], "type": "object" }, "ProgramPractitionerReplacement": { "additionalProperties": false, "properties": { "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "practitionerIds": { "items": { "$ref": "#/components/schemas/Uuid" }, "type": "array", "uniqueItems": true } }, "required": [ "practitionerIds", "expectedVersion" ], "type": "object" }, "RequestSourceCreate": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "channel": { "enum": [ "PHONE", "WEB", "IN_PERSON", "PARTNER" ], "type": "string" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "code", "name", "channel", "active" ], "type": "object" }, "RequestSourceDetail": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "channel": { "enum": [ "PHONE", "WEB", "IN_PERSON", "PARTNER" ], "type": "string" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "channel", "active", "version" ], "type": "object" }, "RequestSourcePage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/RequestSourceSummary" }, "maxItems": 100, "type": "array" }, "nextCursor": { "$ref": "#/components/schemas/PageCursor" } }, "required": [ "items", "nextCursor" ], "type": "object" }, "RequestSourceSummary": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "channel": { "enum": [ "PHONE", "WEB", "IN_PERSON", "PARTNER" ], "type": "string" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "channel", "active", "version" ], "type": "object" }, "RequestSourceUpdate": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "type": "boolean" }, "channel": { "enum": [ "PHONE", "WEB", "IN_PERSON", "PARTNER" ], "type": "string" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "expectedVersion" ], "type": "object" }, "SahPractitioner": { "additionalProperties": false, "properties": { "code": { "maxLength": 50, "minLength": 1, "type": "string" }, "fullName": { "maxLength": 160, "minLength": 3, "type": "string" }, "id": { "format": "uuid", "type": "string" }, "locationIds": { "items": { "format": "uuid", "type": "string" }, "type": "array", "uniqueItems": true }, "serviceIds": { "items": { "format": "uuid", "type": "string" }, "type": "array", "uniqueItems": true }, "specialtyIds": { "items": { "format": "uuid", "type": "string" }, "type": "array", "uniqueItems": true } }, "required": [ "id", "code", "fullName", "locationIds", "specialtyIds", "serviceIds" ], "type": "object" }, "SahPractitionerPage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/SahPractitioner" }, "maxItems": 100, "type": "array" }, "nextCursor": { "$ref": "#/components/schemas/PageCursor" } }, "required": [ "items", "nextCursor" ], "type": "object" }, "SchedulingBlockCreate": { "additionalProperties": false, "anyOf": [ { "required": [ "programId" ] }, { "required": [ "practitionerId" ] } ], "properties": { "active": { "type": "boolean" }, "endsAt": { "format": "date-time", "type": "string" }, "locationId": { "$ref": "#/components/schemas/Uuid" }, "practitionerId": { "$ref": "#/components/schemas/Uuid" }, "programId": { "$ref": "#/components/schemas/Uuid" }, "reason": { "maxLength": 500, "minLength": 3, "type": "string" }, "startsAt": { "format": "date-time", "type": "string" } }, "required": [ "locationId", "startsAt", "endsAt", "reason", "active" ], "type": "object" }, "SchedulingBlockDetail": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "endsAt": { "format": "date-time", "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "locationId": { "$ref": "#/components/schemas/Uuid" }, "practitionerId": { "$ref": "#/components/schemas/Uuid" }, "programId": { "$ref": "#/components/schemas/Uuid" }, "reason": { "type": "string" }, "startsAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "locationId", "startsAt", "endsAt", "reason", "active", "version" ], "type": "object" }, "SchedulingBlockPage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/SchedulingBlockDetail" }, "maxItems": 100, "type": "array" }, "nextCursor": { "$ref": "#/components/schemas/PageCursor" } }, "required": [ "items", "nextCursor" ], "type": "object" }, "SchedulingBlockUpdate": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "type": "boolean" }, "endsAt": { "format": "date-time", "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "locationId": { "$ref": "#/components/schemas/Uuid" }, "practitionerId": { "$ref": "#/components/schemas/Uuid" }, "programId": { "$ref": "#/components/schemas/Uuid" }, "reason": { "maxLength": 500, "minLength": 3, "type": "string" }, "startsAt": { "format": "date-time", "type": "string" } }, "required": [ "expectedVersion" ], "type": "object" }, "SchedulingHolidayCreate": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "date": { "format": "date", "type": "string" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "date", "name", "active" ], "type": "object" }, "SchedulingHolidayDetail": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "date": { "format": "date", "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "date", "name", "active", "version" ], "type": "object" }, "SchedulingHolidayPage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/SchedulingHolidayDetail" }, "maxItems": 100, "type": "array" }, "nextCursor": { "$ref": "#/components/schemas/PageCursor" } }, "required": [ "items", "nextCursor" ], "type": "object" }, "SchedulingHolidayUpdate": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "type": "boolean" }, "date": { "format": "date", "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "expectedVersion" ], "type": "object" }, "SchedulingProgramCreate": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "emergency": { "type": "boolean" }, "locationId": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "code", "name", "locationId", "emergency", "active" ], "type": "object" }, "SchedulingProgramDetail": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "type": "string" }, "emergency": { "type": "boolean" }, "id": { "$ref": "#/components/schemas/Uuid" }, "locationId": { "$ref": "#/components/schemas/Uuid" }, "name": { "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "locationId", "emergency", "active", "version" ], "type": "object" }, "SchedulingProgramPage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/SchedulingProgramDetail" }, "maxItems": 100, "type": "array" }, "nextCursor": { "$ref": "#/components/schemas/PageCursor" } }, "required": [ "items", "nextCursor" ], "type": "object" }, "SchedulingProgramUpdate": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "emergency": { "type": "boolean" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "locationId": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "expectedVersion" ], "type": "object" }, "SchedulingRuleCreate": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "dailyCapacity": { "maximum": 1000, "minimum": 1, "type": "integer" }, "endsAtLocal": { "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$", "type": "string" }, "holidayDates": { "items": { "format": "date", "type": "string" }, "type": "array", "uniqueItems": true }, "holidayPolicy": { "enum": [ "SKIP", "INCLUDE", "ONLY_EXCEPTIONS" ], "type": "string" }, "recurrence": { "enum": [ "WEEKLY" ], "type": "string" }, "slotDurationMinutes": { "maximum": 480, "minimum": 5, "type": "integer" }, "startsAtLocal": { "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$", "type": "string" }, "validFrom": { "format": "date", "type": "string" }, "validTo": { "format": "date", "type": "string" }, "weekdays": { "items": { "maximum": 7, "minimum": 1, "type": "integer" }, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "validFrom", "validTo", "startsAtLocal", "endsAtLocal", "slotDurationMinutes", "dailyCapacity", "weekdays", "recurrence", "holidayPolicy", "active" ], "type": "object" }, "SchedulingRuleDetail": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "dailyCapacity": { "type": "integer" }, "endsAtLocal": { "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$", "type": "string" }, "holidayDates": { "items": { "format": "date", "type": "string" }, "type": "array", "uniqueItems": true }, "holidayPolicy": { "enum": [ "SKIP", "INCLUDE", "ONLY_EXCEPTIONS" ], "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "programId": { "$ref": "#/components/schemas/Uuid" }, "recurrence": { "enum": [ "WEEKLY" ], "type": "string" }, "slotDurationMinutes": { "type": "integer" }, "startsAtLocal": { "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$", "type": "string" }, "validFrom": { "format": "date", "type": "string" }, "validTo": { "format": "date", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" }, "weekdays": { "items": { "type": "integer" }, "type": "array", "uniqueItems": true } }, "required": [ "id", "programId", "validFrom", "validTo", "startsAtLocal", "endsAtLocal", "slotDurationMinutes", "dailyCapacity", "weekdays", "recurrence", "holidayPolicy", "holidayDates", "active", "version" ], "type": "object" }, "SchedulingRulePage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/SchedulingRuleDetail" }, "maxItems": 100, "type": "array" }, "nextCursor": { "$ref": "#/components/schemas/PageCursor" } }, "required": [ "items", "nextCursor" ], "type": "object" }, "SchedulingRuleUpdate": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "type": "boolean" }, "dailyCapacity": { "maximum": 1000, "minimum": 1, "type": "integer" }, "endsAtLocal": { "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$", "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "holidayDates": { "items": { "format": "date", "type": "string" }, "type": "array", "uniqueItems": true }, "holidayPolicy": { "enum": [ "SKIP", "INCLUDE", "ONLY_EXCEPTIONS" ], "type": "string" }, "recurrence": { "enum": [ "WEEKLY" ], "type": "string" }, "slotDurationMinutes": { "maximum": 480, "minimum": 5, "type": "integer" }, "startsAtLocal": { "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$", "type": "string" }, "validFrom": { "format": "date", "type": "string" }, "validTo": { "format": "date", "type": "string" }, "weekdays": { "items": { "maximum": 7, "minimum": 1, "type": "integer" }, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "expectedVersion" ], "type": "object" }, "SiauCaseCreate": { "additionalProperties": false, "properties": { "appointmentId": { "format": "uuid", "type": "string" }, "category": { "enum": [ "INFORMATION_REQUEST", "COMPLAINT", "CLAIM", "SUGGESTION", "COMPLIMENT" ], "type": "string" }, "description": { "maxLength": 1000, "minLength": 10, "type": "string" }, "externalReference": { "maxLength": 100, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" }, "patientId": { "format": "uuid", "type": "string" } }, "required": [ "category", "externalReference", "description" ], "type": "object" }, "SlotGenerationRequest": { "additionalProperties": false, "properties": { "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "from": { "format": "date", "type": "string" }, "to": { "format": "date", "type": "string" } }, "required": [ "from", "to", "expectedVersion" ], "type": "object" }, "SlotGenerationResult": { "additionalProperties": false, "properties": { "duplicateCount": { "minimum": 0, "type": "integer" }, "from": { "format": "date", "type": "string" }, "generatedCount": { "minimum": 0, "type": "integer" }, "ruleId": { "$ref": "#/components/schemas/Uuid" }, "ruleVersion": { "$ref": "#/components/schemas/Version" }, "skippedCount": { "minimum": 0, "type": "integer" }, "to": { "format": "date", "type": "string" } }, "required": [ "ruleId", "from", "to", "ruleVersion", "generatedCount", "skippedCount", "duplicateCount" ], "type": "object" }, "SpecialtyCreate": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "description": { "maxLength": 500, "type": "string" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "code", "name", "active" ], "type": "object" }, "SpecialtyDetail": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "description": { "maxLength": 500, "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "active", "version" ], "type": "object" }, "SpecialtyPage": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/SpecialtySummary" }, "maxItems": 100, "type": "array" }, "nextCursor": { "$ref": "#/components/schemas/PageCursor" } }, "required": [ "items", "nextCursor" ], "type": "object" }, "SpecialtySummary": { "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "description": { "maxLength": 500, "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "id", "code", "name", "active", "version" ], "type": "object" }, "SpecialtyUpdate": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "type": "boolean" }, "code": { "maxLength": 40, "minLength": 1, "type": "string" }, "description": { "maxLength": 500, "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "expectedVersion" ], "type": "object" }, "Uuid": { "example": "b1000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" }, "Version": { "example": 1, "minimum": 1, "type": "integer" }, "WaitlistCreate": { "additionalProperties": false, "properties": { "dateFrom": { "format": "date", "type": "string" }, "dateTo": { "format": "date", "type": "string" }, "locationId": { "format": "uuid", "type": "string" }, "patientId": { "format": "uuid", "type": "string" }, "practitionerId": { "format": "uuid", "type": "string" }, "preferredPeriods": { "items": { "enum": [ "MORNING", "AFTERNOON", "EVENING" ], "type": "string" }, "minItems": 1, "type": "array", "uniqueItems": true }, "serviceId": { "format": "uuid", "type": "string" } }, "required": [ "patientId", "serviceId", "dateFrom", "dateTo", "preferredPeriods" ], "type": "object" } }, "securitySchemes": { "servicePrincipal": { "description": "OAuth 2.0 client credentials emitido para una aplicacion, tenant y empresa autorizados.", "flows": { "clientCredentials": { "scopes": { "appointment-events:read": "Reproducir eventos de citas.", "appointments:read": "Consultar citas.", "appointments:write": "Reservar, cancelar y reprogramar citas.", "availability:read": "Consultar opciones de agenda.", "configuration:read": "Consultar catalogos administrativos de configuracion.", "configuration:write": "Crear, actualizar y eliminar catalogos administrativos.", "contracts:read": "Consultar servicios contratados.", "eligibility:read": "Evaluar elegibilidad de cobertura.", "patients:read": "Consultar identidad de pacientes.", "patients:write": "Registrar y actualizar pacientes.", "practitioners:read": "Consultar profesionales reservables.", "preauthorizations:write": "Radicar preautorizaciones.", "scheduling:generate": "Generar slots desde una regla autorizada.", "scheduling:read": "Consultar configuracion de agenda.", "scheduling:write": "Mantener programas, reglas, relaciones, festivos y bloqueos.", "siau:write": "Crear casos SIAU.", "waitlist:write": "Registrar entradas de lista de espera." }, "tokenUrl": "https://auth.magnosoft.com.co/oauth2/token" } }, "type": "oauth2" } } }, "externalDocs": { "description": "Portal MagnoSoft Developers", "url": "https://magnosoft.com.co/developers/citas-medicas/api-externa-v1/" }, "info": { "contact": { "name": "MagnoSoft Developers", "url": "https://magnosoft.com.co/developers/" }, "description": "Contrato de integracion maquina a maquina para el flujo esencial del Sistema de Administracion Hospitalaria (SAH). Cada operacion declara `x-api-status`; las operaciones preview describen trabajo futuro y no deben usarse hasta que el portal las marque stable. El tenant y la empresa siempre se derivan del token; nunca se reciben como parametros ni headers del consumidor. Las fechas operativas usan America/Bogota y los ejemplos son completamente sinteticos.", "license": { "identifier": "LicenseRef-MagnoSoft-Proprietary", "name": "Uso propietario MagnoSoft" }, "termsOfService": "https://magnosoft.com.co/terminos-y-condiciones", "title": "MagnoSoft Citas Medicas External API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/admin/configuration/appointment-types": { "get": { "description": "Lista tipos de cita del organization y company derivados del token, con busqueda, filtros permitidos, orden estable y paginacion acotada; nunca expone metadata interna ni datos de otros tenants.", "operationId": "listAppointmentTypes", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Busqueda textual allowlisted sobre codigo y nombre.", "in": "query", "name": "search", "required": false, "schema": { "default": "", "maxLength": 100, "minLength": 1, "type": "string" } }, { "description": "Filtra por estado administrable del recurso.", "in": "query", "name": "active", "required": false, "schema": { "default": "", "type": "boolean" } }, { "description": "Orden estable permitido para catalogos.", "in": "query", "name": "sort", "required": false, "schema": { "default": "code", "enum": [ "code", "name", "-code", "-name" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "items": [ { "active": true, "code": "CONS-30", "createdAt": "2026-07-26T14:00:00-05:00", "durationMinutes": 30, "id": "b2000003-0000-4000-8000-000000000001", "name": "Consulta sintetica de 30 minutos", "opportunityDefinitionId": "b1000000-0000-4000-8000-000000000003", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } ], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/AppointmentTypePage" } } }, "description": "Pagina tipada de tipos de cita visibles.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Listar tipos de cita", "tags": [ "Configuracion - Tipos de cita" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/appointment-types?limit=25\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/appointment-types?limit=25`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "post": { "description": "Crea tipo de cita mediante un DTO nominal cerrado, valida referencias dentro del alcance firmado y conserva el resultado para reintentos idempotentes sin publicar metadata generica.", "operationId": "createAppointmentType", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "CONS-30", "durationMinutes": 30, "name": "Consulta sintetica de 30 minutos", "opportunityDefinitionId": "b1000000-0000-4000-8000-000000000003" } } }, "schema": { "additionalProperties": false, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "durationMinutes": { "default": "", "maximum": 480, "minimum": 5, "type": "integer" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" }, "opportunityDefinitionId": { "$ref": "#/components/schemas/Uuid" } }, "required": [ "code", "name", "durationMinutes", "opportunityDefinitionId", "active" ], "type": "object" } } }, "description": "Atributos administrables y sinteticos de tipo de cita.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "CONS-30", "createdAt": "2026-07-26T14:00:00-05:00", "durationMinutes": 30, "id": "b2000003-0000-4000-8000-000000000001", "name": "Consulta sintetica de 30 minutos", "opportunityDefinitionId": "b1000000-0000-4000-8000-000000000003", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/AppointmentTypeDetail" } } }, "description": "AppointmentType creado con version inicial o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Crear tipo de cita", "tags": [ "Configuracion - Tipos de cita" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/appointment-types\" --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"CONS-30\",\"name\":\"Consulta sintetica de 30 minutos\",\"durationMinutes\":30,\"opportunityDefinitionId\":\"b1000000-0000-4000-8000-000000000003\",\"active\":true}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/appointment-types`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"CONS-30\",\"name\":\"Consulta sintetica de 30 minutos\",\"durationMinutes\":30,\"opportunityDefinitionId\":\"b1000000-0000-4000-8000-000000000003\",\"active\":true}) });" } ] } }, "/admin/configuration/appointment-types/{id}": { "delete": { "description": "Elimina tipo de cita solo cuando la version coincide y no existen referencias protegidas; los reintentos con igual clave devuelven la confirmacion original de forma segura.", "operationId": "deleteAppointmentType", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } }, { "description": "Version observada antes de eliminar el recurso existente.", "in": "query", "name": "expectedVersion", "required": true, "schema": { "$ref": "#/components/schemas/ExpectedVersion" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "deleted": true, "id": "b2000003-0000-4000-8000-000000000001", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/DeletionResult" } } }, "description": "Confirmacion tipada de eliminacion.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Eliminar tipo de cita", "tags": [ "Configuracion - Tipos de cita" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/appointment-types/{id}?expectedVersion=1\" --request DELETE --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/appointment-types/{id}?expectedVersion=1`, { method: 'DELETE', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' } });" } ] }, "get": { "description": "Obtiene la proyeccion detallada y cerrada de tipo de cita visible para el alcance autenticado; un identificador ajeno se trata como no encontrado y no revela existencia.", "operationId": "getAppointmentType", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "CONS-30", "createdAt": "2026-07-26T14:00:00-05:00", "durationMinutes": 30, "id": "b2000003-0000-4000-8000-000000000001", "name": "Consulta sintetica de 30 minutos", "opportunityDefinitionId": "b1000000-0000-4000-8000-000000000003", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/AppointmentTypeDetail" } } }, "description": "Detalle tipado de tipo de cita.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Consultar tipo de cita", "tags": [ "Configuracion - Tipos de cita" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/appointment-types/{id}\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/appointment-types/{id}`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "patch": { "description": "Actualiza solamente atributos administrables de tipo de cita, exige la version observada y una clave idempotente, y rechaza referencias externas al organization o company autorizado.", "operationId": "updateAppointmentType", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "CONS-30", "durationMinutes": 30, "expectedVersion": 1, "name": "Consulta sintetica de 30 minutos", "opportunityDefinitionId": "b1000000-0000-4000-8000-000000000003" } } }, "schema": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "durationMinutes": { "default": "", "maximum": 480, "minimum": 5, "type": "integer" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" }, "opportunityDefinitionId": { "$ref": "#/components/schemas/Uuid" } }, "required": [ "expectedVersion" ], "type": "object" } } }, "description": "Cambios parciales cerrados y expectedVersion vigente.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "CONS-30", "createdAt": "2026-07-26T14:00:00-05:00", "durationMinutes": 30, "id": "b2000003-0000-4000-8000-000000000001", "name": "Consulta sintetica de 30 minutos", "opportunityDefinitionId": "b1000000-0000-4000-8000-000000000003", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 2 } } }, "schema": { "$ref": "#/components/schemas/AppointmentTypeDetail" } } }, "description": "AppointmentType actualizado o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Actualizar tipo de cita", "tags": [ "Configuracion - Tipos de cita" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/appointment-types/{id}\" --request PATCH --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"CONS-30\",\"name\":\"Consulta sintetica de 30 minutos\",\"durationMinutes\":30,\"opportunityDefinitionId\":\"b1000000-0000-4000-8000-000000000003\",\"active\":true,\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/appointment-types/{id}`, { method: 'PATCH', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"CONS-30\",\"name\":\"Consulta sintetica de 30 minutos\",\"durationMinutes\":30,\"opportunityDefinitionId\":\"b1000000-0000-4000-8000-000000000003\",\"active\":true,\"expectedVersion\":1}) });" } ] } }, "/admin/configuration/cancellation-reasons": { "get": { "description": "Lista motivos de cancelacion del organization y company derivados del token, con busqueda, filtros permitidos, orden estable y paginacion acotada; nunca expone metadata interna ni datos de otros tenants.", "operationId": "listCancellationReasons", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Busqueda textual allowlisted sobre codigo y nombre.", "in": "query", "name": "search", "required": false, "schema": { "default": "", "maxLength": 100, "minLength": 1, "type": "string" } }, { "description": "Filtra por estado administrable del recurso.", "in": "query", "name": "active", "required": false, "schema": { "default": "", "type": "boolean" } }, { "description": "Orden estable permitido para catalogos.", "in": "query", "name": "sort", "required": false, "schema": { "default": "code", "enum": [ "code", "name", "-code", "-name" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "items": [ { "active": true, "code": "SOLICITUD", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000009-0000-4000-8000-000000000001", "name": "Solicitud sintetica del usuario", "requiresComment": false, "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } ], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/CancellationReasonPage" } } }, "description": "Pagina tipada de motivos de cancelacion visibles.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Listar motivos de cancelacion", "tags": [ "Configuracion - Motivos de cancelacion" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/cancellation-reasons?limit=25\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/cancellation-reasons?limit=25`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "post": { "description": "Crea motivo de cancelacion mediante un DTO nominal cerrado, valida referencias dentro del alcance firmado y conserva el resultado para reintentos idempotentes sin publicar metadata generica.", "operationId": "createCancellationReason", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "SOLICITUD", "name": "Solicitud sintetica del usuario", "requiresComment": false } } }, "schema": { "additionalProperties": false, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" }, "requiresComment": { "default": "", "type": "boolean" } }, "required": [ "code", "name", "requiresComment", "active" ], "type": "object" } } }, "description": "Atributos administrables y sinteticos de motivo de cancelacion.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "SOLICITUD", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000009-0000-4000-8000-000000000001", "name": "Solicitud sintetica del usuario", "requiresComment": false, "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/CancellationReasonDetail" } } }, "description": "CancellationReason creado con version inicial o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Crear motivo de cancelacion", "tags": [ "Configuracion - Motivos de cancelacion" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/cancellation-reasons\" --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"SOLICITUD\",\"name\":\"Solicitud sintetica del usuario\",\"requiresComment\":false,\"active\":true}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/cancellation-reasons`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"SOLICITUD\",\"name\":\"Solicitud sintetica del usuario\",\"requiresComment\":false,\"active\":true}) });" } ] } }, "/admin/configuration/cancellation-reasons/{id}": { "delete": { "description": "Elimina motivo de cancelacion solo cuando la version coincide y no existen referencias protegidas; los reintentos con igual clave devuelven la confirmacion original de forma segura.", "operationId": "deleteCancellationReason", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } }, { "description": "Version observada antes de eliminar el recurso existente.", "in": "query", "name": "expectedVersion", "required": true, "schema": { "$ref": "#/components/schemas/ExpectedVersion" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "deleted": true, "id": "b2000009-0000-4000-8000-000000000001", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/DeletionResult" } } }, "description": "Confirmacion tipada de eliminacion.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Eliminar motivo de cancelacion", "tags": [ "Configuracion - Motivos de cancelacion" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/cancellation-reasons/{id}?expectedVersion=1\" --request DELETE --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/cancellation-reasons/{id}?expectedVersion=1`, { method: 'DELETE', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' } });" } ] }, "get": { "description": "Obtiene la proyeccion detallada y cerrada de motivo de cancelacion visible para el alcance autenticado; un identificador ajeno se trata como no encontrado y no revela existencia.", "operationId": "getCancellationReason", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "SOLICITUD", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000009-0000-4000-8000-000000000001", "name": "Solicitud sintetica del usuario", "requiresComment": false, "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/CancellationReasonDetail" } } }, "description": "Detalle tipado de motivo de cancelacion.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Consultar motivo de cancelacion", "tags": [ "Configuracion - Motivos de cancelacion" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/cancellation-reasons/{id}\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/cancellation-reasons/{id}`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "patch": { "description": "Actualiza solamente atributos administrables de motivo de cancelacion, exige la version observada y una clave idempotente, y rechaza referencias externas al organization o company autorizado.", "operationId": "updateCancellationReason", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "SOLICITUD", "expectedVersion": 1, "name": "Solicitud sintetica del usuario", "requiresComment": false } } }, "schema": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" }, "requiresComment": { "default": "", "type": "boolean" } }, "required": [ "expectedVersion" ], "type": "object" } } }, "description": "Cambios parciales cerrados y expectedVersion vigente.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "SOLICITUD", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000009-0000-4000-8000-000000000001", "name": "Solicitud sintetica del usuario", "requiresComment": false, "updatedAt": "2026-07-26T14:00:00-05:00", "version": 2 } } }, "schema": { "$ref": "#/components/schemas/CancellationReasonDetail" } } }, "description": "CancellationReason actualizado o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Actualizar motivo de cancelacion", "tags": [ "Configuracion - Motivos de cancelacion" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/cancellation-reasons/{id}\" --request PATCH --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"SOLICITUD\",\"name\":\"Solicitud sintetica del usuario\",\"requiresComment\":false,\"active\":true,\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/cancellation-reasons/{id}`, { method: 'PATCH', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"SOLICITUD\",\"name\":\"Solicitud sintetica del usuario\",\"requiresComment\":false,\"active\":true,\"expectedVersion\":1}) });" } ] } }, "/admin/configuration/consultation-types": { "get": { "description": "Lista tipos de consulta del organization y company derivados del token, con busqueda, filtros permitidos, orden estable y paginacion acotada; nunca expone metadata interna ni datos de otros tenants.", "operationId": "listConsultationTypes", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Busqueda textual allowlisted sobre codigo y nombre.", "in": "query", "name": "search", "required": false, "schema": { "default": "", "maxLength": 100, "minLength": 1, "type": "string" } }, { "description": "Filtra por estado administrable del recurso.", "in": "query", "name": "active", "required": false, "schema": { "default": "", "type": "boolean" } }, { "description": "Orden estable permitido para catalogos.", "in": "query", "name": "sort", "required": false, "schema": { "default": "code", "enum": [ "code", "name", "-code", "-name" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "items": [ { "active": true, "code": "PRIMERA-VEZ", "createdAt": "2026-07-26T14:00:00-05:00", "description": "Consulta inicial de demostracion.", "id": "b2000004-0000-4000-8000-000000000001", "name": "Primera vez sintetica", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } ], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/ConsultationTypePage" } } }, "description": "Pagina tipada de tipos de consulta visibles.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Listar tipos de consulta", "tags": [ "Configuracion - Tipos de consulta" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/consultation-types?limit=25\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/consultation-types?limit=25`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "post": { "description": "Crea tipo de consulta mediante un DTO nominal cerrado, valida referencias dentro del alcance firmado y conserva el resultado para reintentos idempotentes sin publicar metadata generica.", "operationId": "createConsultationType", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "PRIMERA-VEZ", "description": "Consulta inicial de demostracion.", "name": "Primera vez sintetica" } } }, "schema": { "additionalProperties": false, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "description": { "default": "", "maxLength": 500, "type": "string" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "code", "name", "active" ], "type": "object" } } }, "description": "Atributos administrables y sinteticos de tipo de consulta.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "PRIMERA-VEZ", "createdAt": "2026-07-26T14:00:00-05:00", "description": "Consulta inicial de demostracion.", "id": "b2000004-0000-4000-8000-000000000001", "name": "Primera vez sintetica", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/ConsultationTypeDetail" } } }, "description": "ConsultationType creado con version inicial o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Crear tipo de consulta", "tags": [ "Configuracion - Tipos de consulta" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/consultation-types\" --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"PRIMERA-VEZ\",\"name\":\"Primera vez sintetica\",\"description\":\"Consulta inicial de demostracion.\",\"active\":true}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/consultation-types`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"PRIMERA-VEZ\",\"name\":\"Primera vez sintetica\",\"description\":\"Consulta inicial de demostracion.\",\"active\":true}) });" } ] } }, "/admin/configuration/consultation-types/{id}": { "delete": { "description": "Elimina tipo de consulta solo cuando la version coincide y no existen referencias protegidas; los reintentos con igual clave devuelven la confirmacion original de forma segura.", "operationId": "deleteConsultationType", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } }, { "description": "Version observada antes de eliminar el recurso existente.", "in": "query", "name": "expectedVersion", "required": true, "schema": { "$ref": "#/components/schemas/ExpectedVersion" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "deleted": true, "id": "b2000004-0000-4000-8000-000000000001", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/DeletionResult" } } }, "description": "Confirmacion tipada de eliminacion.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Eliminar tipo de consulta", "tags": [ "Configuracion - Tipos de consulta" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/consultation-types/{id}?expectedVersion=1\" --request DELETE --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/consultation-types/{id}?expectedVersion=1`, { method: 'DELETE', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' } });" } ] }, "get": { "description": "Obtiene la proyeccion detallada y cerrada de tipo de consulta visible para el alcance autenticado; un identificador ajeno se trata como no encontrado y no revela existencia.", "operationId": "getConsultationType", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "PRIMERA-VEZ", "createdAt": "2026-07-26T14:00:00-05:00", "description": "Consulta inicial de demostracion.", "id": "b2000004-0000-4000-8000-000000000001", "name": "Primera vez sintetica", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/ConsultationTypeDetail" } } }, "description": "Detalle tipado de tipo de consulta.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Consultar tipo de consulta", "tags": [ "Configuracion - Tipos de consulta" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/consultation-types/{id}\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/consultation-types/{id}`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "patch": { "description": "Actualiza solamente atributos administrables de tipo de consulta, exige la version observada y una clave idempotente, y rechaza referencias externas al organization o company autorizado.", "operationId": "updateConsultationType", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "PRIMERA-VEZ", "description": "Consulta inicial de demostracion.", "expectedVersion": 1, "name": "Primera vez sintetica" } } }, "schema": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "description": { "default": "", "maxLength": 500, "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "expectedVersion" ], "type": "object" } } }, "description": "Cambios parciales cerrados y expectedVersion vigente.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "PRIMERA-VEZ", "createdAt": "2026-07-26T14:00:00-05:00", "description": "Consulta inicial de demostracion.", "id": "b2000004-0000-4000-8000-000000000001", "name": "Primera vez sintetica", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 2 } } }, "schema": { "$ref": "#/components/schemas/ConsultationTypeDetail" } } }, "description": "ConsultationType actualizado o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Actualizar tipo de consulta", "tags": [ "Configuracion - Tipos de consulta" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/consultation-types/{id}\" --request PATCH --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"PRIMERA-VEZ\",\"name\":\"Primera vez sintetica\",\"description\":\"Consulta inicial de demostracion.\",\"active\":true,\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/consultation-types/{id}`, { method: 'PATCH', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"PRIMERA-VEZ\",\"name\":\"Primera vez sintetica\",\"description\":\"Consulta inicial de demostracion.\",\"active\":true,\"expectedVersion\":1}) });" } ] } }, "/admin/configuration/contracts": { "get": { "description": "Lista contratos del organization y company derivados del token, con busqueda, filtros permitidos, orden estable y paginacion acotada; nunca expone metadata interna ni datos de otros tenants.", "operationId": "listContracts", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Busqueda textual allowlisted sobre codigo y nombre.", "in": "query", "name": "search", "required": false, "schema": { "default": "", "maxLength": 100, "minLength": 1, "type": "string" } }, { "description": "Filtra por estado administrable del recurso.", "in": "query", "name": "active", "required": false, "schema": { "default": "", "type": "boolean" } }, { "description": "Orden estable permitido para catalogos.", "in": "query", "name": "sort", "required": false, "schema": { "default": "code", "enum": [ "code", "name", "-code", "-name" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "items": [ { "active": true, "code": "CTR-DEMO", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000007-0000-4000-8000-000000000001", "name": "Contrato Sintetico", "payerId": "b1000000-0000-4000-8000-000000000004", "updatedAt": "2026-07-26T14:00:00-05:00", "validFrom": "2026-01-01", "validTo": "2026-12-31", "version": 1 } ], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/ContractPage" } } }, "description": "Pagina tipada de contratos visibles.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Listar contratos", "tags": [ "Configuracion - Contratos" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/contracts?limit=25\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/contracts?limit=25`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "post": { "description": "Crea contrato mediante un DTO nominal cerrado, valida referencias dentro del alcance firmado y conserva el resultado para reintentos idempotentes sin publicar metadata generica.", "operationId": "createContract", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "CTR-DEMO", "name": "Contrato Sintetico", "payerId": "b1000000-0000-4000-8000-000000000004", "validFrom": "2026-01-01", "validTo": "2026-12-31" } } }, "schema": { "additionalProperties": false, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" }, "payerId": { "$ref": "#/components/schemas/Uuid" }, "validFrom": { "default": "", "format": "date", "type": "string" }, "validTo": { "default": "", "format": "date", "type": "string" } }, "required": [ "code", "name", "payerId", "validFrom", "validTo", "active" ], "type": "object" } } }, "description": "Atributos administrables y sinteticos de contrato.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "CTR-DEMO", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000007-0000-4000-8000-000000000001", "name": "Contrato Sintetico", "payerId": "b1000000-0000-4000-8000-000000000004", "updatedAt": "2026-07-26T14:00:00-05:00", "validFrom": "2026-01-01", "validTo": "2026-12-31", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/ContractDetail" } } }, "description": "Contract creado con version inicial o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Crear contrato", "tags": [ "Configuracion - Contratos" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/contracts\" --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"CTR-DEMO\",\"name\":\"Contrato Sintetico\",\"payerId\":\"b1000000-0000-4000-8000-000000000004\",\"validFrom\":\"2026-01-01\",\"validTo\":\"2026-12-31\",\"active\":true}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/contracts`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"CTR-DEMO\",\"name\":\"Contrato Sintetico\",\"payerId\":\"b1000000-0000-4000-8000-000000000004\",\"validFrom\":\"2026-01-01\",\"validTo\":\"2026-12-31\",\"active\":true}) });" } ] } }, "/admin/configuration/contracts/{id}": { "delete": { "description": "Elimina contrato solo cuando la version coincide y no existen referencias protegidas; los reintentos con igual clave devuelven la confirmacion original de forma segura.", "operationId": "deleteContract", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } }, { "description": "Version observada antes de eliminar el recurso existente.", "in": "query", "name": "expectedVersion", "required": true, "schema": { "$ref": "#/components/schemas/ExpectedVersion" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "deleted": true, "id": "b2000007-0000-4000-8000-000000000001", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/DeletionResult" } } }, "description": "Confirmacion tipada de eliminacion.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Eliminar contrato", "tags": [ "Configuracion - Contratos" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/contracts/{id}?expectedVersion=1\" --request DELETE --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/contracts/{id}?expectedVersion=1`, { method: 'DELETE', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' } });" } ] }, "get": { "description": "Obtiene la proyeccion detallada y cerrada de contrato visible para el alcance autenticado; un identificador ajeno se trata como no encontrado y no revela existencia.", "operationId": "getContract", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "CTR-DEMO", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000007-0000-4000-8000-000000000001", "name": "Contrato Sintetico", "payerId": "b1000000-0000-4000-8000-000000000004", "updatedAt": "2026-07-26T14:00:00-05:00", "validFrom": "2026-01-01", "validTo": "2026-12-31", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/ContractDetail" } } }, "description": "Detalle tipado de contrato.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Consultar contrato", "tags": [ "Configuracion - Contratos" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/contracts/{id}\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/contracts/{id}`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "patch": { "description": "Actualiza solamente atributos administrables de contrato, exige la version observada y una clave idempotente, y rechaza referencias externas al organization o company autorizado.", "operationId": "updateContract", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "CTR-DEMO", "expectedVersion": 1, "name": "Contrato Sintetico", "payerId": "b1000000-0000-4000-8000-000000000004", "validFrom": "2026-01-01", "validTo": "2026-12-31" } } }, "schema": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" }, "payerId": { "$ref": "#/components/schemas/Uuid" }, "validFrom": { "default": "", "format": "date", "type": "string" }, "validTo": { "default": "", "format": "date", "type": "string" } }, "required": [ "expectedVersion" ], "type": "object" } } }, "description": "Cambios parciales cerrados y expectedVersion vigente.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "CTR-DEMO", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000007-0000-4000-8000-000000000001", "name": "Contrato Sintetico", "payerId": "b1000000-0000-4000-8000-000000000004", "updatedAt": "2026-07-26T14:00:00-05:00", "validFrom": "2026-01-01", "validTo": "2026-12-31", "version": 2 } } }, "schema": { "$ref": "#/components/schemas/ContractDetail" } } }, "description": "Contract actualizado o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Actualizar contrato", "tags": [ "Configuracion - Contratos" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/contracts/{id}\" --request PATCH --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"CTR-DEMO\",\"name\":\"Contrato Sintetico\",\"payerId\":\"b1000000-0000-4000-8000-000000000004\",\"validFrom\":\"2026-01-01\",\"validTo\":\"2026-12-31\",\"active\":true,\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/contracts/{id}`, { method: 'PATCH', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"CTR-DEMO\",\"name\":\"Contrato Sintetico\",\"payerId\":\"b1000000-0000-4000-8000-000000000004\",\"validFrom\":\"2026-01-01\",\"validTo\":\"2026-12-31\",\"active\":true,\"expectedVersion\":1}) });" } ] } }, "/admin/configuration/locations": { "get": { "description": "Lista sedes del organization y company derivados del token, con busqueda, filtros permitidos, orden estable y paginacion acotada; nunca expone metadata interna ni datos de otros tenants.", "operationId": "listLocations", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Busqueda textual allowlisted sobre codigo y nombre.", "in": "query", "name": "search", "required": false, "schema": { "default": "", "maxLength": 100, "minLength": 1, "type": "string" } }, { "description": "Filtra por estado administrable del recurso.", "in": "query", "name": "active", "required": false, "schema": { "default": "", "type": "boolean" } }, { "description": "Orden estable permitido para catalogos.", "in": "query", "name": "sort", "required": false, "schema": { "default": "code", "enum": [ "code", "name", "-code", "-name" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "items": [ { "active": true, "address": "Calle 100 # 10-20", "cityCode": "11001", "code": "SEDE-NORTE", "createdAt": "2026-07-26T14:00:00-05:00", "departmentCode": "11", "id": "b2000000-0000-4000-8000-000000000001", "name": "Sede Norte Sintetica", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } ], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/LocationPage" } } }, "description": "Pagina tipada de sedes visibles.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Listar sedes", "tags": [ "Configuracion - Sedes" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/locations?limit=25\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/locations?limit=25`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "post": { "description": "Crea sede mediante un DTO nominal cerrado, valida referencias dentro del alcance firmado y conserva el resultado para reintentos idempotentes sin publicar metadata generica.", "operationId": "createLocation", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "address": "Calle 100 # 10-20", "cityCode": "11001", "code": "SEDE-NORTE", "departmentCode": "11", "name": "Sede Norte Sintetica" } } }, "schema": { "additionalProperties": false, "properties": { "active": { "default": "", "type": "boolean" }, "address": { "default": "", "maxLength": 240, "minLength": 3, "type": "string" }, "cityCode": { "default": "", "maxLength": 5, "minLength": 5, "pattern": "^[0-9]{5}", "type": "string" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "departmentCode": { "default": "", "maxLength": 2, "minLength": 2, "pattern": "^[0-9]{2}", "type": "string" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "code", "name", "address", "cityCode", "departmentCode", "active" ], "type": "object" } } }, "description": "Atributos administrables y sinteticos de sede.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "address": "Calle 100 # 10-20", "cityCode": "11001", "code": "SEDE-NORTE", "createdAt": "2026-07-26T14:00:00-05:00", "departmentCode": "11", "id": "b2000000-0000-4000-8000-000000000001", "name": "Sede Norte Sintetica", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/LocationDetail" } } }, "description": "Location creado con version inicial o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Crear sede", "tags": [ "Configuracion - Sedes" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/locations\" --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"SEDE-NORTE\",\"name\":\"Sede Norte Sintetica\",\"address\":\"Calle 100 # 10-20\",\"cityCode\":\"11001\",\"departmentCode\":\"11\",\"active\":true}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/locations`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"SEDE-NORTE\",\"name\":\"Sede Norte Sintetica\",\"address\":\"Calle 100 # 10-20\",\"cityCode\":\"11001\",\"departmentCode\":\"11\",\"active\":true}) });" } ] } }, "/admin/configuration/locations/{id}": { "delete": { "description": "Elimina sede solo cuando la version coincide y no existen referencias protegidas; los reintentos con igual clave devuelven la confirmacion original de forma segura.", "operationId": "deleteLocation", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } }, { "description": "Version observada antes de eliminar el recurso existente.", "in": "query", "name": "expectedVersion", "required": true, "schema": { "$ref": "#/components/schemas/ExpectedVersion" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "deleted": true, "id": "b2000000-0000-4000-8000-000000000001", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/DeletionResult" } } }, "description": "Confirmacion tipada de eliminacion.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Eliminar sede", "tags": [ "Configuracion - Sedes" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/locations/{id}?expectedVersion=1\" --request DELETE --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/locations/{id}?expectedVersion=1`, { method: 'DELETE', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' } });" } ] }, "get": { "description": "Obtiene la proyeccion detallada y cerrada de sede visible para el alcance autenticado; un identificador ajeno se trata como no encontrado y no revela existencia.", "operationId": "getLocation", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "address": "Calle 100 # 10-20", "cityCode": "11001", "code": "SEDE-NORTE", "createdAt": "2026-07-26T14:00:00-05:00", "departmentCode": "11", "id": "b2000000-0000-4000-8000-000000000001", "name": "Sede Norte Sintetica", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/LocationDetail" } } }, "description": "Detalle tipado de sede.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Consultar sede", "tags": [ "Configuracion - Sedes" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/locations/{id}\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/locations/{id}`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "patch": { "description": "Actualiza solamente atributos administrables de sede, exige la version observada y una clave idempotente, y rechaza referencias externas al organization o company autorizado.", "operationId": "updateLocation", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "address": "Calle 100 # 10-20", "cityCode": "11001", "code": "SEDE-NORTE", "departmentCode": "11", "expectedVersion": 1, "name": "Sede Norte Sintetica" } } }, "schema": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "default": "", "type": "boolean" }, "address": { "default": "", "maxLength": 240, "minLength": 3, "type": "string" }, "cityCode": { "default": "", "maxLength": 5, "minLength": 5, "pattern": "^[0-9]{5}", "type": "string" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "departmentCode": { "default": "", "maxLength": 2, "minLength": 2, "pattern": "^[0-9]{2}", "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "expectedVersion" ], "type": "object" } } }, "description": "Cambios parciales cerrados y expectedVersion vigente.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "address": "Calle 100 # 10-20", "cityCode": "11001", "code": "SEDE-NORTE", "createdAt": "2026-07-26T14:00:00-05:00", "departmentCode": "11", "id": "b2000000-0000-4000-8000-000000000001", "name": "Sede Norte Sintetica", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 2 } } }, "schema": { "$ref": "#/components/schemas/LocationDetail" } } }, "description": "Location actualizado o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Actualizar sede", "tags": [ "Configuracion - Sedes" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/locations/{id}\" --request PATCH --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"SEDE-NORTE\",\"name\":\"Sede Norte Sintetica\",\"address\":\"Calle 100 # 10-20\",\"cityCode\":\"11001\",\"departmentCode\":\"11\",\"active\":true,\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/locations/{id}`, { method: 'PATCH', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"SEDE-NORTE\",\"name\":\"Sede Norte Sintetica\",\"address\":\"Calle 100 # 10-20\",\"cityCode\":\"11001\",\"departmentCode\":\"11\",\"active\":true,\"expectedVersion\":1}) });" } ] } }, "/admin/configuration/no-show-reasons": { "get": { "description": "Lista motivos de inasistencia del organization y company derivados del token, con busqueda, filtros permitidos, orden estable y paginacion acotada; nunca expone metadata interna ni datos de otros tenants.", "operationId": "listNoShowReasons", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Busqueda textual allowlisted sobre codigo y nombre.", "in": "query", "name": "search", "required": false, "schema": { "default": "", "maxLength": 100, "minLength": 1, "type": "string" } }, { "description": "Filtra por estado administrable del recurso.", "in": "query", "name": "active", "required": false, "schema": { "default": "", "type": "boolean" } }, { "description": "Orden estable permitido para catalogos.", "in": "query", "name": "sort", "required": false, "schema": { "default": "code", "enum": [ "code", "name", "-code", "-name" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "items": [ { "active": true, "code": "NO-ASISTE", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000010-0000-4000-8000-000000000001", "name": "Inasistencia sintetica", "requiresComment": true, "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } ], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/NoShowReasonPage" } } }, "description": "Pagina tipada de motivos de inasistencia visibles.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Listar motivos de inasistencia", "tags": [ "Configuracion - Motivos de inasistencia" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/no-show-reasons?limit=25\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/no-show-reasons?limit=25`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "post": { "description": "Crea motivo de inasistencia mediante un DTO nominal cerrado, valida referencias dentro del alcance firmado y conserva el resultado para reintentos idempotentes sin publicar metadata generica.", "operationId": "createNoShowReason", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "NO-ASISTE", "name": "Inasistencia sintetica", "requiresComment": true } } }, "schema": { "additionalProperties": false, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" }, "requiresComment": { "default": "", "type": "boolean" } }, "required": [ "code", "name", "requiresComment", "active" ], "type": "object" } } }, "description": "Atributos administrables y sinteticos de motivo de inasistencia.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "NO-ASISTE", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000010-0000-4000-8000-000000000001", "name": "Inasistencia sintetica", "requiresComment": true, "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/NoShowReasonDetail" } } }, "description": "NoShowReason creado con version inicial o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Crear motivo de inasistencia", "tags": [ "Configuracion - Motivos de inasistencia" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/no-show-reasons\" --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"NO-ASISTE\",\"name\":\"Inasistencia sintetica\",\"requiresComment\":true,\"active\":true}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/no-show-reasons`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"NO-ASISTE\",\"name\":\"Inasistencia sintetica\",\"requiresComment\":true,\"active\":true}) });" } ] } }, "/admin/configuration/no-show-reasons/{id}": { "delete": { "description": "Elimina motivo de inasistencia solo cuando la version coincide y no existen referencias protegidas; los reintentos con igual clave devuelven la confirmacion original de forma segura.", "operationId": "deleteNoShowReason", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } }, { "description": "Version observada antes de eliminar el recurso existente.", "in": "query", "name": "expectedVersion", "required": true, "schema": { "$ref": "#/components/schemas/ExpectedVersion" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "deleted": true, "id": "b2000010-0000-4000-8000-000000000001", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/DeletionResult" } } }, "description": "Confirmacion tipada de eliminacion.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Eliminar motivo de inasistencia", "tags": [ "Configuracion - Motivos de inasistencia" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/no-show-reasons/{id}?expectedVersion=1\" --request DELETE --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/no-show-reasons/{id}?expectedVersion=1`, { method: 'DELETE', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' } });" } ] }, "get": { "description": "Obtiene la proyeccion detallada y cerrada de motivo de inasistencia visible para el alcance autenticado; un identificador ajeno se trata como no encontrado y no revela existencia.", "operationId": "getNoShowReason", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "NO-ASISTE", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000010-0000-4000-8000-000000000001", "name": "Inasistencia sintetica", "requiresComment": true, "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/NoShowReasonDetail" } } }, "description": "Detalle tipado de motivo de inasistencia.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Consultar motivo de inasistencia", "tags": [ "Configuracion - Motivos de inasistencia" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/no-show-reasons/{id}\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/no-show-reasons/{id}`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "patch": { "description": "Actualiza solamente atributos administrables de motivo de inasistencia, exige la version observada y una clave idempotente, y rechaza referencias externas al organization o company autorizado.", "operationId": "updateNoShowReason", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "NO-ASISTE", "expectedVersion": 1, "name": "Inasistencia sintetica", "requiresComment": true } } }, "schema": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" }, "requiresComment": { "default": "", "type": "boolean" } }, "required": [ "expectedVersion" ], "type": "object" } } }, "description": "Cambios parciales cerrados y expectedVersion vigente.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "NO-ASISTE", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000010-0000-4000-8000-000000000001", "name": "Inasistencia sintetica", "requiresComment": true, "updatedAt": "2026-07-26T14:00:00-05:00", "version": 2 } } }, "schema": { "$ref": "#/components/schemas/NoShowReasonDetail" } } }, "description": "NoShowReason actualizado o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Actualizar motivo de inasistencia", "tags": [ "Configuracion - Motivos de inasistencia" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/no-show-reasons/{id}\" --request PATCH --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"NO-ASISTE\",\"name\":\"Inasistencia sintetica\",\"requiresComment\":true,\"active\":true,\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/no-show-reasons/{id}`, { method: 'PATCH', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"NO-ASISTE\",\"name\":\"Inasistencia sintetica\",\"requiresComment\":true,\"active\":true,\"expectedVersion\":1}) });" } ] } }, "/admin/configuration/opportunity-definitions": { "get": { "description": "Lista definiciones de oportunidad del organization y company derivados del token, con busqueda, filtros permitidos, orden estable y paginacion acotada; nunca expone metadata interna ni datos de otros tenants.", "operationId": "listOpportunityDefinitions", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Busqueda textual allowlisted sobre codigo y nombre.", "in": "query", "name": "search", "required": false, "schema": { "default": "", "maxLength": 100, "minLength": 1, "type": "string" } }, { "description": "Filtra por estado administrable del recurso.", "in": "query", "name": "active", "required": false, "schema": { "default": "", "type": "boolean" } }, { "description": "Orden estable permitido para catalogos.", "in": "query", "name": "sort", "required": false, "schema": { "default": "code", "enum": [ "code", "name", "-code", "-name" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "items": [ { "active": true, "code": "OPORTUNA", "createdAt": "2026-07-26T14:00:00-05:00", "description": "Definicion de demostracion.", "id": "b2000005-0000-4000-8000-000000000001", "name": "Atencion oportuna sintetica", "protected": false, "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } ], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/OpportunityDefinitionPage" } } }, "description": "Pagina tipada de definiciones de oportunidad visibles.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Listar definiciones de oportunidad", "tags": [ "Configuracion - Oportunidades" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/opportunity-definitions?limit=25\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/opportunity-definitions?limit=25`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "post": { "description": "Crea definicion de oportunidad mediante un DTO nominal cerrado, valida referencias dentro del alcance firmado y conserva el resultado para reintentos idempotentes sin publicar metadata generica.", "operationId": "createOpportunityDefinition", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "OPORTUNA", "description": "Definicion de demostracion.", "name": "Atencion oportuna sintetica" } } }, "schema": { "additionalProperties": false, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "description": { "default": "", "maxLength": 500, "type": "string" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" }, "protected": { "readOnly": true, "type": "boolean" } }, "required": [ "code", "name", "active" ], "type": "object" } } }, "description": "Atributos administrables y sinteticos de definicion de oportunidad.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "OPORTUNA", "createdAt": "2026-07-26T14:00:00-05:00", "description": "Definicion de demostracion.", "id": "b2000005-0000-4000-8000-000000000001", "name": "Atencion oportuna sintetica", "protected": false, "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/OpportunityDefinitionDetail" } } }, "description": "OpportunityDefinition creado con version inicial o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Crear definicion de oportunidad", "tags": [ "Configuracion - Oportunidades" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/opportunity-definitions\" --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"OPORTUNA\",\"name\":\"Atencion oportuna sintetica\",\"description\":\"Definicion de demostracion.\",\"active\":true}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/opportunity-definitions`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"OPORTUNA\",\"name\":\"Atencion oportuna sintetica\",\"description\":\"Definicion de demostracion.\",\"active\":true}) });" } ] } }, "/admin/configuration/opportunity-definitions/{id}": { "delete": { "description": "Elimina definicion de oportunidad solo cuando la version coincide y no existen referencias protegidas; los reintentos con igual clave devuelven la confirmacion original de forma segura.", "operationId": "deleteOpportunityDefinition", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } }, { "description": "Version observada antes de eliminar el recurso existente.", "in": "query", "name": "expectedVersion", "required": true, "schema": { "$ref": "#/components/schemas/ExpectedVersion" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "deleted": true, "id": "b2000005-0000-4000-8000-000000000001", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/DeletionResult" } } }, "description": "Confirmacion tipada de eliminacion.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Eliminar definicion de oportunidad", "tags": [ "Configuracion - Oportunidades" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/opportunity-definitions/{id}?expectedVersion=1\" --request DELETE --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/opportunity-definitions/{id}?expectedVersion=1`, { method: 'DELETE', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' } });" } ] }, "get": { "description": "Obtiene la proyeccion detallada y cerrada de definicion de oportunidad visible para el alcance autenticado; un identificador ajeno se trata como no encontrado y no revela existencia.", "operationId": "getOpportunityDefinition", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "OPORTUNA", "createdAt": "2026-07-26T14:00:00-05:00", "description": "Definicion de demostracion.", "id": "b2000005-0000-4000-8000-000000000001", "name": "Atencion oportuna sintetica", "protected": false, "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/OpportunityDefinitionDetail" } } }, "description": "Detalle tipado de definicion de oportunidad.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Consultar definicion de oportunidad", "tags": [ "Configuracion - Oportunidades" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/opportunity-definitions/{id}\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/opportunity-definitions/{id}`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "patch": { "description": "Actualiza solamente atributos administrables de definicion de oportunidad, exige la version observada y una clave idempotente, y rechaza referencias externas al organization o company autorizado.", "operationId": "updateOpportunityDefinition", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "OPORTUNA", "description": "Definicion de demostracion.", "expectedVersion": 1, "name": "Atencion oportuna sintetica" } } }, "schema": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "description": { "default": "", "maxLength": 500, "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" }, "protected": { "readOnly": true, "type": "boolean" } }, "required": [ "expectedVersion" ], "type": "object" } } }, "description": "Cambios parciales cerrados y expectedVersion vigente.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "OPORTUNA", "createdAt": "2026-07-26T14:00:00-05:00", "description": "Definicion de demostracion.", "id": "b2000005-0000-4000-8000-000000000001", "name": "Atencion oportuna sintetica", "protected": false, "updatedAt": "2026-07-26T14:00:00-05:00", "version": 2 } } }, "schema": { "$ref": "#/components/schemas/OpportunityDefinitionDetail" } } }, "description": "OpportunityDefinition actualizado o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Actualizar definicion de oportunidad", "tags": [ "Configuracion - Oportunidades" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/opportunity-definitions/{id}\" --request PATCH --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"OPORTUNA\",\"name\":\"Atencion oportuna sintetica\",\"description\":\"Definicion de demostracion.\",\"active\":true,\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/opportunity-definitions/{id}`, { method: 'PATCH', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"OPORTUNA\",\"name\":\"Atencion oportuna sintetica\",\"description\":\"Definicion de demostracion.\",\"active\":true,\"expectedVersion\":1}) });" } ] } }, "/admin/configuration/payers": { "get": { "description": "Lista pagadores del organization y company derivados del token, con busqueda, filtros permitidos, orden estable y paginacion acotada; nunca expone metadata interna ni datos de otros tenants.", "operationId": "listPayers", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Busqueda textual allowlisted sobre codigo y nombre.", "in": "query", "name": "search", "required": false, "schema": { "default": "", "maxLength": 100, "minLength": 1, "type": "string" } }, { "description": "Filtra por estado administrable del recurso.", "in": "query", "name": "active", "required": false, "schema": { "default": "", "type": "boolean" } }, { "description": "Orden estable permitido para catalogos.", "in": "query", "name": "sort", "required": false, "schema": { "default": "code", "enum": [ "code", "name", "-code", "-name" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "items": [ { "active": true, "code": "PAG-DEMO", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000006-0000-4000-8000-000000000001", "name": "Pagador Sintetico", "taxId": "900000000-1", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } ], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/PayerPage" } } }, "description": "Pagina tipada de pagadores visibles.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Listar pagadores", "tags": [ "Configuracion - Pagadores" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/payers?limit=25\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/payers?limit=25`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "post": { "description": "Crea pagador mediante un DTO nominal cerrado, valida referencias dentro del alcance firmado y conserva el resultado para reintentos idempotentes sin publicar metadata generica.", "operationId": "createPayer", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "PAG-DEMO", "name": "Pagador Sintetico", "taxId": "900000000-1" } } }, "schema": { "additionalProperties": false, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" }, "taxId": { "default": "", "maxLength": 30, "minLength": 5, "type": "string" } }, "required": [ "code", "name", "taxId", "active" ], "type": "object" } } }, "description": "Atributos administrables y sinteticos de pagador.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "PAG-DEMO", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000006-0000-4000-8000-000000000001", "name": "Pagador Sintetico", "taxId": "900000000-1", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/PayerDetail" } } }, "description": "Payer creado con version inicial o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Crear pagador", "tags": [ "Configuracion - Pagadores" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/payers\" --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"PAG-DEMO\",\"name\":\"Pagador Sintetico\",\"taxId\":\"900000000-1\",\"active\":true}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/payers`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"PAG-DEMO\",\"name\":\"Pagador Sintetico\",\"taxId\":\"900000000-1\",\"active\":true}) });" } ] } }, "/admin/configuration/payers/{id}": { "delete": { "description": "Elimina pagador solo cuando la version coincide y no existen referencias protegidas; los reintentos con igual clave devuelven la confirmacion original de forma segura.", "operationId": "deletePayer", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } }, { "description": "Version observada antes de eliminar el recurso existente.", "in": "query", "name": "expectedVersion", "required": true, "schema": { "$ref": "#/components/schemas/ExpectedVersion" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "deleted": true, "id": "b2000006-0000-4000-8000-000000000001", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/DeletionResult" } } }, "description": "Confirmacion tipada de eliminacion.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Eliminar pagador", "tags": [ "Configuracion - Pagadores" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/payers/{id}?expectedVersion=1\" --request DELETE --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/payers/{id}?expectedVersion=1`, { method: 'DELETE', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' } });" } ] }, "get": { "description": "Obtiene la proyeccion detallada y cerrada de pagador visible para el alcance autenticado; un identificador ajeno se trata como no encontrado y no revela existencia.", "operationId": "getPayer", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "PAG-DEMO", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000006-0000-4000-8000-000000000001", "name": "Pagador Sintetico", "taxId": "900000000-1", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/PayerDetail" } } }, "description": "Detalle tipado de pagador.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Consultar pagador", "tags": [ "Configuracion - Pagadores" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/payers/{id}\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/payers/{id}`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "patch": { "description": "Actualiza solamente atributos administrables de pagador, exige la version observada y una clave idempotente, y rechaza referencias externas al organization o company autorizado.", "operationId": "updatePayer", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "PAG-DEMO", "expectedVersion": 1, "name": "Pagador Sintetico", "taxId": "900000000-1" } } }, "schema": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" }, "taxId": { "default": "", "maxLength": 30, "minLength": 5, "type": "string" } }, "required": [ "expectedVersion" ], "type": "object" } } }, "description": "Cambios parciales cerrados y expectedVersion vigente.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "PAG-DEMO", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000006-0000-4000-8000-000000000001", "name": "Pagador Sintetico", "taxId": "900000000-1", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 2 } } }, "schema": { "$ref": "#/components/schemas/PayerDetail" } } }, "description": "Payer actualizado o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Actualizar pagador", "tags": [ "Configuracion - Pagadores" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/payers/{id}\" --request PATCH --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"PAG-DEMO\",\"name\":\"Pagador Sintetico\",\"taxId\":\"900000000-1\",\"active\":true,\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/payers/{id}`, { method: 'PATCH', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"PAG-DEMO\",\"name\":\"Pagador Sintetico\",\"taxId\":\"900000000-1\",\"active\":true,\"expectedVersion\":1}) });" } ] } }, "/admin/configuration/practitioners": { "get": { "description": "Lista profesionales del organization y company derivados del token, con busqueda, filtros permitidos, orden estable y paginacion acotada; nunca expone metadata interna ni datos de otros tenants.", "operationId": "listPractitioners", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Busqueda textual allowlisted sobre codigo y nombre.", "in": "query", "name": "search", "required": false, "schema": { "default": "", "maxLength": 100, "minLength": 1, "type": "string" } }, { "description": "Filtra por estado administrable del recurso.", "in": "query", "name": "active", "required": false, "schema": { "default": "", "type": "boolean" } }, { "description": "Orden estable permitido para catalogos.", "in": "query", "name": "sort", "required": false, "schema": { "default": "code", "enum": [ "code", "name", "-code", "-name" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "items": [ { "active": true, "code": "PROF-001", "createdAt": "2026-07-26T14:00:00-05:00", "email": "profesional@example.invalid", "fullName": "Profesional Sintetico", "id": "b2000001-0000-4000-8000-000000000001", "locationIds": [ "b1000000-0000-4000-8000-000000000001" ], "phone": "3000000000", "specialtyIds": [ "b1000000-0000-4000-8000-000000000002" ], "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } ], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/PractitionerPage" } } }, "description": "Pagina tipada de profesionales visibles.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Listar profesionales", "tags": [ "Configuracion - Profesionales" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/practitioners?limit=25\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/practitioners?limit=25`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "post": { "description": "Crea profesional mediante un DTO nominal cerrado, valida referencias dentro del alcance firmado y conserva el resultado para reintentos idempotentes sin publicar metadata generica.", "operationId": "createPractitioner", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "PROF-001", "email": "profesional@example.invalid", "fullName": "Profesional Sintetico", "locationIds": [ "b1000000-0000-4000-8000-000000000001" ], "phone": "3000000000", "specialtyIds": [ "b1000000-0000-4000-8000-000000000002" ] } } }, "schema": { "additionalProperties": false, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "email": { "default": "", "format": "email", "maxLength": 254, "type": "string" }, "fullName": { "default": "", "maxLength": 160, "minLength": 3, "type": "string" }, "locationIds": { "items": { "$ref": "#/components/schemas/Uuid" }, "maxItems": 1, "minItems": 1, "type": "array", "uniqueItems": true }, "phone": { "default": "", "maxLength": 30, "minLength": 7, "type": "string" }, "specialtyIds": { "items": { "$ref": "#/components/schemas/Uuid" }, "maxItems": 1, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "code", "fullName", "email", "locationIds", "specialtyIds", "active" ], "type": "object" } } }, "description": "Atributos administrables y sinteticos de profesional.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "PROF-001", "createdAt": "2026-07-26T14:00:00-05:00", "email": "profesional@example.invalid", "fullName": "Profesional Sintetico", "id": "b2000001-0000-4000-8000-000000000001", "locationIds": [ "b1000000-0000-4000-8000-000000000001" ], "phone": "3000000000", "specialtyIds": [ "b1000000-0000-4000-8000-000000000002" ], "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/PractitionerDetail" } } }, "description": "Practitioner creado con version inicial o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Crear profesional", "tags": [ "Configuracion - Profesionales" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/practitioners\" --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"PROF-001\",\"fullName\":\"Profesional Sintetico\",\"email\":\"profesional@example.invalid\",\"phone\":\"3000000000\",\"locationIds\":[\"b1000000-0000-4000-8000-000000000001\"],\"specialtyIds\":[\"b1000000-0000-4000-8000-000000000002\"],\"active\":true}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/practitioners`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"PROF-001\",\"fullName\":\"Profesional Sintetico\",\"email\":\"profesional@example.invalid\",\"phone\":\"3000000000\",\"locationIds\":[\"b1000000-0000-4000-8000-000000000001\"],\"specialtyIds\":[\"b1000000-0000-4000-8000-000000000002\"],\"active\":true}) });" } ] } }, "/admin/configuration/practitioners/{id}": { "delete": { "description": "Elimina profesional solo cuando la version coincide y no existen referencias protegidas; los reintentos con igual clave devuelven la confirmacion original de forma segura.", "operationId": "deletePractitioner", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } }, { "description": "Version observada antes de eliminar el recurso existente.", "in": "query", "name": "expectedVersion", "required": true, "schema": { "$ref": "#/components/schemas/ExpectedVersion" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "deleted": true, "id": "b2000001-0000-4000-8000-000000000001", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/DeletionResult" } } }, "description": "Confirmacion tipada de eliminacion.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Eliminar profesional", "tags": [ "Configuracion - Profesionales" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/practitioners/{id}?expectedVersion=1\" --request DELETE --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/practitioners/{id}?expectedVersion=1`, { method: 'DELETE', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' } });" } ] }, "get": { "description": "Obtiene la proyeccion detallada y cerrada de profesional visible para el alcance autenticado; un identificador ajeno se trata como no encontrado y no revela existencia.", "operationId": "getPractitioner", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "PROF-001", "createdAt": "2026-07-26T14:00:00-05:00", "email": "profesional@example.invalid", "fullName": "Profesional Sintetico", "id": "b2000001-0000-4000-8000-000000000001", "locationIds": [ "b1000000-0000-4000-8000-000000000001" ], "phone": "3000000000", "specialtyIds": [ "b1000000-0000-4000-8000-000000000002" ], "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/PractitionerDetail" } } }, "description": "Detalle tipado de profesional.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Consultar profesional", "tags": [ "Configuracion - Profesionales" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/practitioners/{id}\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/practitioners/{id}`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "patch": { "description": "Actualiza solamente atributos administrables de profesional, exige la version observada y una clave idempotente, y rechaza referencias externas al organization o company autorizado.", "operationId": "updatePractitioner", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "PROF-001", "email": "profesional@example.invalid", "expectedVersion": 1, "fullName": "Profesional Sintetico", "locationIds": [ "b1000000-0000-4000-8000-000000000001" ], "phone": "3000000000", "specialtyIds": [ "b1000000-0000-4000-8000-000000000002" ] } } }, "schema": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "email": { "default": "", "format": "email", "maxLength": 254, "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "fullName": { "default": "", "maxLength": 160, "minLength": 3, "type": "string" }, "locationIds": { "items": { "$ref": "#/components/schemas/Uuid" }, "maxItems": 1, "minItems": 1, "type": "array", "uniqueItems": true }, "phone": { "default": "", "maxLength": 30, "minLength": 7, "type": "string" }, "specialtyIds": { "items": { "$ref": "#/components/schemas/Uuid" }, "maxItems": 1, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "expectedVersion" ], "type": "object" } } }, "description": "Cambios parciales cerrados y expectedVersion vigente.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "PROF-001", "createdAt": "2026-07-26T14:00:00-05:00", "email": "profesional@example.invalid", "fullName": "Profesional Sintetico", "id": "b2000001-0000-4000-8000-000000000001", "locationIds": [ "b1000000-0000-4000-8000-000000000001" ], "phone": "3000000000", "specialtyIds": [ "b1000000-0000-4000-8000-000000000002" ], "updatedAt": "2026-07-26T14:00:00-05:00", "version": 2 } } }, "schema": { "$ref": "#/components/schemas/PractitionerDetail" } } }, "description": "Practitioner actualizado o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Actualizar profesional", "tags": [ "Configuracion - Profesionales" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/practitioners/{id}\" --request PATCH --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"PROF-001\",\"fullName\":\"Profesional Sintetico\",\"email\":\"profesional@example.invalid\",\"phone\":\"3000000000\",\"locationIds\":[\"b1000000-0000-4000-8000-000000000001\"],\"specialtyIds\":[\"b1000000-0000-4000-8000-000000000002\"],\"active\":true,\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/practitioners/{id}`, { method: 'PATCH', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"PROF-001\",\"fullName\":\"Profesional Sintetico\",\"email\":\"profesional@example.invalid\",\"phone\":\"3000000000\",\"locationIds\":[\"b1000000-0000-4000-8000-000000000001\"],\"specialtyIds\":[\"b1000000-0000-4000-8000-000000000002\"],\"active\":true,\"expectedVersion\":1}) });" } ] } }, "/admin/configuration/request-sources": { "get": { "description": "Lista fuentes de solicitud del organization y company derivados del token, con busqueda, filtros permitidos, orden estable y paginacion acotada; nunca expone metadata interna ni datos de otros tenants.", "operationId": "listRequestSources", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Busqueda textual allowlisted sobre codigo y nombre.", "in": "query", "name": "search", "required": false, "schema": { "default": "", "maxLength": 100, "minLength": 1, "type": "string" } }, { "description": "Filtra por estado administrable del recurso.", "in": "query", "name": "active", "required": false, "schema": { "default": "", "type": "boolean" } }, { "description": "Orden estable permitido para catalogos.", "in": "query", "name": "sort", "required": false, "schema": { "default": "code", "enum": [ "code", "name", "-code", "-name" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "items": [ { "active": true, "channel": "WEB", "code": "WEB-DEMO", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000008-0000-4000-8000-000000000001", "name": "Portal sintetico", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } ], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/RequestSourcePage" } } }, "description": "Pagina tipada de fuentes de solicitud visibles.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Listar fuentes de solicitud", "tags": [ "Configuracion - Fuentes de solicitud" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/request-sources?limit=25\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/request-sources?limit=25`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "post": { "description": "Crea fuente de solicitud mediante un DTO nominal cerrado, valida referencias dentro del alcance firmado y conserva el resultado para reintentos idempotentes sin publicar metadata generica.", "operationId": "createRequestSource", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "channel": "WEB", "code": "WEB-DEMO", "name": "Portal sintetico" } } }, "schema": { "additionalProperties": false, "properties": { "active": { "default": "", "type": "boolean" }, "channel": { "default": "", "enum": [ "PHONE", "WEB", "IN_PERSON", "PARTNER" ], "type": "string" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "code", "name", "channel", "active" ], "type": "object" } } }, "description": "Atributos administrables y sinteticos de fuente de solicitud.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "channel": "WEB", "code": "WEB-DEMO", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000008-0000-4000-8000-000000000001", "name": "Portal sintetico", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/RequestSourceDetail" } } }, "description": "RequestSource creado con version inicial o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Crear fuente de solicitud", "tags": [ "Configuracion - Fuentes de solicitud" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/request-sources\" --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"WEB-DEMO\",\"name\":\"Portal sintetico\",\"channel\":\"WEB\",\"active\":true}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/request-sources`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"WEB-DEMO\",\"name\":\"Portal sintetico\",\"channel\":\"WEB\",\"active\":true}) });" } ] } }, "/admin/configuration/request-sources/{id}": { "delete": { "description": "Elimina fuente de solicitud solo cuando la version coincide y no existen referencias protegidas; los reintentos con igual clave devuelven la confirmacion original de forma segura.", "operationId": "deleteRequestSource", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } }, { "description": "Version observada antes de eliminar el recurso existente.", "in": "query", "name": "expectedVersion", "required": true, "schema": { "$ref": "#/components/schemas/ExpectedVersion" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "deleted": true, "id": "b2000008-0000-4000-8000-000000000001", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/DeletionResult" } } }, "description": "Confirmacion tipada de eliminacion.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Eliminar fuente de solicitud", "tags": [ "Configuracion - Fuentes de solicitud" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/request-sources/{id}?expectedVersion=1\" --request DELETE --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/request-sources/{id}?expectedVersion=1`, { method: 'DELETE', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' } });" } ] }, "get": { "description": "Obtiene la proyeccion detallada y cerrada de fuente de solicitud visible para el alcance autenticado; un identificador ajeno se trata como no encontrado y no revela existencia.", "operationId": "getRequestSource", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "channel": "WEB", "code": "WEB-DEMO", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000008-0000-4000-8000-000000000001", "name": "Portal sintetico", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/RequestSourceDetail" } } }, "description": "Detalle tipado de fuente de solicitud.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Consultar fuente de solicitud", "tags": [ "Configuracion - Fuentes de solicitud" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/request-sources/{id}\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/request-sources/{id}`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "patch": { "description": "Actualiza solamente atributos administrables de fuente de solicitud, exige la version observada y una clave idempotente, y rechaza referencias externas al organization o company autorizado.", "operationId": "updateRequestSource", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "channel": "WEB", "code": "WEB-DEMO", "expectedVersion": 1, "name": "Portal sintetico" } } }, "schema": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "default": "", "type": "boolean" }, "channel": { "default": "", "enum": [ "PHONE", "WEB", "IN_PERSON", "PARTNER" ], "type": "string" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "expectedVersion" ], "type": "object" } } }, "description": "Cambios parciales cerrados y expectedVersion vigente.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "channel": "WEB", "code": "WEB-DEMO", "createdAt": "2026-07-26T14:00:00-05:00", "id": "b2000008-0000-4000-8000-000000000001", "name": "Portal sintetico", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 2 } } }, "schema": { "$ref": "#/components/schemas/RequestSourceDetail" } } }, "description": "RequestSource actualizado o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Actualizar fuente de solicitud", "tags": [ "Configuracion - Fuentes de solicitud" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/request-sources/{id}\" --request PATCH --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"WEB-DEMO\",\"name\":\"Portal sintetico\",\"channel\":\"WEB\",\"active\":true,\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/request-sources/{id}`, { method: 'PATCH', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"WEB-DEMO\",\"name\":\"Portal sintetico\",\"channel\":\"WEB\",\"active\":true,\"expectedVersion\":1}) });" } ] } }, "/admin/configuration/scheduling/blocks": { "get": { "description": "Lista bloqueos tenant-scoped por rango temporal con referencias explicitas a sede, programa o profesional, sin simular ausencias, horas extra, holds ni overrides.", "operationId": "listSchedulingBlocks", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "items": [], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/SchedulingBlockPage" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:read" ] } ], "summary": "[Preview] Listar bloqueos de agenda", "tags": [ "Scheduling - Bloqueos" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/blocks\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/blocks`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "post": { "description": "Crea un bloqueo con sede, rango ISO con offset, razon y al menos programa o profesional; valida referencias y orden temporal antes del efecto idempotente.", "operationId": "createSchedulingBlock", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "endsAt": "2026-08-03T13:00:00-05:00", "locationId": "b1000000-0000-4000-8000-000000000001", "programId": "c1000000-0000-4000-8000-000000000001", "reason": "Mantenimiento sintetico", "startsAt": "2026-08-03T12:00:00-05:00" } } }, "schema": { "additionalProperties": false, "anyOf": [ { "required": [ "programId" ] }, { "required": [ "practitionerId" ] } ], "properties": { "active": { "type": "boolean" }, "endsAt": { "format": "date-time", "type": "string" }, "locationId": { "$ref": "#/components/schemas/Uuid" }, "practitionerId": { "$ref": "#/components/schemas/Uuid" }, "programId": { "$ref": "#/components/schemas/Uuid" }, "reason": { "maxLength": 500, "minLength": 3, "type": "string" }, "startsAt": { "format": "date-time", "type": "string" } }, "required": [ "locationId", "startsAt", "endsAt", "reason", "active" ], "type": "object" } } }, "description": "DTO cerrado con valores sinteticos y precondicion cuando aplica.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "endsAt": "2026-08-03T13:00:00-05:00", "id": "c4000000-0000-4000-8000-000000000001", "locationId": "b1000000-0000-4000-8000-000000000001", "programId": "c1000000-0000-4000-8000-000000000001", "reason": "Mantenimiento sintetico", "startsAt": "2026-08-03T12:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/SchedulingBlockDetail" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:write" ] } ], "summary": "[Preview] Crear bloqueo de agenda", "tags": [ "Scheduling - Bloqueos" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/blocks\" --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"programId\":\"c1000000-0000-4000-8000-000000000001\",\"locationId\":\"b1000000-0000-4000-8000-000000000001\",\"startsAt\":\"2026-08-03T12:00:00-05:00\",\"endsAt\":\"2026-08-03T13:00:00-05:00\",\"reason\":\"Mantenimiento sintetico\",\"active\":true}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/blocks`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"programId\":\"c1000000-0000-4000-8000-000000000001\",\"locationId\":\"b1000000-0000-4000-8000-000000000001\",\"startsAt\":\"2026-08-03T12:00:00-05:00\",\"endsAt\":\"2026-08-03T13:00:00-05:00\",\"reason\":\"Mantenimiento sintetico\",\"active\":true}) });" } ] } }, "/admin/configuration/scheduling/blocks/{blockId}": { "patch": { "description": "Actualiza el bloqueo mediante un DTO cerrado y expectedVersion, valida rango y referencias del mismo alcance y evita sobrescrituras concurrentes o efectos duplicados.", "operationId": "updateSchedulingBlock", "parameters": [ { "description": "UUID del bloqueo dentro del alcance autenticado.", "in": "path", "name": "blockId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "endsAt": "2026-08-03T14:00:00-05:00", "expectedVersion": 1 } } }, "schema": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "default": "", "type": "boolean" }, "endsAt": { "default": "", "format": "date-time", "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "locationId": { "$ref": "#/components/schemas/Uuid" }, "practitionerId": { "$ref": "#/components/schemas/Uuid" }, "programId": { "$ref": "#/components/schemas/Uuid" }, "reason": { "default": "", "maxLength": 500, "minLength": 3, "type": "string" }, "startsAt": { "default": "", "format": "date-time", "type": "string" } }, "required": [ "expectedVersion" ], "type": "object" } } }, "description": "DTO cerrado con valores sinteticos y precondicion cuando aplica.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "endsAt": "2026-08-03T14:00:00-05:00", "id": "c4000000-0000-4000-8000-000000000001", "locationId": "b1000000-0000-4000-8000-000000000001", "programId": "c1000000-0000-4000-8000-000000000001", "reason": "Mantenimiento sintetico", "startsAt": "2026-08-03T12:00:00-05:00", "version": 2 } } }, "schema": { "$ref": "#/components/schemas/SchedulingBlockDetail" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:write" ] } ], "summary": "[Preview] Actualizar bloqueo de agenda", "tags": [ "Scheduling - Bloqueos" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/blocks/c4000000-0000-4000-8000-000000000001\" --request PATCH --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"endsAt\":\"2026-08-03T14:00:00-05:00\",\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/blocks/c4000000-0000-4000-8000-000000000001`, { method: 'PATCH', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"endsAt\":\"2026-08-03T14:00:00-05:00\",\"expectedVersion\":1}) });" } ] } }, "/admin/configuration/scheduling/holidays": { "get": { "description": "Lista festivos configurados por fecha operativa de Colombia con paginacion acotada y proyecciones cerradas, sin datos de auditoria, tenancy ni metadata interna.", "operationId": "listSchedulingHolidays", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "items": [ { "active": true, "date": "2026-08-17", "id": "c3000000-0000-4000-8000-000000000001", "name": "Festivo sintetico", "version": 1 } ], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/SchedulingHolidayPage" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:read" ] } ], "summary": "[Preview] Listar festivos de agenda", "tags": [ "Scheduling - Festivos" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/holidays\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/holidays`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "post": { "description": "Crea un festivo tenant-scoped usando fecha local America/Bogota, nombre y estado tipados; valida unicidad y conserva el resultado para reintentos idempotentes.", "operationId": "createSchedulingHoliday", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "date": "2026-08-17", "name": "Festivo sintetico" } } }, "schema": { "additionalProperties": false, "properties": { "active": { "default": "", "type": "boolean" }, "date": { "default": "", "format": "date", "type": "string" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "date", "name", "active" ], "type": "object" } } }, "description": "DTO cerrado con valores sinteticos y precondicion cuando aplica.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "date": "2026-08-17", "id": "c3000000-0000-4000-8000-000000000001", "name": "Festivo sintetico", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/SchedulingHolidayDetail" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:write" ] } ], "summary": "[Preview] Crear festivo de agenda", "tags": [ "Scheduling - Festivos" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/holidays\" --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"date\":\"2026-08-17\",\"name\":\"Festivo sintetico\",\"active\":true}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/holidays`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"date\":\"2026-08-17\",\"name\":\"Festivo sintetico\",\"active\":true}) });" } ] } }, "/admin/configuration/scheduling/holidays/{holidayId}": { "delete": { "description": "Elimina el festivo si expectedVersion coincide y las referencias permiten la operacion; el replay idempotente devuelve la confirmacion inicial sin convertirla en 404.", "operationId": "deleteSchedulingHoliday", "parameters": [ { "description": "UUID del festivo dentro del alcance autenticado.", "in": "path", "name": "holidayId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } }, { "description": "Version observada antes de eliminar el recurso existente.", "in": "query", "name": "expectedVersion", "required": true, "schema": { "$ref": "#/components/schemas/ExpectedVersion" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "deleted": true, "id": "c3000000-0000-4000-8000-000000000001", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/DeletionResult" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:write" ] } ], "summary": "[Preview] Eliminar festivo de agenda", "tags": [ "Scheduling - Festivos" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/holidays/c3000000-0000-4000-8000-000000000001?expectedVersion=1\" --request DELETE --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/holidays/c3000000-0000-4000-8000-000000000001?expectedVersion=1`, { method: 'DELETE', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' } });" } ] }, "patch": { "description": "Actualiza atributos cerrados del festivo con expectedVersion e idempotencia, y protege las referencias de reglas y excepciones antes de confirmar cualquier cambio.", "operationId": "updateSchedulingHoliday", "parameters": [ { "description": "UUID del festivo dentro del alcance autenticado.", "in": "path", "name": "holidayId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "expectedVersion": 1, "name": "Festivo sintetico actualizado" } } }, "schema": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "default": "", "type": "boolean" }, "date": { "default": "", "format": "date", "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "expectedVersion" ], "type": "object" } } }, "description": "DTO cerrado con valores sinteticos y precondicion cuando aplica.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "date": "2026-08-17", "id": "c3000000-0000-4000-8000-000000000001", "name": "Festivo sintetico actualizado", "version": 2 } } }, "schema": { "$ref": "#/components/schemas/SchedulingHolidayDetail" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:write" ] } ], "summary": "[Preview] Actualizar festivo de agenda", "tags": [ "Scheduling - Festivos" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/holidays/c3000000-0000-4000-8000-000000000001\" --request PATCH --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"name\":\"Festivo sintetico actualizado\",\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/holidays/c3000000-0000-4000-8000-000000000001`, { method: 'PATCH', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"name\":\"Festivo sintetico actualizado\",\"expectedVersion\":1}) });" } ] } }, "/admin/configuration/scheduling/practitioners/{practitionerId}/appointment-types": { "get": { "description": "Consulta la relacion cerrada entre un profesional y sus tipos de cita dentro del alcance autenticado, incluyendo la version requerida para un reemplazo atomico posterior.", "operationId": "getSchedulingPractitionerAppointmentTypes", "parameters": [ { "description": "UUID del profesional dentro del alcance autenticado.", "in": "path", "name": "practitionerId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "appointmentTypeIds": [ "b1000000-0000-4000-8000-000000000011" ], "practitionerId": "b1000000-0000-4000-8000-000000000010", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/PractitionerAppointmentTypeConfiguration" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:read" ] } ], "summary": "[Preview] Consultar tipos de cita del profesional", "tags": [ "Scheduling - Relaciones" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/practitioners/b1000000-0000-4000-8000-000000000010/appointment-types\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/practitioners/b1000000-0000-4000-8000-000000000010/appointment-types`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "put": { "description": "Reemplaza atomicamente los tipos de cita habilitados para el profesional, valida identificadores unicos tenant-scoped y exige expectedVersion e idempotencia.", "operationId": "replaceSchedulingPractitionerAppointmentTypes", "parameters": [ { "description": "UUID del profesional dentro del alcance autenticado.", "in": "path", "name": "practitionerId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "appointmentTypeIds": [ "b1000000-0000-4000-8000-000000000011" ], "expectedVersion": 1 } } }, "schema": { "additionalProperties": false, "properties": { "appointmentTypeIds": { "items": { "$ref": "#/components/schemas/Uuid" }, "maxItems": 2, "type": "array", "uniqueItems": true }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" } }, "required": [ "appointmentTypeIds", "expectedVersion" ], "type": "object" } } }, "description": "DTO cerrado con valores sinteticos y precondicion cuando aplica.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "appointmentTypeIds": [ "b1000000-0000-4000-8000-000000000011" ], "practitionerId": "b1000000-0000-4000-8000-000000000010", "version": 2 } } }, "schema": { "$ref": "#/components/schemas/PractitionerAppointmentTypeConfiguration" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:write" ] } ], "summary": "[Preview] Reemplazar tipos de cita del profesional", "tags": [ "Scheduling - Relaciones" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/practitioners/b1000000-0000-4000-8000-000000000010/appointment-types\" --request PUT --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"appointmentTypeIds\":[\"b1000000-0000-4000-8000-000000000011\"],\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/practitioners/b1000000-0000-4000-8000-000000000010/appointment-types`, { method: 'PUT', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"appointmentTypeIds\":[\"b1000000-0000-4000-8000-000000000011\"],\"expectedVersion\":1}) });" } ] } }, "/admin/configuration/scheduling/programs": { "get": { "description": "Lista programas de agenda del alcance firmado mediante filtros cerrados y paginacion acotada, sin incluir reglas, slots, dashboards ni agregados destinados al portal web.", "operationId": "listSchedulingPrograms", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "items": [ { "active": true, "code": "PROG-DEMO", "emergency": false, "id": "c1000000-0000-4000-8000-000000000001", "locationId": "b1000000-0000-4000-8000-000000000001", "name": "Programa sintetico", "version": 1 } ], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/SchedulingProgramPage" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:read" ] } ], "summary": "[Preview] Listar programas de agenda", "tags": [ "Scheduling - Programas" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/programs\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/programs`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "post": { "description": "Crea un programa con location del mismo alcance, atributos cerrados y version inicial; la clave idempotente conserva el primer resultado confirmado sin repetir efectos.", "operationId": "createSchedulingProgram", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "PROG-DEMO", "emergency": false, "locationId": "b1000000-0000-4000-8000-000000000001", "name": "Programa sintetico" } } }, "schema": { "additionalProperties": false, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "emergency": { "default": "", "type": "boolean" }, "locationId": { "$ref": "#/components/schemas/Uuid" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "code", "name", "locationId", "emergency", "active" ], "type": "object" } } }, "description": "DTO cerrado con valores sinteticos y precondicion cuando aplica.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "PROG-DEMO", "emergency": false, "id": "c1000000-0000-4000-8000-000000000001", "locationId": "b1000000-0000-4000-8000-000000000001", "name": "Programa sintetico", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/SchedulingProgramDetail" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:write" ] } ], "summary": "[Preview] Crear programa de agenda", "tags": [ "Scheduling - Programas" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/programs\" --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"PROG-DEMO\",\"name\":\"Programa sintetico\",\"locationId\":\"b1000000-0000-4000-8000-000000000001\",\"emergency\":false,\"active\":true}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/programs`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"PROG-DEMO\",\"name\":\"Programa sintetico\",\"locationId\":\"b1000000-0000-4000-8000-000000000001\",\"emergency\":false,\"active\":true}) });" } ] } }, "/admin/configuration/scheduling/programs/{programId}": { "delete": { "description": "Elimina el programa solamente si expectedVersion coincide y no tiene rules, slots, appointments o blocks protegidos; un replay valido retorna la confirmacion original.", "operationId": "deleteSchedulingProgram", "parameters": [ { "description": "UUID del programa dentro del alcance autenticado.", "in": "path", "name": "programId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } }, { "description": "Version observada antes de eliminar el recurso existente.", "in": "query", "name": "expectedVersion", "required": true, "schema": { "$ref": "#/components/schemas/ExpectedVersion" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "deleted": true, "id": "c1000000-0000-4000-8000-000000000001", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/DeletionResult" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:write" ] } ], "summary": "[Preview] Eliminar programa de agenda", "tags": [ "Scheduling - Programas" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/programs/c1000000-0000-4000-8000-000000000001?expectedVersion=1\" --request DELETE --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/programs/c1000000-0000-4000-8000-000000000001?expectedVersion=1`, { method: 'DELETE', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' } });" } ] }, "patch": { "description": "Actualiza campos administrables del programa con expectedVersion, referencias tenant-scoped e idempotencia obligatoria; una version obsoleta no sobrescribe cambios posteriores.", "operationId": "updateSchedulingProgram", "parameters": [ { "description": "UUID del programa dentro del alcance autenticado.", "in": "path", "name": "programId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "expectedVersion": 1, "name": "Programa sintetico actualizado" } } }, "schema": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "emergency": { "default": "", "type": "boolean" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "locationId": { "$ref": "#/components/schemas/Uuid" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "expectedVersion" ], "type": "object" } } }, "description": "DTO cerrado con valores sinteticos y precondicion cuando aplica.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "PROG-DEMO", "emergency": false, "id": "c1000000-0000-4000-8000-000000000001", "locationId": "b1000000-0000-4000-8000-000000000001", "name": "Programa sintetico actualizado", "version": 2 } } }, "schema": { "$ref": "#/components/schemas/SchedulingProgramDetail" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:write" ] } ], "summary": "[Preview] Actualizar programa de agenda", "tags": [ "Scheduling - Programas" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/programs/c1000000-0000-4000-8000-000000000001\" --request PATCH --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"name\":\"Programa sintetico actualizado\",\"active\":true,\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/programs/c1000000-0000-4000-8000-000000000001`, { method: 'PATCH', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"name\":\"Programa sintetico actualizado\",\"active\":true,\"expectedVersion\":1}) });" } ] } }, "/admin/configuration/scheduling/programs/{programId}/practitioners": { "put": { "description": "Reemplaza atomicamente el conjunto completo de profesionales del programa, valida UUID unicos del mismo alcance y protege agenda materializada mediante expectedVersion.", "operationId": "replaceSchedulingProgramPractitioners", "parameters": [ { "description": "UUID del programa dentro del alcance autenticado.", "in": "path", "name": "programId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "expectedVersion": 1, "practitionerIds": [ "b1000000-0000-4000-8000-000000000010" ] } } }, "schema": { "additionalProperties": false, "properties": { "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "practitionerIds": { "items": { "$ref": "#/components/schemas/Uuid" }, "maxItems": 2, "type": "array", "uniqueItems": true } }, "required": [ "practitionerIds", "expectedVersion" ], "type": "object" } } }, "description": "DTO cerrado con valores sinteticos y precondicion cuando aplica.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "practitionerIds": [ "b1000000-0000-4000-8000-000000000010" ], "programId": "c1000000-0000-4000-8000-000000000001", "version": 2 } } }, "schema": { "$ref": "#/components/schemas/ProgramPractitionerAssignment" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:write" ] } ], "summary": "[Preview] Reemplazar profesionales del programa", "tags": [ "Scheduling - Relaciones" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/programs/c1000000-0000-4000-8000-000000000001/practitioners\" --request PUT --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"practitionerIds\":[\"b1000000-0000-4000-8000-000000000010\"],\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/programs/c1000000-0000-4000-8000-000000000001/practitioners`, { method: 'PUT', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"practitionerIds\":[\"b1000000-0000-4000-8000-000000000010\"],\"expectedVersion\":1}) });" } ] } }, "/admin/configuration/scheduling/programs/{programId}/rules": { "get": { "description": "Lista reglas cerradas del programa autenticado con fechas y horas locales de Colombia, recurrencia y capacidad tipadas, sin materializar ni incluir slots en la respuesta.", "operationId": "listSchedulingProgramRules", "parameters": [ { "description": "UUID del programa dentro del alcance autenticado.", "in": "path", "name": "programId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "items": [], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/SchedulingRulePage" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:read" ] } ], "summary": "[Preview] Listar reglas del programa", "tags": [ "Scheduling - Reglas" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/programs/c1000000-0000-4000-8000-000000000001/rules\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/programs/c1000000-0000-4000-8000-000000000001/rules`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "post": { "description": "Crea una regla de agenda con vigencia, horas locales, weekdays, recurrencia, capacidad y politica de festivos cerradas; valida superposiciones antes de confirmar.", "operationId": "createSchedulingProgramRule", "parameters": [ { "description": "UUID del programa dentro del alcance autenticado.", "in": "path", "name": "programId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "dailyCapacity": 8, "endsAtLocal": "12:00:00", "holidayPolicy": "SKIP", "recurrence": "WEEKLY", "slotDurationMinutes": 30, "startsAtLocal": "08:00:00", "validFrom": "2026-08-01", "validTo": "2026-12-31", "weekdays": [ 1, 2, 3, 4, 5 ] } } }, "schema": { "additionalProperties": false, "properties": { "active": { "default": "", "type": "boolean" }, "dailyCapacity": { "default": "", "maximum": 1000, "minimum": 1, "type": "integer" }, "endsAtLocal": { "default": "", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$", "type": "string" }, "holidayDates": { "items": { "default": "", "format": "date", "type": "string" }, "maxItems": 2, "type": "array", "uniqueItems": true }, "holidayPolicy": { "default": "", "enum": [ "SKIP", "INCLUDE", "ONLY_EXCEPTIONS" ], "type": "string" }, "recurrence": { "default": "", "enum": [ "WEEKLY" ], "type": "string" }, "slotDurationMinutes": { "default": "", "maximum": 480, "minimum": 5, "type": "integer" }, "startsAtLocal": { "default": "", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$", "type": "string" }, "validFrom": { "default": "", "format": "date", "type": "string" }, "validTo": { "default": "", "format": "date", "type": "string" }, "weekdays": { "items": { "default": "", "maximum": 7, "minimum": 1, "type": "integer" }, "maxItems": 1, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "validFrom", "validTo", "startsAtLocal", "endsAtLocal", "slotDurationMinutes", "dailyCapacity", "weekdays", "recurrence", "holidayPolicy", "active" ], "type": "object" } } }, "description": "DTO cerrado con valores sinteticos y precondicion cuando aplica.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "dailyCapacity": 8, "endsAtLocal": "12:00:00", "holidayDates": [], "holidayPolicy": "SKIP", "id": "c2000000-0000-4000-8000-000000000001", "programId": "c1000000-0000-4000-8000-000000000001", "recurrence": "WEEKLY", "slotDurationMinutes": 30, "startsAtLocal": "08:00:00", "validFrom": "2026-08-01", "validTo": "2026-12-31", "version": 1, "weekdays": [ 1, 2, 3, 4, 5 ] } } }, "schema": { "$ref": "#/components/schemas/SchedulingRuleDetail" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:write" ] } ], "summary": "[Preview] Crear regla del programa", "tags": [ "Scheduling - Reglas" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/programs/c1000000-0000-4000-8000-000000000001/rules\" --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"validFrom\":\"2026-08-01\",\"validTo\":\"2026-12-31\",\"startsAtLocal\":\"08:00:00\",\"endsAtLocal\":\"12:00:00\",\"slotDurationMinutes\":30,\"dailyCapacity\":8,\"weekdays\":[1,2,3,4,5],\"recurrence\":\"WEEKLY\",\"holidayPolicy\":\"SKIP\",\"active\":true}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/programs/c1000000-0000-4000-8000-000000000001/rules`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"validFrom\":\"2026-08-01\",\"validTo\":\"2026-12-31\",\"startsAtLocal\":\"08:00:00\",\"endsAtLocal\":\"12:00:00\",\"slotDurationMinutes\":30,\"dailyCapacity\":8,\"weekdays\":[1,2,3,4,5],\"recurrence\":\"WEEKLY\",\"holidayPolicy\":\"SKIP\",\"active\":true}) });" } ] } }, "/admin/configuration/scheduling/programs/{programId}/rules/{ruleId}": { "delete": { "description": "Elimina una regla solo cuando expectedVersion coincide y no existen slots o citas protegidos; la operacion idempotente conserva la confirmacion original para replays.", "operationId": "deleteSchedulingProgramRule", "parameters": [ { "description": "UUID del programa dentro del alcance autenticado.", "in": "path", "name": "programId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID de la regla dentro del alcance autenticado.", "in": "path", "name": "ruleId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } }, { "description": "Version observada antes de eliminar el recurso existente.", "in": "query", "name": "expectedVersion", "required": true, "schema": { "$ref": "#/components/schemas/ExpectedVersion" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "deleted": true, "id": "c2000000-0000-4000-8000-000000000001", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/DeletionResult" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:write" ] } ], "summary": "[Preview] Eliminar regla del programa", "tags": [ "Scheduling - Reglas" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/programs/c1000000-0000-4000-8000-000000000001/rules/c2000000-0000-4000-8000-000000000001?expectedVersion=1\" --request DELETE --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/programs/c1000000-0000-4000-8000-000000000001/rules/c2000000-0000-4000-8000-000000000001?expectedVersion=1`, { method: 'DELETE', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' } });" } ] }, "patch": { "description": "Actualiza parcialmente una regla con expectedVersion e idempotencia, conserva semantica America/Bogota y rechaza superposiciones, rangos o capacidades invalidas.", "operationId": "updateSchedulingProgramRule", "parameters": [ { "description": "UUID del programa dentro del alcance autenticado.", "in": "path", "name": "programId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID de la regla dentro del alcance autenticado.", "in": "path", "name": "ruleId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "dailyCapacity": 10, "expectedVersion": 1 } } }, "schema": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "default": "", "type": "boolean" }, "dailyCapacity": { "default": "", "maximum": 1000, "minimum": 1, "type": "integer" }, "endsAtLocal": { "default": "", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$", "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "holidayDates": { "items": { "default": "", "format": "date", "type": "string" }, "maxItems": 2, "type": "array", "uniqueItems": true }, "holidayPolicy": { "default": "", "enum": [ "SKIP", "INCLUDE", "ONLY_EXCEPTIONS" ], "type": "string" }, "recurrence": { "default": "", "enum": [ "WEEKLY" ], "type": "string" }, "slotDurationMinutes": { "default": "", "maximum": 480, "minimum": 5, "type": "integer" }, "startsAtLocal": { "default": "", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$", "type": "string" }, "validFrom": { "default": "", "format": "date", "type": "string" }, "validTo": { "default": "", "format": "date", "type": "string" }, "weekdays": { "items": { "default": "", "maximum": 7, "minimum": 1, "type": "integer" }, "maxItems": 1, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "expectedVersion" ], "type": "object" } } }, "description": "DTO cerrado con valores sinteticos y precondicion cuando aplica.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "dailyCapacity": 10, "endsAtLocal": "12:00:00", "holidayDates": [], "holidayPolicy": "SKIP", "id": "c2000000-0000-4000-8000-000000000001", "programId": "c1000000-0000-4000-8000-000000000001", "recurrence": "WEEKLY", "slotDurationMinutes": 30, "startsAtLocal": "08:00:00", "validFrom": "2026-08-01", "validTo": "2026-12-31", "version": 2, "weekdays": [ 1, 2, 3, 4, 5 ] } } }, "schema": { "$ref": "#/components/schemas/SchedulingRuleDetail" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:write" ] } ], "summary": "[Preview] Actualizar regla del programa", "tags": [ "Scheduling - Reglas" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/programs/c1000000-0000-4000-8000-000000000001/rules/c2000000-0000-4000-8000-000000000001\" --request PATCH --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"dailyCapacity\":10,\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/programs/c1000000-0000-4000-8000-000000000001/rules/c2000000-0000-4000-8000-000000000001`, { method: 'PATCH', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"dailyCapacity\":10,\"expectedVersion\":1}) });" } ] } }, "/admin/configuration/scheduling/rules/{ruleId}/slot-generation": { "post": { "description": "Genera slots para un horizonte maximo de 92 dias con la version vigente de la regla, respetando profesionales, tipos de cita, festivos, bloqueos y deduplicacion.", "operationId": "generateSchedulingRuleSlots", "parameters": [ { "description": "UUID de la regla dentro del alcance autenticado.", "in": "path", "name": "ruleId", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "expectedVersion": 1, "from": "2026-08-01", "to": "2026-08-31" } } }, "schema": { "additionalProperties": false, "properties": { "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "from": { "default": "", "format": "date", "type": "string" }, "to": { "default": "", "format": "date", "type": "string" } }, "required": [ "from", "to", "expectedVersion" ], "type": "object" } } }, "description": "DTO cerrado con valores sinteticos y precondicion cuando aplica.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "duplicateCount": 4, "from": "2026-08-01", "generatedCount": 120, "ruleId": "c2000000-0000-4000-8000-000000000001", "ruleVersion": 1, "skippedCount": 8, "to": "2026-08-31" } } }, "schema": { "$ref": "#/components/schemas/SlotGenerationResult" } } }, "description": "Resultado tipado de la operacion administrativa.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "scheduling:generate" ] } ], "summary": "[Preview] Generar slots desde una regla", "tags": [ "Scheduling - Generacion de slots" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/scheduling/rules/c2000000-0000-4000-8000-000000000001/slot-generation\" --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"from\":\"2026-08-01\",\"to\":\"2026-08-31\",\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/scheduling/rules/c2000000-0000-4000-8000-000000000001/slot-generation`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"from\":\"2026-08-01\",\"to\":\"2026-08-31\",\"expectedVersion\":1}) });" } ] } }, "/admin/configuration/specialties": { "get": { "description": "Lista especialidades del organization y company derivados del token, con busqueda, filtros permitidos, orden estable y paginacion acotada; nunca expone metadata interna ni datos de otros tenants.", "operationId": "listSpecialties", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Busqueda textual allowlisted sobre codigo y nombre.", "in": "query", "name": "search", "required": false, "schema": { "default": "", "maxLength": 100, "minLength": 1, "type": "string" } }, { "description": "Filtra por estado administrable del recurso.", "in": "query", "name": "active", "required": false, "schema": { "default": "", "type": "boolean" } }, { "description": "Orden estable permitido para catalogos.", "in": "query", "name": "sort", "required": false, "schema": { "default": "code", "enum": [ "code", "name", "-code", "-name" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "items": [ { "active": true, "code": "MED-GEN", "createdAt": "2026-07-26T14:00:00-05:00", "description": "Especialidad de demostracion sin datos reales.", "id": "b2000002-0000-4000-8000-000000000001", "name": "Medicina general sintetica", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } ], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/SpecialtyPage" } } }, "description": "Pagina tipada de especialidades visibles.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Listar especialidades", "tags": [ "Configuracion - Especialidades" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/specialties?limit=25\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/specialties?limit=25`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "post": { "description": "Crea especialidad mediante un DTO nominal cerrado, valida referencias dentro del alcance firmado y conserva el resultado para reintentos idempotentes sin publicar metadata generica.", "operationId": "createSpecialty", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "MED-GEN", "description": "Especialidad de demostracion sin datos reales.", "name": "Medicina general sintetica" } } }, "schema": { "additionalProperties": false, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "description": { "default": "", "maxLength": 500, "type": "string" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "code", "name", "active" ], "type": "object" } } }, "description": "Atributos administrables y sinteticos de especialidad.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "MED-GEN", "createdAt": "2026-07-26T14:00:00-05:00", "description": "Especialidad de demostracion sin datos reales.", "id": "b2000002-0000-4000-8000-000000000001", "name": "Medicina general sintetica", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/SpecialtyDetail" } } }, "description": "Specialty creado con version inicial o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Crear especialidad", "tags": [ "Configuracion - Especialidades" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/specialties\" --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"MED-GEN\",\"name\":\"Medicina general sintetica\",\"description\":\"Especialidad de demostracion sin datos reales.\",\"active\":true}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/specialties`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"MED-GEN\",\"name\":\"Medicina general sintetica\",\"description\":\"Especialidad de demostracion sin datos reales.\",\"active\":true}) });" } ] } }, "/admin/configuration/specialties/{id}": { "delete": { "description": "Elimina especialidad solo cuando la version coincide y no existen referencias protegidas; los reintentos con igual clave devuelven la confirmacion original de forma segura.", "operationId": "deleteSpecialty", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } }, { "description": "Version observada antes de eliminar el recurso existente.", "in": "query", "name": "expectedVersion", "required": true, "schema": { "$ref": "#/components/schemas/ExpectedVersion" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "deleted": true, "id": "b2000002-0000-4000-8000-000000000001", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/DeletionResult" } } }, "description": "Confirmacion tipada de eliminacion.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Eliminar especialidad", "tags": [ "Configuracion - Especialidades" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/specialties/{id}?expectedVersion=1\" --request DELETE --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/specialties/{id}?expectedVersion=1`, { method: 'DELETE', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' } });" } ] }, "get": { "description": "Obtiene la proyeccion detallada y cerrada de especialidad visible para el alcance autenticado; un identificador ajeno se trata como no encontrado y no revela existencia.", "operationId": "getSpecialty", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "MED-GEN", "createdAt": "2026-07-26T14:00:00-05:00", "description": "Especialidad de demostracion sin datos reales.", "id": "b2000002-0000-4000-8000-000000000001", "name": "Medicina general sintetica", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 1 } } }, "schema": { "$ref": "#/components/schemas/SpecialtyDetail" } } }, "description": "Detalle tipado de especialidad.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:read" ] } ], "summary": "[Preview] Consultar especialidad", "tags": [ "Configuracion - Especialidades" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/specialties/{id}\" --request GET --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/specialties/{id}`, { method: 'GET', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "patch": { "description": "Actualiza solamente atributos administrables de especialidad, exige la version observada y una clave idempotente, y rechaza referencias externas al organization o company autorizado.", "operationId": "updateSpecialty", "parameters": [ { "description": "UUID del recurso de catalogo dentro del alcance autenticado.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "MED-GEN", "description": "Especialidad de demostracion sin datos reales.", "expectedVersion": 1, "name": "Medicina general sintetica" } } }, "schema": { "additionalProperties": false, "minProperties": 2, "properties": { "active": { "default": "", "type": "boolean" }, "code": { "default": "", "maxLength": 40, "minLength": 1, "type": "string" }, "description": { "default": "", "maxLength": 500, "type": "string" }, "expectedVersion": { "$ref": "#/components/schemas/ExpectedVersion" }, "name": { "default": "", "maxLength": 160, "minLength": 2, "type": "string" } }, "required": [ "expectedVersion" ], "type": "object" } } }, "description": "Cambios parciales cerrados y expectedVersion vigente.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "active": true, "code": "MED-GEN", "createdAt": "2026-07-26T14:00:00-05:00", "description": "Especialidad de demostracion sin datos reales.", "id": "b2000002-0000-4000-8000-000000000001", "name": "Medicina general sintetica", "updatedAt": "2026-07-26T14:00:00-05:00", "version": 2 } } }, "schema": { "$ref": "#/components/schemas/SpecialtyDetail" } } }, "description": "Specialty actualizado o replay confirmado.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "servicePrincipal": [ "configuration:write" ] } ], "summary": "[Preview] Actualizar especialidad", "tags": [ "Configuracion - Especialidades" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl \"${BASE_URL}/admin/configuration/specialties/{id}\" --request PATCH --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000100' --header 'Content-Type: application/json' --header 'Idempotency-Key: synthetic-operation-0001' --data '{\"code\":\"MED-GEN\",\"name\":\"Medicina general sintetica\",\"description\":\"Especialidad de demostracion sin datos reales.\",\"active\":true,\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/admin/configuration/specialties/{id}`, { method: 'PATCH', headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID(), 'Content-Type': 'application/json', 'Idempotency-Key': 'synthetic-operation-0001' }, body: JSON.stringify({\"code\":\"MED-GEN\",\"name\":\"Medicina general sintetica\",\"description\":\"Especialidad de demostracion sin datos reales.\",\"active\":true,\"expectedVersion\":1}) });" } ] } }, "/appointment-events": { "get": { "description": "Retorna el log append-only del tenant en orden `(occurredAt,id)`. Sin cursor inicia en el primer evento retenido; reutilizar un cursor repite deterministamente la pagina posterior. `nextCursor` representa el ultimo evento entregado y sirve para polling.", "operationId": "listAppointmentEvents", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "booked": { "value": { "hasMore": false, "items": [ { "appointmentId": "60000000-0000-4000-8000-000000000001", "correlationId": "10000000-0000-4000-8000-000000000001", "id": "62000000-0000-4000-8000-000000000001", "newStatus": "PENDING", "occurredAt": "2026-07-27T15:00:00.000Z", "previousStatus": null, "source": "EXTERNAL_API", "type": "APPOINTMENT_BOOKED" } ], "nextCursor": "eyJvY2N1cnJlZEF0IjoiMjAyNi0wNy0yN1QxNTowMDowMC4wMDBaIiwiaWQiOiI2MjAwMDAwMC0wMDAwLTQwMDAtODAwMC0wMDAwMDAwMDAwMDEifQ" } } }, "schema": { "$ref": "#/components/schemas/AppointmentEventPage" } } }, "description": "Pagina cronologica de eventos posteriores al cursor.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "servicePrincipal": [ "appointment-events:read" ] } ], "summary": "Reproducir eventos de citas", "tags": [ "Agenda" ], "x-api-status": "stable", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --get '${BASE_URL}/appointment-events' --header 'Authorization: Bearer ${ACCESS_TOKEN}' --data-urlencode 'limit=50'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/appointment-events?cursor=${encodeURIComponent(cursor)}`, { headers: { Authorization: `Bearer ${accessToken}` } });" } ] } }, "/appointments": { "get": { "description": "Lista citas visibles para el tenant autenticado. Se exige `patientId` para evitar extracciones masivas; el intervalo es semiabierto y maximo de 366 dias.", "operationId": "listAppointments", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Identificador opaco del paciente dentro del tenant autenticado.", "in": "query", "name": "patientId", "required": true, "schema": { "default": "", "example": "20000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Inicio inclusivo del rango.", "in": "query", "name": "from", "required": true, "schema": { "default": "", "example": "2026-08-01T00:00:00-05:00", "format": "date-time", "type": "string" } }, { "description": "Fin exclusivo del rango.", "in": "query", "name": "to", "required": true, "schema": { "default": "", "example": "2026-09-01T00:00:00-05:00", "format": "date-time", "type": "string" } }, { "description": "Estado operativo opcional.", "in": "query", "name": "status", "required": false, "schema": { "$ref": "#/components/schemas/AppointmentStatus" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "items": [ { "confirmationNumber": "0001", "endsAt": "2026-08-03T09:30:00-05:00", "id": "60000000-0000-4000-8000-000000000001", "patientId": "20000000-0000-4000-8000-000000000001", "serviceId": "30000000-0000-4000-8000-000000000003", "startsAt": "2026-08-03T09:00:00-05:00", "status": "PENDING", "version": 1 } ], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/AppointmentPage" } } }, "description": "Pagina ordenada por fecha de inicio ascendente.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "servicePrincipal": [ "appointments:read" ] } ], "summary": "Consultar citas por paciente y rango", "tags": [ "Agenda" ], "x-api-status": "stable", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --get '${BASE_URL}/appointments' --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000007' --data-urlencode 'patientId=20000000-0000-4000-8000-000000000001' --data-urlencode 'from=2026-08-01T00:00:00-05:00' --data-urlencode 'to=2026-09-01T00:00:00-05:00'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const query = new URLSearchParams({ patientId, from, to }); const response = await fetch(`${baseUrl}/appointments?${query}`, { headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] }, "post": { "description": "Consume un `optionToken` vigente y reserva atomicamente la capacidad para el paciente. Revalida tenant, disponibilidad y elegibilidad; una opcion vencida o agotada no crea cita.", "operationId": "createAppointment", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "eligibilityDecisionId": "40000000-0000-4000-8000-000000000001", "optionToken": "opt_preview_synthetic_not_a_real_token", "patientId": "20000000-0000-4000-8000-000000000001", "serviceId": "30000000-0000-4000-8000-000000000003", "visitType": "FIRST_TIME" } } }, "schema": { "additionalProperties": false, "properties": { "eligibilityDecisionId": { "default": "", "format": "uuid", "type": "string" }, "optionToken": { "default": "", "maxLength": 2048, "minLength": 20, "type": "string" }, "patientId": { "default": "", "format": "uuid", "type": "string" }, "serviceId": { "default": "", "format": "uuid", "type": "string" }, "visitType": { "default": "", "enum": [ "FIRST_TIME", "CONTROL" ], "type": "string" } }, "required": [ "patientId", "serviceId", "optionToken", "visitType" ], "type": "object" } } }, "description": "Paciente, opcion opaca y contexto de cobertura de la reserva.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "$ref": "#/components/examples/Appointment" } }, "schema": { "$ref": "#/components/schemas/Appointment" } } }, "description": "Cita reservada o resultado original de un replay valido.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "servicePrincipal": [ "appointments:write" ] } ], "summary": "Reservar una cita", "tags": [ "Agenda" ], "x-api-status": "stable", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl '${BASE_URL}/appointments' --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'Content-Type: application/json' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000008' --header 'Idempotency-Key: appointment-demo-0001' --data '{\"patientId\":\"20000000-0000-4000-8000-000000000001\",\"serviceId\":\"30000000-0000-4000-8000-000000000003\",\"optionToken\":\"opt_preview_synthetic_not_a_real_token\",\"visitType\":\"FIRST_TIME\"}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/appointments`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', 'X-Correlation-Id': crypto.randomUUID(), 'Idempotency-Key': 'appointment-demo-0001' }, body: JSON.stringify(booking) }); const appointment = await response.json();" } ] } }, "/appointments/{appointmentId}": { "get": { "description": "Obtiene el estado y horario vigente de una cita del tenant autenticado. No retorna documento, telefono, notas clinicas ni timeline interno.", "operationId": "getAppointment", "parameters": [ { "description": "Identificador opaco de la cita dentro del tenant autenticado.", "in": "path", "name": "appointmentId", "required": true, "schema": { "default": "", "example": "60000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "$ref": "#/components/examples/Appointment" } }, "schema": { "$ref": "#/components/schemas/Appointment" } } }, "description": "Detalle externo de la cita.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "servicePrincipal": [ "appointments:read" ] } ], "summary": "Consultar el detalle de una cita", "tags": [ "Agenda" ], "x-api-status": "stable", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl '${BASE_URL}/appointments/60000000-0000-4000-8000-000000000001' --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000009'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/appointments/${appointmentId}`, { headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } }); const appointment = await response.json();" } ] } }, "/appointments/{appointmentId}/cancel": { "post": { "description": "Cancela una cita futura segun las reglas del tenant y libera capacidad cuando aplica. `expectedVersion` protege contra cambios concurrentes y el motivo debe pertenecer al catalogo autorizado.", "operationId": "cancelAppointment", "parameters": [ { "description": "Identificador opaco de la cita dentro del tenant autenticado.", "in": "path", "name": "appointmentId", "required": true, "schema": { "default": "", "example": "60000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "comment": "Solicitud recibida por canal institucional", "expectedVersion": 1, "reasonId": "70000000-0000-4000-8000-000000000001" } } }, "schema": { "additionalProperties": false, "properties": { "comment": { "default": "", "maxLength": 500, "minLength": 1, "type": "string" }, "expectedVersion": { "default": "", "minimum": 1, "type": "integer" }, "reasonId": { "default": "", "format": "uuid", "type": "string" } }, "required": [ "reasonId", "expectedVersion" ], "type": "object" } } }, "description": "Motivo catalogado, observacion no clinica opcional y version observada.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "$ref": "#/components/examples/AppointmentCancelled" } }, "schema": { "$ref": "#/components/schemas/Appointment" } } }, "description": "Cita cancelada o replay valido.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "servicePrincipal": [ "appointments:write" ] } ], "summary": "Cancelar una cita", "tags": [ "Agenda" ], "x-api-status": "stable", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl '${BASE_URL}/appointments/60000000-0000-4000-8000-000000000001/cancel' --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'Content-Type: application/json' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000010' --header 'Idempotency-Key: cancel-demo-0001' --data '{\"reasonId\":\"70000000-0000-4000-8000-000000000001\",\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/appointments/${appointmentId}/cancel`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', 'X-Correlation-Id': crypto.randomUUID(), 'Idempotency-Key': 'cancel-demo-0001' }, body: JSON.stringify({ reasonId, expectedVersion: 1 }) });" } ] } }, "/appointments/{appointmentId}/reschedule": { "post": { "description": "Cambia atomicamente una cita a la opcion indicada: reserva la nueva capacidad y libera la anterior solo si toda la operacion confirma. Exige option token nuevo y version vigente.", "operationId": "rescheduleAppointment", "parameters": [ { "description": "Identificador opaco de la cita dentro del tenant autenticado.", "in": "path", "name": "appointmentId", "required": true, "schema": { "default": "", "example": "60000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "expectedVersion": 1, "optionToken": "opt_preview_synthetic_new_option" } } }, "schema": { "additionalProperties": false, "properties": { "expectedVersion": { "default": "", "minimum": 1, "type": "integer" }, "optionToken": { "default": "", "maxLength": 2048, "minLength": 20, "type": "string" } }, "required": [ "optionToken", "expectedVersion" ], "type": "object" } } }, "description": "Nueva opcion opaca y version de la cita a reemplazar.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "$ref": "#/components/examples/Appointment" } }, "schema": { "$ref": "#/components/schemas/Appointment" } } }, "description": "Cita reprogramada o replay valido.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "servicePrincipal": [ "appointments:write" ] } ], "summary": "Reprogramar una cita", "tags": [ "Agenda" ], "x-api-status": "stable", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl '${BASE_URL}/appointments/60000000-0000-4000-8000-000000000001/reschedule' --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'Content-Type: application/json' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000011' --header 'Idempotency-Key: reschedule-demo-0001' --data '{\"optionToken\":\"opt_preview_synthetic_new_option\",\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/appointments/${appointmentId}/reschedule`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', 'X-Correlation-Id': crypto.randomUUID(), 'Idempotency-Key': 'reschedule-demo-0001' }, body: JSON.stringify({ optionToken, expectedVersion: 1 }) });" } ] } }, "/availability": { "get": { "description": "Retorna opciones reservables para un servicio y rango maximo de 31 dias. `optionToken` es opaco, ligado al tenant y de corta duracion; debe enviarse al reservar y no debe persistirse como identificador de agenda.", "operationId": "searchAvailability", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Servicio contratado solicitado.", "in": "query", "name": "serviceId", "required": true, "schema": { "default": "", "example": "30000000-0000-4000-8000-000000000003", "format": "uuid", "type": "string" } }, { "description": "Inicio inclusivo en ISO 8601 con offset.", "in": "query", "name": "from", "required": true, "schema": { "default": "", "example": "2026-08-03T00:00:00-05:00", "format": "date-time", "type": "string" } }, { "description": "Fin exclusivo en ISO 8601 con offset.", "in": "query", "name": "to", "required": true, "schema": { "default": "", "example": "2026-08-10T00:00:00-05:00", "format": "date-time", "type": "string" } }, { "description": "Filtro opcional por sede.", "in": "query", "name": "locationId", "required": false, "schema": { "default": "", "format": "uuid", "type": "string" } }, { "description": "Filtro opcional por profesional.", "in": "query", "name": "practitionerId", "required": false, "schema": { "default": "", "format": "uuid", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "items": [ { "endsAt": "2026-08-03T09:30:00-05:00", "expiresAt": "2026-07-26T14:20:00-05:00", "locationId": "50000000-0000-4000-8000-000000000001", "optionToken": "opt_preview_synthetic_not_a_real_token", "practitionerId": "50000000-0000-4000-8000-000000000002", "startsAt": "2026-08-03T09:00:00-05:00" } ], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/AvailabilityPage" } } }, "description": "Pagina de opciones disponibles al momento de la consulta.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "servicePrincipal": [ "availability:read" ] } ], "summary": "Consultar opciones de disponibilidad", "tags": [ "Agenda" ], "x-api-status": "stable", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --get '${BASE_URL}/availability' --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000006' --data-urlencode 'serviceId=30000000-0000-4000-8000-000000000003' --data-urlencode 'from=2026-08-03T00:00:00-05:00' --data-urlencode 'to=2026-08-10T00:00:00-05:00'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const query = new URLSearchParams({ serviceId, from: '2026-08-03T00:00:00-05:00', to: '2026-08-10T00:00:00-05:00' }); const response = await fetch(`${baseUrl}/availability?${query}`, { headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] } }, "/contracted-services": { "get": { "description": "Lista servicios activos del contrato indicado para la fecha consultada. La respuesta es paginada y no expone tarifas, identificadores de otros tenants ni datos del paciente. Los identificadores `id` y `appointmentTypeId` son reservables mediante disponibilidad.", "operationId": "listContractedServices", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Identificador del pagador en el tenant.", "in": "query", "name": "payerId", "required": true, "schema": { "default": "", "example": "30000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Contrato activo asociado al pagador.", "in": "query", "name": "contractId", "required": true, "schema": { "default": "", "example": "30000000-0000-4000-8000-000000000002", "format": "uuid", "type": "string" } }, { "description": "Fecha local para validar vigencia.", "in": "query", "name": "effectiveOn", "required": true, "schema": { "default": "", "example": "2026-08-03", "format": "date", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "value": { "items": [ { "appointmentTypeId": "30000000-0000-4000-8000-000000000004", "code": "CONSULTA-GENERAL", "id": "30000000-0000-4000-8000-000000000003", "name": "Consulta medicina general", "requiresPreauthorization": false } ], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/ContractedServicePage" } } }, "description": "Pagina de servicios contratados vigentes.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "servicePrincipal": [ "contracts:read" ] } ], "summary": "Listar servicios contratados", "tags": [ "Cobertura" ], "x-api-status": "stable", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --get '${BASE_URL}/contracted-services' --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000005' --data-urlencode 'payerId=30000000-0000-4000-8000-000000000001' --data-urlencode 'contractId=30000000-0000-4000-8000-000000000002' --data-urlencode 'effectiveOn=2026-08-03'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const query = new URLSearchParams({ payerId, contractId, effectiveOn: '2026-08-03' }); const response = await fetch(`${baseUrl}/contracted-services?${query}`, { headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });" } ] } }, "/eligibility-checks": { "post": { "description": "Evalua paciente, pagador, contrato y servicio para una fecha local. Un resultado no elegible se expresa con HTTP 200 y razones tipadas; los 4xx se reservan para errores del protocolo. Preview: el runtime solo valida paciente activo durante la reserva.", "operationId": "checkPatientEligibility", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "contractId": "30000000-0000-4000-8000-000000000002", "patientId": "20000000-0000-4000-8000-000000000001", "payerId": "30000000-0000-4000-8000-000000000001", "serviceDate": "2026-08-03", "serviceId": "30000000-0000-4000-8000-000000000003" } } }, "schema": { "additionalProperties": false, "properties": { "contractId": { "default": "", "format": "uuid", "type": "string" }, "patientId": { "default": "", "format": "uuid", "type": "string" }, "payerId": { "default": "", "format": "uuid", "type": "string" }, "serviceDate": { "default": "", "format": "date", "type": "string" }, "serviceId": { "default": "", "format": "uuid", "type": "string" } }, "required": [ "patientId", "payerId", "contractId", "serviceId", "serviceDate" ], "type": "object" } } }, "description": "Contexto de cobertura a evaluar dentro del tenant autenticado.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "eligible": { "value": { "decisionId": "40000000-0000-4000-8000-000000000001", "eligible": true, "evaluatedAt": "2026-07-26T14:05:00-05:00", "reasons": [], "validUntil": "2026-08-03T23:59:59-05:00" } } }, "schema": { "$ref": "#/components/schemas/EligibilityResult" } } }, "description": "Decision de negocio de elegibilidad, positiva o negativa.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "servicePrincipal": [ "eligibility:read" ] } ], "summary": "[Preview] Validar elegibilidad para un servicio", "tags": [ "Cobertura" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl '${BASE_URL}/eligibility-checks' --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'Content-Type: application/json' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000004' --header 'Idempotency-Key: eligibility-demo-0001' --data '{\"patientId\":\"20000000-0000-4000-8000-000000000001\",\"payerId\":\"30000000-0000-4000-8000-000000000001\",\"contractId\":\"30000000-0000-4000-8000-000000000002\",\"serviceId\":\"30000000-0000-4000-8000-000000000003\",\"serviceDate\":\"2026-08-03\"}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/eligibility-checks`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', 'X-Correlation-Id': crypto.randomUUID(), 'Idempotency-Key': 'eligibility-demo-0001' }, body: JSON.stringify(check) }); const decision = await response.json();" } ] } }, "/patients": { "post": { "description": "Crea un paciente en el tenant del service principal, registra la evidencia temporal de consentimiento y rechaza duplicados activos. La clave de idempotencia identifica el intento y no puede reutilizarse con otro payload.", "operationId": "createPatient", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "$ref": "#/components/examples/PatientCreate" } }, "schema": { "additionalProperties": false, "properties": { "consentGrantedAt": { "default": "", "format": "date-time", "type": "string" }, "documentNumber": { "default": "", "maxLength": 40, "minLength": 3, "type": "string" }, "documentType": { "default": "", "maxLength": 20, "minLength": 1, "type": "string" }, "email": { "default": "", "format": "email", "maxLength": 254, "type": "string" }, "fullName": { "default": "", "maxLength": 160, "minLength": 3, "type": "string" }, "phone": { "default": "", "maxLength": 30, "minLength": 7, "type": "string" } }, "required": [ "documentType", "documentNumber", "fullName", "phone", "consentGrantedAt" ], "type": "object" } } }, "description": "Datos minimos del paciente; no incluya historia clinica ni credenciales.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "$ref": "#/components/examples/Patient" } }, "schema": { "$ref": "#/components/schemas/Patient" } } }, "description": "Paciente creado o resultado original de un replay valido.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "servicePrincipal": [ "patients:write" ] } ], "summary": "Registrar un paciente", "tags": [ "Pacientes" ], "x-api-status": "stable", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl 'https://citamedica.magnosoft.com.co/api/external/v1/patients' --request POST \\\n --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'Content-Type: application/json' \\\n --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000002' \\\n --header 'Idempotency-Key: patient-demo-0001' \\\n --data '{\"documentType\":\"CC\",\"documentNumber\":\"900000001\",\"fullName\":\"Paciente Ejemplo\",\"phone\":\"3000000000\",\"email\":\"paciente@example.invalid\",\"consentGrantedAt\":\"2026-07-26T14:00:00-05:00\"}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/patients`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', 'X-Correlation-Id': crypto.randomUUID(), 'Idempotency-Key': 'patient-demo-0001' }, body: JSON.stringify(patient) });\nconst created = await response.json();" } ] } }, "/patients/resolve": { "get": { "description": "Busca una coincidencia exacta dentro del tenant derivado del token mediante tipo y numero de documento normalizados. No realiza busquedas parciales ni retorna pacientes de otra organizacion.", "operationId": "resolvePatient", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Codigo de tipo documental acordado con el tenant.", "in": "query", "name": "documentType", "required": true, "schema": { "default": "", "example": "CC", "maxLength": 20, "minLength": 1, "type": "string" } }, { "description": "Numero documental sintetico; se normaliza para coincidencia exacta.", "in": "query", "name": "documentNumber", "required": true, "schema": { "default": "", "example": "900000001", "maxLength": 40, "minLength": 3, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "matched": { "$ref": "#/components/examples/PatientResolutionMatched" } }, "schema": { "$ref": "#/components/schemas/PatientResolution" } } }, "description": "Resultado determinista de resolucion; `matched=false` no es un error.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "servicePrincipal": [ "patients:read" ] } ], "summary": "Resolver la identidad de un paciente", "tags": [ "Pacientes" ], "x-api-status": "stable", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --get 'https://citamedica.magnosoft.com.co/api/external/v1/patients/resolve' \\\n --header 'Authorization: Bearer ${ACCESS_TOKEN}' \\\n --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000001' \\\n --data-urlencode 'documentType=CC' --data-urlencode 'documentNumber=900000001'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const url = new URL('/api/external/v1/patients/resolve', 'https://citamedica.magnosoft.com.co');\nurl.search = new URLSearchParams({ documentType: 'CC', documentNumber: '900000001' });\nconst response = await fetch(url, { headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } });\nconst result = await response.json();" } ] } }, "/patients/{patientId}": { "get": { "description": "Retorna el paciente solamente cuando pertenece a la organizacion y empresa derivadas del service principal. Un identificador inexistente o de otro tenant produce la misma respuesta segura de recurso no encontrado.", "operationId": "getPatient", "parameters": [ { "description": "Identificador opaco del paciente dentro del tenant autenticado.", "in": "path", "name": "patientId", "required": true, "schema": { "default": "", "example": "20000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "$ref": "#/components/examples/Patient" } }, "schema": { "$ref": "#/components/schemas/Patient" } } }, "description": "Paciente visible dentro del tenant autenticado.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "502": { "$ref": "#/components/responses/BadGateway" } }, "security": [ { "servicePrincipal": [ "patients:read" ] } ], "summary": "Consultar un paciente por identificador", "tags": [ "Pacientes" ], "x-api-status": "stable", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl '${BASE_URL}/patients/20000000-0000-4000-8000-000000000001' --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000003'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/patients/${patientId}`, { headers: { Authorization: `Bearer ${accessToken}`, 'X-Correlation-Id': crypto.randomUUID() } }); const patient = await response.json();" } ] }, "patch": { "description": "Actualiza nombre y canales de contacto sin permitir cambiar la identidad documental. `expectedVersion` aplica concurrencia optimista y evita sobrescribir cambios recientes.", "operationId": "updatePatient", "parameters": [ { "description": "Identificador opaco del paciente dentro del tenant autenticado.", "in": "path", "name": "patientId", "required": true, "schema": { "default": "", "example": "20000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "email": "actualizado@example.invalid", "expectedVersion": 1, "fullName": "Paciente Ejemplo Actualizado", "phone": "3000000001" } } }, "schema": { "additionalProperties": false, "properties": { "email": { "default": "", "format": "email", "maxLength": 254, "type": "string" }, "expectedVersion": { "default": "", "minimum": 1, "type": "integer" }, "fullName": { "default": "", "maxLength": 160, "minLength": 3, "type": "string" }, "phone": { "default": "", "maxLength": 30, "minLength": 7, "type": "string" } }, "required": [ "fullName", "phone", "expectedVersion" ], "type": "object" } } }, "description": "Campos editables y version observada por el consumidor.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "synthetic": { "$ref": "#/components/examples/Patient" } }, "schema": { "$ref": "#/components/schemas/Patient" } } }, "description": "Paciente actualizado o replay de la misma solicitud.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "servicePrincipal": [ "patients:write" ] } ], "summary": "Actualizar datos de contacto del paciente", "tags": [ "Pacientes" ], "x-api-status": "stable", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl '${BASE_URL}/patients/20000000-0000-4000-8000-000000000001' --request PATCH --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'Content-Type: application/json' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000003' --header 'Idempotency-Key: patient-update-demo-0001' --data '{\"fullName\":\"Paciente Ejemplo Actualizado\",\"phone\":\"3000000001\",\"expectedVersion\":1}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/patients/${patientId}`, { method: 'PATCH', headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', 'X-Correlation-Id': crypto.randomUUID(), 'Idempotency-Key': 'patient-update-demo-0001' }, body: JSON.stringify({ fullName: 'Paciente Ejemplo Actualizado', phone: '3000000001', expectedVersion: 1 }) });" } ] } }, "/practitioners": { "get": { "description": "Lista profesionales activos del tenant autenticado. Puede filtrar por servicio y sede; los arreglos retornados contienen exclusivamente relaciones activas utilizables por SAH.", "operationId": "listSahPractitioners", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Tipo de cita contratado que debe atender el profesional.", "in": "query", "name": "serviceId", "required": false, "schema": { "default": "", "example": "22000000-0000-4000-8000-000000000004", "format": "uuid", "type": "string" } }, { "description": "Sede activa asociada al profesional.", "in": "query", "name": "locationId", "required": false, "schema": { "default": "", "example": "22000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Cursor opaco retornado por la pagina anterior; no debe interpretarse.", "in": "query", "name": "cursor", "required": false, "schema": { "default": "", "maxLength": 512, "minLength": 1, "type": "string" } }, { "description": "Cantidad maxima de elementos solicitados.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "example": 25, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "demo": { "value": { "items": [ { "code": "ANA-TORRES", "fullName": "Dra. Ana Torres", "id": "22000000-0000-4000-8000-000000000002", "locationIds": [ "22000000-0000-4000-8000-000000000001" ], "serviceIds": [ "22000000-0000-4000-8000-000000000004" ], "specialtyIds": [ "22000000-0000-4000-8000-000000000003" ] } ], "nextCursor": null } } }, "schema": { "$ref": "#/components/schemas/SahPractitionerPage" } } }, "description": "Pagina estable de profesionales reservables.", "headers": { "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "servicePrincipal": [ "practitioners:read" ] } ], "summary": "Listar profesionales reservables", "tags": [ "Agenda" ], "x-api-status": "stable", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --get '${BASE_URL}/practitioners' --header 'Authorization: Bearer ${ACCESS_TOKEN}' --data-urlencode 'serviceId=22000000-0000-4000-8000-000000000004'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/practitioners?serviceId=${serviceId}`, { headers: { Authorization: `Bearer ${accessToken}` } });" } ] } }, "/preauthorizations": { "post": { "description": "Radica una solicitud con referencias externas no sensibles y metadatos estructurados. No acepta archivos, historia clinica ni credenciales; documentos se intercambiaran por un canal seguro definido posteriormente. Preview sin soporte en runtime.", "operationId": "submitPreauthorization", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "contractId": "30000000-0000-4000-8000-000000000002", "externalReference": "SAH-DEMO-0001", "patientId": "20000000-0000-4000-8000-000000000001", "payerId": "30000000-0000-4000-8000-000000000001", "serviceId": "30000000-0000-4000-8000-000000000003" } } }, "schema": { "additionalProperties": false, "properties": { "contractId": { "default": "", "format": "uuid", "type": "string" }, "externalReference": { "default": "", "maxLength": 100, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" }, "patientId": { "default": "", "format": "uuid", "type": "string" }, "payerId": { "default": "", "format": "uuid", "type": "string" }, "serviceId": { "default": "", "format": "uuid", "type": "string" } }, "required": [ "patientId", "payerId", "contractId", "serviceId", "externalReference" ], "type": "object" } } }, "description": "Referencias del paciente, cobertura y servicio solicitado.", "required": true }, "responses": { "202": { "content": { "application/json": { "examples": { "synthetic": { "value": { "createdAt": "2026-07-26T14:15:00-05:00", "id": "90000000-0000-4000-8000-000000000001", "status": "RECEIVED" } } }, "schema": { "$ref": "#/components/schemas/AsyncResource" } } }, "description": "Solicitud aceptada para procesamiento o replay valido.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "servicePrincipal": [ "preauthorizations:write" ] } ], "summary": "[Preview] Radicar una preautorizacion", "tags": [ "Gestion complementaria" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl '${BASE_URL}/preauthorizations' --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'Content-Type: application/json' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000013' --header 'Idempotency-Key: preauth-demo-0001' --data '{\"patientId\":\"20000000-0000-4000-8000-000000000001\",\"payerId\":\"30000000-0000-4000-8000-000000000001\",\"contractId\":\"30000000-0000-4000-8000-000000000002\",\"serviceId\":\"30000000-0000-4000-8000-000000000003\",\"externalReference\":\"SAH-DEMO-0001\"}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/preauthorizations`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', 'X-Correlation-Id': crypto.randomUUID(), 'Idempotency-Key': 'preauth-demo-0001' }, body: JSON.stringify(request) });" } ] } }, "/siau-cases": { "post": { "description": "Crea un caso de atencion al usuario asociado opcionalmente a paciente o cita. La descripcion debe excluir diagnosticos, credenciales y datos financieros; el API no reemplaza canales de urgencia. Preview sin modulo SIAU en runtime.", "operationId": "createSiauCase", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "appointmentId": "60000000-0000-4000-8000-000000000001", "category": "INFORMATION_REQUEST", "description": "Solicitud de confirmacion del horario publicado", "externalReference": "SAH-CASE-DEMO-0001", "patientId": "20000000-0000-4000-8000-000000000001" } } }, "schema": { "additionalProperties": false, "properties": { "appointmentId": { "default": "", "format": "uuid", "type": "string" }, "category": { "default": "", "enum": [ "INFORMATION_REQUEST", "COMPLAINT", "CLAIM", "SUGGESTION", "COMPLIMENT" ], "type": "string" }, "description": { "default": "", "maxLength": 1000, "minLength": 10, "type": "string" }, "externalReference": { "default": "", "maxLength": 100, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" }, "patientId": { "default": "", "format": "uuid", "type": "string" } }, "required": [ "category", "externalReference", "description" ], "type": "object" } } }, "description": "Categoria, referencia externa y descripcion operativa minima.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "value": { "createdAt": "2026-07-26T14:20:00-05:00", "id": "a0000000-0000-4000-8000-000000000001", "status": "OPEN" } } }, "schema": { "$ref": "#/components/schemas/AsyncResource" } } }, "description": "Caso creado o replay valido.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "servicePrincipal": [ "siau:write" ] } ], "summary": "[Preview] Crear un caso SIAU", "tags": [ "Gestion complementaria" ], "x-api-status": "preview", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl '${BASE_URL}/siau-cases' --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'Content-Type: application/json' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000014' --header 'Idempotency-Key: siau-demo-0001' --data '{\"category\":\"INFORMATION_REQUEST\",\"externalReference\":\"SAH-CASE-DEMO-0001\",\"description\":\"Solicitud de confirmacion del horario publicado\"}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/siau-cases`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', 'X-Correlation-Id': crypto.randomUUID(), 'Idempotency-Key': 'siau-demo-0001' }, body: JSON.stringify(siauCase) });" } ] } }, "/waitlist-entries": { "post": { "description": "Registra preferencias de agenda cuando no existe una opcion aceptable. No garantiza asignacion ni reserva capacidad y no admite texto clinico libre. Preview sin soporte de asignacion automatica.", "operationId": "createWaitlistEntry", "parameters": [ { "description": "UUID generado por el consumidor para trazabilidad; el servidor genera uno si se omite.", "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "default": "", "example": "10000000-0000-4000-8000-000000000001", "format": "uuid", "type": "string" } }, { "description": "Clave unica por service principal y operacion; reutilizarla con otro payload produce 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "default": "", "example": "operation-demo-0001", "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "synthetic": { "value": { "dateFrom": "2026-08-03", "dateTo": "2026-08-31", "patientId": "20000000-0000-4000-8000-000000000001", "preferredPeriods": [ "MORNING" ], "serviceId": "30000000-0000-4000-8000-000000000003" } } }, "schema": { "additionalProperties": false, "properties": { "dateFrom": { "default": "", "format": "date", "type": "string" }, "dateTo": { "default": "", "format": "date", "type": "string" }, "locationId": { "default": "", "format": "uuid", "type": "string" }, "patientId": { "default": "", "format": "uuid", "type": "string" }, "practitionerId": { "default": "", "format": "uuid", "type": "string" }, "preferredPeriods": { "items": { "default": "", "enum": [ "MORNING", "AFTERNOON", "EVENING" ], "type": "string" }, "maxItems": 1, "minItems": 1, "type": "array", "uniqueItems": true }, "serviceId": { "default": "", "format": "uuid", "type": "string" } }, "required": [ "patientId", "serviceId", "dateFrom", "dateTo", "preferredPeriods" ], "type": "object" } } }, "description": "Paciente, servicio, ventana y preferencias operativas.", "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "synthetic": { "value": { "createdAt": "2026-07-26T14:10:00-05:00", "id": "80000000-0000-4000-8000-000000000001", "status": "ACTIVE" } } }, "schema": { "$ref": "#/components/schemas/AsyncResource" } } }, "description": "Entrada creada o replay valido.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "X-Correlation-Id": { "$ref": "#/components/headers/CorrelationId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "servicePrincipal": [ "waitlist:write" ] } ], "summary": "Registrar una solicitud en lista de espera", "tags": [ "Gestion complementaria" ], "x-api-status": "stable", "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl '${BASE_URL}/waitlist-entries' --request POST --header 'Authorization: Bearer ${ACCESS_TOKEN}' --header 'Content-Type: application/json' --header 'X-Correlation-Id: 10000000-0000-4000-8000-000000000012' --header 'Idempotency-Key: waitlist-demo-0001' --data '{\"patientId\":\"20000000-0000-4000-8000-000000000001\",\"serviceId\":\"30000000-0000-4000-8000-000000000003\",\"dateFrom\":\"2026-08-03\",\"dateTo\":\"2026-08-31\",\"preferredPeriods\":[\"MORNING\"]}'" }, { "label": "JavaScript", "lang": "JavaScript", "source": "const response = await fetch(`${baseUrl}/waitlist-entries`, { method: 'POST', headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', 'X-Correlation-Id': crypto.randomUUID(), 'Idempotency-Key': 'waitlist-demo-0001' }, body: JSON.stringify(entry) });" } ] } } }, "securityDefs": { "servicePrincipal": { "description": "OAuth 2.0 client credentials emitido para una aplicacion, tenant y empresa autorizados.", "flows": { "clientCredentials": { "scopes": { "appointment-events:read": "Reproducir eventos de citas.", "appointments:read": "Consultar citas.", "appointments:write": "Reservar, cancelar y reprogramar citas.", "availability:read": "Consultar opciones de agenda.", "configuration:read": "Consultar catalogos administrativos de configuracion.", "configuration:write": "Crear, actualizar y eliminar catalogos administrativos.", "contracts:read": "Consultar servicios contratados.", "eligibility:read": "Evaluar elegibilidad de cobertura.", "patients:read": "Consultar identidad de pacientes.", "patients:write": "Registrar y actualizar pacientes.", "practitioners:read": "Consultar profesionales reservables.", "preauthorizations:write": "Radicar preautorizaciones.", "scheduling:generate": "Generar slots desde una regla autorizada.", "scheduling:read": "Consultar configuracion de agenda.", "scheduling:write": "Mantener programas, reglas, relaciones, festivos y bloqueos.", "siau:write": "Crear casos SIAU.", "waitlist:write": "Registrar entradas de lista de espera." }, "tokenUrl": "https://auth.magnosoft.com.co/oauth2/token" } }, "type": "oauth2" } }, "servers": [ { "description": "Produccion (operaciones disponibles solo cuando su estado sea stable)", "url": "https://citamedica.magnosoft.com.co/api/external/v1" } ], "tags": [ { "description": "Identificacion, registro y mantenimiento del paciente.", "name": "Pacientes", "x-displayName": "Pacientes" }, { "description": "Elegibilidad y servicios contratados para el paciente.", "name": "Cobertura", "x-displayName": "Cobertura" }, { "description": "Disponibilidad y ciclo de vida de citas medicas.", "name": "Agenda", "x-displayName": "Agenda" }, { "description": "Lista de espera, preautorizaciones y casos SIAU.", "name": "Gestion complementaria", "x-displayName": "Gestion complementaria" }, { "description": "Administracion externa preview de sedes.", "name": "Configuracion - Sedes", "x-displayName": "Sedes" }, { "description": "Administracion externa preview de profesionales.", "name": "Configuracion - Profesionales", "x-displayName": "Profesionales" }, { "description": "Administracion externa preview de especialidades.", "name": "Configuracion - Especialidades", "x-displayName": "Especialidades" }, { "description": "Administracion externa preview de tipos de cita.", "name": "Configuracion - Tipos de cita", "x-displayName": "Tipos de cita" }, { "description": "Administracion externa preview de tipos de consulta.", "name": "Configuracion - Tipos de consulta", "x-displayName": "Tipos de consulta" }, { "description": "Administracion externa preview de definiciones de oportunidad.", "name": "Configuracion - Oportunidades", "x-displayName": "Definiciones de oportunidad" }, { "description": "Administracion externa preview de pagadores.", "name": "Configuracion - Pagadores", "x-displayName": "Pagadores" }, { "description": "Administracion externa preview de contratos.", "name": "Configuracion - Contratos", "x-displayName": "Contratos" }, { "description": "Administracion externa preview de fuentes de solicitud.", "name": "Configuracion - Fuentes de solicitud", "x-displayName": "Fuentes de solicitud" }, { "description": "Administracion externa preview de motivos de cancelacion.", "name": "Configuracion - Motivos de cancelacion", "x-displayName": "Motivos de cancelacion" }, { "description": "Administracion externa preview de motivos de inasistencia.", "name": "Configuracion - Motivos de inasistencia", "x-displayName": "Motivos de inasistencia" }, { "description": "Programas administrativos de agenda.", "name": "Scheduling - Programas" }, { "description": "Reglas recurrentes de agenda.", "name": "Scheduling - Reglas" }, { "description": "Asignaciones entre programas, profesionales y tipos de cita.", "name": "Scheduling - Relaciones" }, { "description": "Festivos operativos en America/Bogota.", "name": "Scheduling - Festivos" }, { "description": "Bloqueos explicitos de agenda.", "name": "Scheduling - Bloqueos" }, { "description": "Materializacion controlada de slots desde reglas.", "name": "Scheduling - Generacion de slots" } ], "x-tagGroups": [ { "name": "API esencial SAH", "tags": [ "Pacientes", "Cobertura", "Agenda", "Gestion complementaria" ] }, { "name": "Catalogos de configuracion", "tags": [ "Configuracion - Sedes", "Configuracion - Profesionales", "Configuracion - Especialidades", "Configuracion - Tipos de cita", "Configuracion - Tipos de consulta", "Configuracion - Oportunidades", "Configuracion - Pagadores", "Configuracion - Contratos", "Configuracion - Fuentes de solicitud", "Configuracion - Motivos de cancelacion", "Configuracion - Motivos de inasistencia" ] }, { "name": "Configuracion de agenda", "tags": [ "Scheduling - Programas", "Scheduling - Reglas", "Scheduling - Relaciones", "Scheduling - Festivos", "Scheduling - Bloqueos", "Scheduling - Generacion de slots" ] } ] }