Skip to Content
Changelog y versionado

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.

Diseña clientes tolerantes. Ignora los campos que no conozcas y no asumas un orden fijo en las listas. Así los cambios compatibles no te afectan.

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

Todos los cambios listados abajo son compatibles: ninguno rompe una integración v1 existente. Se documentan aquí porque cambian el comportamiento observable.

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

Spec OpenAPI publicado (openapi-v1.json, v1.0.0). La referencia interactiva lee el spec real. La superficie del v1 es contrato congelado; los cambios se anuncian aquí con la política de deprecación de 12 meses.

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/{id}/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.
Last updated on
Referencia APISoporte