ForHosting KIT · Ferramentas para dev

Fração do ano decorrida

Esta calculadora de progresso anual retorna a fração do ano civil UTC decorrida em uma data e hora ISO 8601 explícita.

● BetaGrátis · no seu navegador

Use pelo WebAPIE-mailTelegramApp em breve

Ela converte para UTC o horário informado com Z ou deslocamento numérico, mede os milissegundos exatos desde 1º de janeiro às 00:00:00 UTC e divide essa duração pelo comprimento total do ano UTC resultante. Anos bissextos têm 366 dias; anos comuns têm 365. A data atual, o fuso horário local, a rede, valores aleatórios e padrões ocultos não afetam a resposta.

O que significa a fração do ano decorrida

A fração retornada é uma medida contínua do progresso dentro de um ano civil UTC. O numerador é o número de milissegundos desde 1º de janeiro às 00:00:00.000 UTC até o instante informado, e o denominador é o número de milissegundos de todo esse ano UTC. No primeiro instante de 1º de janeiro, o resultado é exatamente zero. Depois, ele aumenta ao longo do ano, mas permanece abaixo de um para qualquer data e hora válida desse ano; um pertence ao primeiro instante do ano seguinte, quando um novo cálculo recomeça em zero. Isso difere de uma porcentagem baseada no dia do ano que conta datas inteiras ou considera o dia atual completamente transcorrido. O meio-dia contribui com metade daquela data, os segundos entram com sua parcela exata e até três casas de segundo são preservadas como milissegundos. O denominador tem 365 dias em um ano comum e 366 em um ano bissexto gregoriano. Como o deslocamento é normalizado antes da escolha do ano UTC, um instante escrito no fim de 31 de dezembro em outro fuso pode pertencer corretamente a 1º de janeiro do próximo ano UTC.

Como informar uma data e hora ISO sem ambiguidade

Envie datetime no formato YYYY-MM-DDTHH:mm:ssZ. Você pode acrescentar de uma a três casas decimais de segundo ou trocar Z por um deslocamento com sinal, como +05:30 ou -04:00. O indicador de fuso é obrigatório porque uma data e hora sem ele não representa um único instante. Datas sem horário, formatos locais, nomes de meses, espaços no lugar de T e deslocamentos sem dois-pontos são rejeitados, sem tentativa de adivinhação. O analisador também valida os comprimentos dos meses gregorianos, dias bissextos, horas, minutos, segundos e campos do deslocamento. Segundos intercalares não são aceitos: o campo de segundos vai de 00 a 59, conforme o modelo determinístico de minuto civil usado no cálculo. Depois da análise, o deslocamento é aplicado com aritmética inteira e o instante resultante aparece em utc_datetime. A resposta também apresenta utc_year, elapsed_milliseconds e year_milliseconds, permitindo que você audite a fração sem reconstruir as regras do calendário. Duas strings que descrevem o mesmo instante com deslocamentos diferentes geram a mesma data normalizada e a mesma fração. Uma solicitação automatizada bem-sucedida custa US$ 0,002; o cálculo também pode ser executado localmente no navegador.

Onde uma proporção anual determinística é útil

Use esta capacidade quando um modelo, uma visualização, um relatório ou um teste precisar de uma posição estável no ano civil, em vez de uma resposta vinculada ao momento em que uma máquina é executada. Painéis podem transformar a fração em porcentagem ou barra de progresso e manter o numerador e o denominador exatos para rótulos e auditorias. Pipelines de dados podem enriquecer registros com carimbo de data e hora usando uma coordenada anual normalizada para análise sazonal, interpolação ou variáveis cíclicas, sabendo que entradas com deslocamento são comparadas na mesma linha do tempo UTC. Testes podem fixar casos limítrofes no Ano-Novo, no dia bissexto ou no último milissegundo de dezembro sem simular um relógio. Como o resultado se baseia na duração decorrida, ele não deve ser usado para contar datas concluídas, dias úteis, períodos fiscais ou meses de igual duração. O cálculo também modela deliberadamente dias civis UTC com 86.400 segundos e não insere segundos intercalares, tornando a operação portátil e reproduzível. Se você precisar de uma porcentagem, multiplique fraction por cem e arredonde apenas na exibição. Para uma proporção fiscal, use os limites do calendário fiscal adequado.

Casos de uso

Painéis de progresso anual

Converta um carimbo de data e hora explícito em uma posição exata de zero a um no ano UTC para barras de progresso e indicadores KPI.

Variáveis para análise sazonal

Adicione uma coordenada anual contínua e consistente aos registros temporais depois de normalizar seus deslocamentos explícitos para UTC.

Testes determinísticos de limites

Crie dados de teste reproduzíveis perto do Ano-Novo e do dia bissexto sem consultar nem simular o relógio do sistema.

Perguntas frequentes

A fração pode ser igual a um?

Não para um instante dentro do ano UTC selecionado. O primeiro instante do ano seguinte pertence ao novo ano e retorna zero.

Como os anos bissextos são tratados?

O denominador usa 366 dias quando o ano UTC é divisível por quatro, exceto anos de século não divisíveis por quatrocentos; caso contrário, usa 365 dias.

Por que o fuso horário é obrigatório?

Sem Z ou um deslocamento numérico, uma data e hora ISO local não identifica um único instante UTC e pode gerar respostas diferentes entre ambientes.

O cálculo inclui segundos intercalares?

Não. Ele usa dias civis fixos de 86.400 segundos e aceita segundos de 00 a 59, oferecendo uma proporção de calendário portátil e determinística.

Quanto custa uma solicitação de API?

Um cálculo bem-sucedido pela API custa US$ 0,002 por solicitação. A mesma operação pura também está disponível no navegador.

Para desenvolvedores — acesso via API

Tudo nesta página está disponível via API. Esta seção é para equipes que querem integrar a ferramenta aos próprios sistemas; quem não precisa disso pode simplesmente usar a ferramenta acima.

Endpoint

POSThttps://api.kit.forhosting.com/date/fraction-of-year-elapsed

Autenticação por token Bearer. Um único POST coloca a tarefa na fila; o resultado chega por webhook ou link assinado.

Chame do seu código

curl -X POST https://api.kit.forhosting.com/date/fraction-of-year-elapsed \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"datetime":"2026-07-02T12:00:00Z"}'

const res = await fetch("https://api.kit.forhosting.com/date/fraction-of-year-elapsed", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "datetime": "2026-07-02T12:00:00Z"
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/date/fraction-of-year-elapsed",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "datetime": "2026-07-02T12:00:00Z"
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/date/fraction-of-year-elapsed", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"datetime":"2026-07-02T12:00:00Z"}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"datetime":"2026-07-02T12:00:00Z"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/date/fraction-of-year-elapsed", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

Exemplo de requisição

{
  "datetime": "2026-07-02T12:00:00Z"
}

Exemplo de resposta

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "date.fraction_of_year_elapsed",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

A API é assíncrona: cada chamada devolve um task_id na hora. Se preferir polling, consulte o status a até 1 requisição por segundo.

Preço

por chamadaUS$ 0,002

Preço publicado, sem tokens nem créditos escondidos. Tarefa que falha não é cobrada.

Erros

HTTP	Código	O que significa
`401`	`unauthorized`	Token ausente ou inválido. Confira o header Authorization.
`402`	`insufficient_balance`	Saldo insuficiente para esta tarefa. Faça uma recarga e tente de novo.
`404`	`unknown_type`	Esse tipo de tarefa não existe. Confira o campo type no catálogo.
`429`	`rate_limited`	Muitas requisições em pouco tempo. Espere um instante e tente de novo.

Ver a documentação completa do KIT →