Skip to Content
Changelog e versionamento

Changelog

Histórico de mudanças da Kinmu Public API. Mudanças incompatíveis nunca são aplicadas dentro de uma versão maior: elas entram em uma nova versão e são anunciadas aqui.

Política de versionamento

  • A versão vai na URL: https://api.kinmu.app/v1.
  • Contrato congelado dentro da v1. Não introduzimos mudanças incompatíveis na v1.

O que consideramos uma mudança compatível (não quebra)

Estas mudanças podem acontecer na v1 sem aviso prévio; sua integração deve tolerá-las:

  • Adicionar novos endpoints ou recursos.
  • Adicionar novos campos a uma resposta.
  • Adicionar novos valores a um enum documentado como extensível (por exemplo, tipos de ausência custom).
  • Adicionar parâmetros opcionais de query ou de body.
  • Mudar o texto de mensagens de erro (title, detail) — por isso sua lógica deve se basear no campo estável code.

Escreva clientes tolerantes. Ignore campos que você não conhece e não assuma uma ordem fixa nas listas. Assim as mudanças compatíveis não afetam você.

O que consideramos uma mudança incompatível (quebra)

Exige uma nova versão maior (v2):

  • Remover ou renomear um endpoint, campo ou valor de enum.
  • Mudar o tipo de um campo ou torná-lo obrigatório.
  • Mudar o significado de um campo ou o código de um erro.

Política de descontinuação (12 meses)

Quando descontinuarmos um endpoint, campo ou versão:

  1. O anúncio é feito neste changelog e na lista de e-mail de desenvolvedores.
  2. O item é marcado como deprecated no spec OpenAPI e, quando aplicável, com os headers de resposta Deprecation + Sunset.
  3. Ele segue operacional por pelo menos 12 meses a partir do anúncio antes de ser retirado.

Inscreva-se nos avisos na página de suporte.

Histórico

Todas as alterações listadas abaixo são compatíveis: nenhuma quebra uma integração v1 existente. Estão documentadas aqui porque mudam o comportamento observável.

2026-08-27 — spec OpenAPI e updated_since

  • A spec declara agora os códigos 402 e 409 e os cabeçalhos X-RateLimit-*, que a API já emitia.
  • O 409 passa a estar declarado também em POST /v1/reports e nas operações idempotentes de webhooks, onde faltava.
  • updated_since implementado em GET /v1/webhook-endpoints.
  • updated_since marcado como obsoleto (deprecated) em GET /v1/vacation-balances e GET /v1/work-summaries: nesses recursos nunca filtrou. Continua a ser aceite sem efeito — para não partir os SDK regerados — e será removido a 27-08-2027, conforme a política de descontinuação de 12 meses. Para estes agregados, volte a consultar o intervalo (year, from/to). Veja as convenções.

2026-08-20 — email do colaborador único por empresa

  • A unicidade do email ao criar um colaborador passa a ser por empresa (antes era global). As criações que antes falhavam com 422 por colisão com o email de outra empresa passam a ser aceites.

2026-08-10 — a sandbox e as chaves são desaprovisionadas

  • Ao desativar o addon Public API são revogadas todas as chaves de API (motivo addon_disabled), são eliminados os relatórios gerados e é eliminada a empresa sandbox com os seus dados. Reativar o addon aprovisiona uma sandbox vazia e não repõe as chaves. Veja sandbox.

2026-07-31 — gate de subscrição e revogação

  • O gate de subscrição fica mais rígido: período experimental esgotado, subscrição cancelada e já terminada, subscrição expirada e empresa arquivada devolvem agora 403 subscription_inactive no /v1.
  • Revogar chaves de API e webhooks (DELETE) deixa de exigir subscrição ativa: cortar uma credencial é um controlo de segurança e tem de estar sempre disponível.

2026-07-30 — definições da empresa na emissão de chaves

  • A emissão de chaves de API respeita as definições do addon por empresa: default_expiration_days (expiração aplicada quando não pede uma explícita) e max_active_keys (limite de chaves ativas, 10 por omissão).

v1 · 1.0.0

Spec OpenAPI publicado (openapi-v1.json, v1.0.0). A referência interativa lê o spec real. A superfície da v1 é contrato congelado; as mudanças são anunciadas aqui com a política de descontinuação de 12 meses.

Recursos do lançamento (MVP):

  • Organization — GET /v1/organization (introspecção).
  • Employees — listar, obter, criar, atualizar e desligar.
  • Check-ins — listar, obter e registrar pontos.
  • Work summaries — agregados de jornada para a folha de pagamento.
  • Absences — listar, obter, criar, aprovar e recusar.
  • Vacation balances — saldos de férias.
  • Locations / Units — estrutura organizacional (somente leitura).
  • Reports — relatórios assíncronos (registro legal de jornada e exports), com download do arquivo via GET /v1/reports/{id}/download.

Webhooks:

  • Eventos de saída assinados (Standard Webhooks): gestão de endpoints, envio de ping, listagem de entregas e reenfileiramento manual de uma entrega via POST /v1/webhook-endpoints/{id}/deliveries/{deliveryId}/retry.
Last updated on
Referência da APISuporte