Integre la API de producción para enviar cuadrantes con una clave API vinculada a su suscripción de pago. Los valores predeterminados del inquilino se guardan con PATCH /v1/schedule-defaults; los deseos semanales por empleado se leen o sustituyen con GET/PUT /v1/staff/{staffId}/weekly-shift-wish. La facturación sigue su plan y contrato (no por llamada API medida). Esta página documenta límites, validaciones y códigos de error — use la barra lateral para ir a cada campo.
Esta página documenta solo la API REST de producto en API Gateway ({stage}/v1/*, autenticación con x-api-key).
Las rutas Next.js /api/* (webhooks de Stripe, imágenes OG, Web Vitals, etc.) son internas de la aplicación web y no forman parte de esta API para desarrolladores. No las use para integraciones externas.
GET /v1/processing-history no se ofrece (eliminado con la interfaz antigua) y no figura en la lista de endpoints de esta página.
Esta API HTTP forma parte del producto de pago: el acceso requiere un acuerdo comercial activo y las claves se emiten a su organización tras el onboarding.
La facturación se basa en la suscripción y el contrato. En planes de pago, los cargos suelen seguir la página de precios (p. ej. por miembro de plantilla y mes).
Los límites del playground o del nivel gratuito no aplican a las claves de API de pago. Los límites efectivos (días, personal, granularidad de 15 minutos) los fijan sus derechos de pago. Consulte Límites y valores por defecto en esta página.
Las solicitudes deben incluir una clave API válida emitida con su suscripción de pago. Cree, rote y revoque claves desde el área de cuenta tras iniciar sesión.
Envíe la clave en la cabecera x-api-key. Las claves están ligadas a su organización para la resolución del inquilino y los límites de acceso del plan contratado.
Gestionar claves: Gestión de API
Envíe una condición de cuadrante como JSON. Es la superficie de integración de pago; la URL base exacta se proporciona por entorno tras aprovisionar el acceso a la API.
Use la URL base proporcionada cuando se aprovisionó el acceso a la API o por su contacto de operaciones.
Sustituya BASE_URL por la URL base de la API (prefijo de ruta) proporcionada cuando se aprovisionó su acceso.
Envíe su clave API en la cabecera **x-api-key**. Su organización (inquilino) se identifica a partir de la clave; no pasa un id de inquilino aparte en la cadena de consulta.
La lectura y actualización de datos de empresa (GET/PATCH /v1/company) requiere una suscripción de pago activa. Si la facturación no está configurada para su inquilino, puede recibir **503** (p. ej. código **STRIPE_NOT_CONFIGURED**).
Windows PowerShell: una barra invertida final `\` **no** continúa la línea. Escriba en una sola línea, o termine cada línea con acento grave (`) para continuar.
curl -sS -D - \ -H "x-api-key: YOUR_API_KEY" \ "BASE_URL/v1/schedule-results?limit=10" curl -sS -D - \ -H "x-api-key: YOUR_API_KEY" \ "BASE_URL/v1/company"
Misma URL base y misma x-api-key que POST /v1/schedule. Consulta opcional: limit (1–100, predeterminado 50), cursor (token opaco: reenvíe el campo nextCursor de la respuesta anterior).
GET /v1/company y las actualizaciones de empresa requieren una suscripción de pago activa. Si la facturación no está configurada, puede recibir **503 / STRIPE_NOT_CONFIGURED**.
| Método | Ruta | Descripción |
|---|---|---|
| GET | {baseUrl}/v1/schedule-results | Lista filas padre SCHEDULE_RESULT: conditionId, status, candidateCount, createdAt/updatedAt, etc. Paginación DynamoDB. |
| GET | {baseUrl}/v1/schedule-results/history | Búsqueda de historial de resultados (como en el navegador). from / to (ISO 8601, predeterminado inicio de servicio a ahora), keyword, eventName (INSERT,MODIFY,REMOVE separados por comas), limit, cursor. Fusiona reciente y archivo automáticamente; solo items / nextCursor. |
| GET | {baseUrl}/v1/schedule-results/{conditionId} | Obtiene una fila padre SCHEDULE_RESULT por conditionId (atributos JSON; sin PK/SK). |
| GET | {baseUrl}/v1/schedule-results/{conditionId}/resolution | Salida de optimización resuelta: status, candidates, confirmedAssignments si existen. Si status es completed y aún no confirmado, rank-1 puede auto-confirmarse en este GET (efecto secundario). Use POST …/confirm-assignments para confirmación manual. |
| GET | {baseUrl}/v1/schedule-results/{conditionId}/review | Carga de revisión para confirmación manual (candidatos, requiredByCellKey, allowedCellKeys del personal, etc.). |
| GET | {baseUrl}/v1/schedule-results/{conditionId}/emergency-shift-context | Contexto de turno de emergencia (fechas, personal, franjas). Requiere suscripción de pago; null si no hay condición. |
| GET | {baseUrl}/v1/schedule-conditions | Lista filas padre SCHEDULE_CONDITION (conditionId, fechas, publicApiCancelledAt opcional). |
| GET | {baseUrl}/v1/schedule-conditions/{conditionId} | Fila padre de condición más reqDays y staffSnapshots (sin PK/SK). |
| GET | {baseUrl}/v1/audit-logs | Lista entradas de auditoría (más recientes primero; paginación con cursor). |
| GET | {baseUrl}/v1/schedule-defaults | Fila de valores predeterminados del inquilino (SCHEDULE_DEFAULTS) o null si no guardada. |
| GET | {baseUrl}/v1/schedule-actual/{conditionId} | Fila SCHEDULE_ACTUAL de turnos reales, o null si no existe. |
| GET | {baseUrl}/v1/staff/{staffId}/weekly-shift-wish | Fila de deseos semanales del empleado, o null si no existe. |
| GET | {baseUrl}/v1/company | Devuelve campos de Stripe Customer (nombre, correo, teléfono, dirección) para el customerId de su clave API. |
| GET | {baseUrl}/v1/users | Lista usuarios del inquilino (opcional: limit, cursor, userName, permissionProfileId, scope fullAccess|nonFullAccess). |
| GET | {baseUrl}/v1/users/{userId} | Obtiene un usuario por el userId de la ruta. |
| GET | {baseUrl}/v1/staff | Lista personal activo del inquilino (ordenado por nombre mostrado). |
| GET | {baseUrl}/v1/staff/{staffId} | Obtiene una persona por staffId con detalles laborales (laborLawCompliance, laborFlsaExempt, topes personales, laborConstraintMask). Borrado lógico → 404. |
Use la misma clave API con cuerpos JSON. PATCH /v1/company rechaza cadenas vacías en campos como el nombre de la empresa (alineado con la aplicación web). PATCH /v1/schedule-defaults guarda valores predeterminados del inquilino (requirementsByCellKey, horizonte de planificación, etc.); los campos de pago siguen su suscripción. PUT /v1/staff/{staffId}/weekly-shift-wish sustituye por completo la cuadrícula semanal de deseos (véase la nota de validación). DELETE /v1/users/{userId} devuelve 409 si no quedarían usuarios activos o al quitar al último administrador. POST /v1/staff devuelve 409 STAFF_LIMIT si la plantilla superaría el tope del inquilino.
POST /v1/users exige userName, email, permissionProfileId; opcional: locale, password. PATCH usuario: solo campos a cambiar. POST /v1/staff: JSON { "displayName": "..." } únicamente. PATCH /v1/staff/{staffId}: displayName, laborLawCompliance, laborFlsaExempt, personalMaxWeeklyMinutes / personalMaxMonthlyMinutes / personalMaxThreeMonthMinutes (entero o null), laborConstraintMask (objeto o null si laborLawCompliance true) — campos laborales de pago. POST /v1/schedule-results/{conditionId}/emergency-shift: absentStaffIds, absentDatesYmd y/o absentSlots (pago, plan fuente completado). POST …/confirm-assignments: array assignments y relaxAvailability opcional. PATCH /v1/schedule-defaults: PUBLIC_API_SCHEDULE_REQUEST_BODY.md §12. PUT /v1/staff/{staffId}/weekly-shift-wish: scheduleStartDate, scheduleEndDate, timeRangeStart, timeRangeEnd, wishByCellKey.
| Método | Ruta | Descripción |
|---|---|---|
| PATCH | {baseUrl}/v1/company | Actualiza los campos del perfil de la empresa (cliente de facturación). |
| PATCH | {baseUrl}/v1/schedule-defaults | Guarda valores predeterminados de planificación del inquilino (cuerpo JSON alineado con saveSchema en schedule-defaults-actions). Los campos de pago siguen su suscripción. |
| POST | {baseUrl}/v1/users | Crea un usuario. Devuelve 201 con JSON de usuario. |
| PATCH | {baseUrl}/v1/users/{userId} | Actualiza campos del usuario (userName, email, permissionProfileId, locale). |
| DELETE | {baseUrl}/v1/users/{userId} | Elimina un usuario. 409 si no quedarían usuarios o por la regla del último administrador. |
| POST | {baseUrl}/v1/staff | Crea una persona (displayName). Devuelve 201 con JSON staff. |
| POST | {baseUrl}/v1/schedule-results/{conditionId}/emergency-shift | Clona un plan fuente completado con ausencias aplicadas; devuelve 201 con conditionId. Requiere suscripción de pago. |
| POST | {baseUrl}/v1/schedule-results/{conditionId}/confirm-assignments | Valida y guarda asignaciones editadas manualmente (200 con { ok: true }). |
| PATCH | {baseUrl}/v1/staff/{staffId} | Actualiza displayName y detalles laborales (laborLawCompliance, laborFlsaExempt, topes personales, laborConstraintMask). |
| DELETE | {baseUrl}/v1/staff/{staffId} | Borrado lógico de una persona (establece deletedAt). |
| DELETE | {baseUrl}/v1/schedule-conditions/{conditionId} | Marca la condición como cancelada (publicApiCancelledAt); no elimina filas hijas. |
| PUT | {baseUrl}/v1/schedule-actual/{conditionId} | Guarda asignaciones reales JSON { "assignments": [ ... ] } (validadas contra la cuadrícula de la condición). |
| PUT | {baseUrl}/v1/staff/{staffId}/weekly-shift-wish | Sustituye los deseos semanales: cuadrícula completa (1–7 días), wishByCellKey por celda (NONE|LOW|HIGH); granularidad según valores predeterminados del inquilino. |
| POST | {baseUrl}/v1/users/{userId}/restore | Restaura un usuario borrado lógicamente. |
| Cabecera | Descripción |
|---|---|
| x-api-key | Clave API vinculada a su suscripción de pago (identifica el inquilino y los límites del plan). |
| Content-Type | application/json |
Algunas cabeceras de respuesta (como ids de solicitud) son metadatos de trazabilidad, no su clave API. Trate los **cuerpos** JSON como confidenciales cuando contengan datos de empresa o de usuario.
Límites de validación habituales para su contrato (granularidad de 15 minutos, duración del cuadrante, número de personal registrado y límites relacionados).
| Ajuste | API de pago (típico) |
|---|---|
| Modelo de facturación | Suscripción Stripe; los cargos del producto suelen escalar con los asientos de personal registrados según la página de precios (no por llamada API). |
| maxScheduleDays | Hasta 14 días naturales por envío en la planificación detallada estándar de dos semanas (plazas mayores solo si el contrato lo permite). |
| maxStaffPerSchedule | Hasta 500 filas staff por POST /v1/schedule (PUBLIC_SCHEDULE_MAX_STAFF; staffId en línea en el cuerpo). |
| maxRosterStaff | Hasta 30 empleados activos vía POST /v1/staff con el tope predeterminado actual (STAFF_ROSTER_MAX_PAID); 409 STAFF_LIMIT si se supera. |
| allowedGranularities | [60, 15] — los slots de 15 minutos son de pago; 60 minutos también está soportado. |
| maxPayloadBytes | 524288 (512 KiB) UTF-8 salvo que se conceda un tope mayor. |
| strictUnknownRootKeys | true — se rechazan claves desconocidas en la raíz o en staff |
La necesidad de personal por celda sigue siendo un entero de 0 a 15. Al superar los límites de tasa puede devolverse una respuesta de error.
Con el modo estricto solo se aceptan las siguientes claves de nivel superior. Cualquier otra devuelve UNKNOWN_FIELD.
El payload sigue el modelo público de pago: fechas de calendario, zona horaria, rejilla de slots (60 o 15 minutos en la API de pago), necesidades por celda y disponibilidad del personal. La jurisdicción laboral, los flags de optimización de pago y los campos laborales por empleado no forman parte del JSON: el servidor escribe valores por defecto en la fila padre SCHEDULE_CONDITION al persistir (véase «Legislación laboral y flags de pago»). No incluya claves DynamoDB ni tipos de entidad internos en el cuerpo.
| Campo | Tipo | Obligatorio | Notas |
|---|---|---|---|
| timeZone | string | Sí | Zona horaria IANA para interpretar fechas y slots. |
| scheduleStartDate / scheduleEndDate | string (YYYY-MM-DD) | Sí | Rango de calendario inclusivo; inicio ≤ fin. |
| timeRangeStart / timeRangeEnd | string (HH:mm) | Sí | Rango horario que define la columna de slots; debe generar al menos un slot. |
| slotGranularityMinutes | 60 | 15 | Sí | API de pago: 60 (hora) o 15 (cuartos). Debe estar en allowedGranularities. |
| requirementsByCell | object | Sí | Claves = cellKey en la rejilla calculada; valores = entero 0–15. |
| staff | array | Sí | No vacío; tamaño máximo según límites; cada ítem: staffId, displayName, availableCells opcional. |
Las siguientes secciones reflejan el validador en `app/lib/public-schedule-api/validate.ts` y los sanitizadores en `sanitize.ts`, con los valores por defecto de pago de `PUBLIC_SCHEDULE_SUBMIT_DEFAULTS` salvo que se pasen opciones. Envíe números JSON como números reales (no como strings). Tras la validación, `build-schedule-transact-items.ts` añade campos de la fila padre (copia de optimización de pago, jurisdicción laboral, versión del modelo) que no son claves de la solicitud — véase «Legislación laboral y flags de pago».
string | omitido · Obligatorio: No — opcional
Valores permitidos
Comportamiento
Errores típicos
TYPE_ERRORValor de apiVersion no admitido.string · Obligatorio: Sí
Valores permitidos
Comportamiento
Errores típicos
INVALID_TIME_ZONEFalta, vacío o zona IANA no válida.string, string · Obligatorio: Sí — ambos
Valores permitidos
Comportamiento
Errores típicos
INVALID_DATE_RANGEFormato incorrecto, fechas inválidas o rango vacío.SCHEDULE_SPAN_TOO_LONGMás de maxScheduleDays días.string, string · Obligatorio: Sí — ambos
Valores permitidos
Comportamiento
Errores típicos
INVALID_TIME_RANGEValores faltantes o cero slots para el rango.number (número JSON) · Obligatorio: Sí
Valores permitidos
Comportamiento
Errores típicos
INVALID_GRANULARITYNo es 60/15 o no permitido en el plan.Record<string, number> · Obligatorio: Sí
Valores permitidos
Comportamiento
Errores típicos
INVALID_REQUIREMENTSNo es un objeto o el valor numérico no es válido.UNKNOWN_CELL_KEYClave fuera de la rejilla fecha × slot calculada.array · Obligatorio: Sí — array no vacío
Valores permitidos
Comportamiento
Errores típicos
INVALID_STAFFArray vacío, demasiadas filas, objeto inválido o sanitización fallida.UNKNOWN_FIELDClave extra en un objeto staff en modo estricto.DUPLICATE_STAFF_IDEl mismo staffId dos veces.string[] | omitido · Obligatorio: No — opcional
Valores permitidos
Comprobación SHORTFALL
Errores típicos
INVALID_AVAILABLE_CELLClave de celda desconocida o entrada vacía.SHORTFALL_CELLSPersonal insuficiente frente al cupo requerido en una celda.n/c — persistido en el servidor · En la solicitud: No — nunca envíe estas claves
Qué guarda la API en la fila padre
Documentación
Si envía claves no permitidas
UNKNOWN_FIELDEl modo estricto rechaza propiedades desconocidas en la raíz o en staff.Aplicadas antes o durante la validación según `sanitize.ts`. Explican rechazos como INVALID_STAFF.
staffId
displayName
Claves de celda (requirements / availableCells)
202 Accepted
El cuerpo pasó la validación y se escribió la condición; la optimización puede continuar de forma asíncrona. El manejador puede devolver JSON con conditionId y campos relacionados.
Los errores de validación devuelven información estructurada con un `code` estable. El análisis ocurre antes de la validación (INVALID_JSON, PAYLOAD_TOO_LARGE). Los fallos de persistencia pueden aparecer como DYNAMODB_ERROR. PATCH /v1/schedule-defaults puede devolver SCHEDULE_DEFAULTS_SAVE_FAILED (HTTP 400) con detalles.
| Código | Significado |
|---|---|
| INVALID_JSON | El cuerpo no es JSON válido. |
| PAYLOAD_TOO_LARGE | La longitud en bytes UTF-8 supera maxPayloadBytes (por defecto 512 KiB). |
| TYPE_ERROR | Tipo JSON incorrecto o cadena apiVersion no admitida. |
| UNKNOWN_FIELD | Modo estricto: propiedad no permitida en la raíz o en staff. |
| INVALID_TIME_ZONE | timeZone ausente o no es un nombre IANA válido. |
| INVALID_DATE_RANGE | Fechas no YYYY-MM-DD, rango inválido o enumeración vacía. |
| SCHEDULE_SPAN_TOO_LONG | Demasiados días entre inicio y fin (véase maxScheduleDays). |
| INVALID_TIME_RANGE | Rango horario ausente o genera cero slots. |
| INVALID_GRANULARITY | slotGranularityMinutes no es 60/15 o no permitido en el plan. |
| INVALID_REQUIREMENTS | requirementsByCell no es objeto o el recuento no es entero 0–15. |
| UNKNOWN_CELL_KEY | Clave no está en la rejilla de planificación calculada. |
| INVALID_STAFF | staff vacío, demasiado grande, fila inválida o sanitización fallida. |
| DUPLICATE_STAFF_ID | Valores staffId duplicados. |
| INVALID_AVAILABLE_CELL | Entrada vacía o desconocida en availableCells. |
| SHORTFALL_CELLS | Disponibilidad insuficiente frente a las necesidades. |
| DYNAMODB_ERROR | Error transitorio o de persistencia tras la validación (depende del manejador). |
| SCHEDULE_DEFAULTS_SAVE_FAILED | PATCH /v1/schedule-defaults: validación o reglas de negocio fallidas (véase error.details). |
| LABOR_COMPLIANCE_REQUIRED | PATCH /v1/staff/{staffId}: laborConstraintMask enviado con laborLawCompliance en false. |
{
"apiVersion": "2026-04-01",
"timeZone": "Asia/Tokyo",
"scheduleStartDate": "2026-04-07",
"scheduleEndDate": "2026-04-13",
"timeRangeStart": "08:00",
"timeRangeEnd": "20:00",
"slotGranularityMinutes": 60,
"requirementsByCell": {
"2026-04-07__slot-0": 2
},
"staff": [
{
"staffId": "550e8400-e29b-41d4-a716-446655440000",
"displayName": "Example",
"availableCells": ["2026-04-07__slot-0"]
}
]
}Más información. Planes y funciones de pago: docs/architecture/NURSE_SCHEDULING_SERVICE_SPECIFICATION.md. Cuerpo POST /v1/schedule: docs/data-and-api/PUBLIC_API_SCHEDULE_REQUEST_BODY.md §1–§11. PATCH de valores predeterminados del inquilino: mismo archivo §12. Código: app/lib/public-schedule-api/, app/features/schedule-settings/schedule-defaults-actions.ts, app/lib/public-api-write/weekly-shift-wish-tenant.ts. Despliegue: docs/aws/CDK_DEPLOY.md.