Changelog

Historial de cambios de la Kinmu Public API. Los cambios incompatibles nunca se aplican dentro de una versión mayor: se introducen en una nueva versión y se anuncian aquí.

Política de versionado

• La versión va en la URL: https://api.kinmu.app/v1.
• Contrato congelado dentro de v1. No introducimos cambios incompatibles en v1.

Qué consideramos un cambio compatible (no rompe)

Estos cambios pueden ocurrir en v1 sin previo aviso; tu integración debe tolerarlos:

• Añadir nuevos endpoints o recursos.
• Añadir campos nuevos a una respuesta.
• Añadir valores nuevos a un enum documentado como extensible (p. ej. tipos de ausencia custom).
• Añadir parámetros opcionales de query o de body.
• Cambiar el texto de mensajes de error (title, detail) — por eso tu lógica debe basarse en el campo estable code.

Qué consideramos un cambio incompatible (rompe)

Requiere una nueva versión mayor (v2):

• Eliminar o renombrar un endpoint, campo o valor de enum.
• Cambiar el tipo de un campo o hacerlo obligatorio.
• Cambiar el significado de un campo o el código de un error.

Política de deprecación (12 meses)

Cuando deprequemos un endpoint, campo o versión:

1. Se anuncia en este changelog y en la lista de correo de desarrolladores.
2. Se marca como deprecated en el spec OpenAPI y, cuando aplique, con la cabecera de respuesta Deprecation + Sunset.
3. Se mantiene operativo al menos 12 meses desde el anuncio antes de retirarse.

Suscríbete a los avisos en la página de soporte.

Historial

2026-10-28 — revisión de seguridad y coherencia

Añadido

• GET /v1/absence-types (scope org:ausencias:read): el catálogo de tipos de ausencia activos de tu empresa. Usa sus key al crear y filtrar ausencias.
• El webhook report.completed, que avisa cuando un informe termina. data lleva id y status; pide GET /v1/reports/{id} para obtener la download_url.
• El webhook vacation_balance.updated, que se emite al aprobar o cancelar unas vacaciones. data tiene el mismo formato que una fila de GET /v1/vacation-balances.

Cambiado

• Tipos de ausencia. Las claves reales son holidays, sick-leave y las del catálogo de tu empresa. vacation y sick_leave, que usaban nuestros ejemplos, se siguen aceptando como alias. Un tipo que no está en el catálogo devuelve 422 validation_failed con la lista de claves válidas.
• Saldos de vacaciones. Las medias jornadas salen como decimal (10.5); los días enteros siguen siendo números enteros. carry_over_expires_at indica el último día para disfrutar el arrastre, o null si tu empresa no lo tiene configurado.
• Caducidad de las keys. Las keys nuevas caducan a los 365 días salvo que elijas otro plazo o «sin caducidad». Las existentes no cambian.
• Importar ausencias aprobadas (status_on_create=approved) tiene ahora los mismos efectos que aprobarlas: descuenta saldo y retira los turnos afectados.
• Documentación del gate de suscripción. Corregimos lo que publicamos el 31-07: el 403 subscription_inactive se devuelve con una suscripción suspendida, una prueba terminada o un primer pago sin completar. Una cancelación surte efecto según las condiciones de tu contrato.

Corregido

• Un fichaje out que haría que la jornada se solapara con otra ya registrada devuelve 409 conflict. Antes se aceptaba y las horas se contaban dos veces.
• Un empleado dado de baja solo admite fichajes y ausencias hasta su termination_date; lo posterior devuelve 422 validation_failed. Los atrasados de su último día se siguen aceptando.
• Dos peticiones simultáneas con la misma Idempotency-Key ya no crean dos registros: la segunda recibe 409 idempotency_conflict y puede reintentarse cuando termine la primera.
• En la referencia, la ruta de descarga es GET /v1/reports/{report}/download.

Seguridad

• Una key ya no puede editar ni dar de baja a un administrador de la empresa: devuelve 403 invalid_scope. terminate con una fecha futura devuelve 422 validation_failed, porque v1 no programa bajas.
• Los webhooks se detienen si se desactiva el complemento Public API o la suscripción deja de estar activa. Al desactivar el complemento, los endpoints pasan a disabled y no se reactivan solos.
• Un endpoint creado con una key sin org:ausencias:read recibe los eventos absence.* sin el tipo de ausencia. Los endpoints creados antes de este cambio no se ven afectados.
• El reintento manual de una entrega solo funciona si ha fallado (409 conflict en otro caso). test y retry tienen un límite de 30 peticiones por minuto.
• Tras 60 intentos de autenticación fallidos en un minuto desde la misma IP, los siguientes devuelven 429 rate_limited. Las keys válidas no se ven afectadas.
• Los informes CSV neutralizan las celdas de texto que empiezan por =, +, - o @ para que no se ejecuten como fórmulas. Los números se exportan sin cambios.
• La URL de descarga de un informe deja de funcionar si se revoca la key que lo pidió o si la cuenta pierde el servicio.

2026-08-27 — spec OpenAPI y updated_since

• El spec declara ahora los códigos 402 y 409 y las cabeceras X-RateLimit-*, que la API ya emitía.
• El 409 se declara además en POST /v1/reports y en las operaciones idempotentes de webhooks, donde faltaba.
• updated_since implementado en GET /v1/webhook-endpoints.
• updated_since marcado como obsoleto (deprecated) en GET /v1/vacation-balances y GET /v1/work-summaries: nunca ha filtrado en esos recursos. Se sigue aceptando sin efecto —para no romper los SDK regenerados— y se retirará el 27-08-2027, conforme a la política de deprecación de 12 meses. Para estos agregados, vuelve a consultar el rango (year, from/to). Ver convenciones.

2026-08-20 — email de empleado único por empresa

• La unicidad del email al crear un empleado pasa a ser por empresa (antes era global). Altas que antes fallaban con 422 por colisión con el email de otra empresa ahora se aceptan.

2026-08-10 — la sandbox y las keys se deprovisionan

• Al desactivar el addon Public API se revocan todas las API keys (motivo addon_disabled), se borran los informes generados y se elimina la empresa sandbox con sus datos. Reactivar el addon reprovisiona una sandbox vacía y no restaura las keys. Ver sandbox.

2026-07-31 — gate de suscripción y revocación

• El gate de suscripción se endurece: trial agotado, suscripción cancelada y vencida, suscripción expirada y empresa archivada devuelven ahora 403 subscription_inactive en /v1.
• Revocar API keys y webhooks (DELETE) deja de exigir suscripción activa: cortar una credencial es un control de seguridad y debe estar siempre disponible.

2026-07-30 — ajustes de empresa en la emisión de keys

• La emisión de API keys respeta los ajustes del addon por empresa: default_expiration_days (expiración aplicada cuando no pides una explícita) y max_active_keys (tope de keys activas, 10 por defecto).

v1 · 1.0.0

Recursos del lanzamiento (MVP):

• Organization — GET /v1/organization (introspección).
• Employees — listar, obtener, crear, actualizar y dar de baja.
• Check-ins — listar, obtener y registrar fichajes.
• Work summaries — agregados de jornada para nómina.
• Absences — listar, obtener, crear, aprobar y rechazar.
• Vacation balances — saldos de vacaciones.
• Locations / Units — estructura organizativa (solo lectura).
• Reports — informes asíncronos (registro horario legal y exports), con descarga del fichero vía GET /v1/reports/{report}/download.

Webhooks:

• Eventos salientes firmados (Standard Webhooks): gestión de endpoints, envío de ping, listado de entregas y reencolado manual de una entrega vía POST /v1/webhook-endpoints/{id}/deliveries/{deliveryId}/retry.