API Reference — Horas PJ

Autenticação

A API utiliza Bearer Token. Envie o token em todas as requisições via header Authorization.

Como gerar um token

Acesse Configurações → seção Tokens de API
Digite um nome para identificar o token (ex: "Zapier", "Script Python")
Clique em Gerar Token
Copie o token exibido — ele não será exibido novamente

Usando o token

# Exemplo curl
curl -X GET https://horas.jonathantolotti.com.br/api/v1/me \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Accept: application/json"
            

Erros

Todos os erros retornam JSON com o campo message. Erros de validação incluem o campo errors.

Código	Significado
`401`	Token ausente ou inválido
`403`	Sem permissão (ex: recurso Premium)
`404`	Recurso não encontrado
`422`	Erro de validação — veja o campo `errors`
`429`	Rate limit excedido
`500`	Erro interno do servidor

// Exemplo de erro de validação (422)
{
  "message": "The date field is required.",
  "errors": {
    "date": ["The date field is required."],
    "start_time": ["The start time field is required."]
  }
}
            

Rate Limiting

Limite de 60 requisições por minuto por token. Quando excedido, a API retorna HTTP 429. Os headers X-RateLimit-Limit e X-RateLimit-Remaining indicam os limites em cada resposta.

Usuário

Retorna os dados do usuário autenticado.

GET /api/v1/me Grátis

// Resposta 200
{
  "data": {
    "id": 1,
    "name": "João Silva",
    "email": "[email protected]",
    "is_premium": true,
    "plan": "premium"
  }
}
                

Lançamentos de Horas

GET /api/v1/time-entries Grátis

Lista os lançamentos do mês. Paginado em 50 por página.

Parâmetros de query

Parâmetro	Tipo	Descrição
month	string opcional	Mês no formato `YYYY-MM`. Padrão: mês atual.
page	integer opcional	Número da página. Padrão: 1.

// Resposta 200
{
  "data": [
    {
      "id": 42,
      "date": "2026-05-02",
      "start_time": "09:00",
      "end_time": "12:00",
      "hours": 3,
      "description": "Desenvolvimento de features",
      "project": { "id": 1, "name": "Projeto Alpha" }
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "total": 15, "month": "2026-05" }
}
                

GET /api/v1/time-entries/stats Grátis

Retorna as estatísticas mensais (horas, receita, etc.).

Parâmetro	Tipo	Descrição
month	string opcional	Mês no formato `YYYY-MM`. Padrão: mês atual.

POST /api/v1/time-entries Grátis

Cria um novo lançamento de horas.

Body (JSON)

Campo	Tipo	Descrição
date	string obrigatório	Data no formato `YYYY-MM-DD`
start_time	string obrigatório	Hora de início `HH:MM`
end_time	string obrigatório	Hora de fim `HH:MM`
project_id	integer opcional	ID do projeto
description	string opcional	Descrição do trabalho

// Exemplo
{
  "date": "2026-05-02",
  "start_time": "09:00",
  "end_time": "12:30",
  "project_id": 1,
  "description": "Desenvolvimento de features"
}
                

DELETE /api/v1/time-entries/{id} Grátis

Exclui um lançamento. Retorna HTTP 200 com mensagem de confirmação.

Projetos

GET /api/v1/projects Grátis

Lista os projetos ativos do usuário.

POST /api/v1/projects Grátis

Cria um novo projeto.

Campo	Tipo	Descrição
name	string obrigatório	Nome do projeto
active	boolean opcional	Padrão: `true`
is_default	boolean opcional	Projeto padrão para tracking automático
default_description	string opcional	Descrição padrão ao salvar tracking

PUT /api/v1/projects/{id} Grátis

Atualiza um projeto. Mesmos campos do POST.

DELETE /api/v1/projects/{id} Grátis

Exclui um projeto.

Empresas

GET /api/v1/companies Grátis

Lista as empresas do usuário.

GET /api/v1/companies/{id} Grátis

Retorna os dados de uma empresa específica, incluindo endereço e responsável.

POST /api/v1/companies Grátis

Cria uma nova empresa.

Campo	Tipo	Descrição
name	string obrigatório	Nome fantasia
cnpj	string obrigatório	CNPJ no formato `XX.XXX.XXX/XXXX-XX`
active	boolean opcional	Padrão: `true`
razao_social	string opcional	Razão social
email	string opcional	E-mail de contato
telefone	string opcional	Telefone
cep / logradouro / numero / bairro / cidade / uf	string opcional	Endereço

PUT /api/v1/companies/{id} Grátis

Atualiza uma empresa. Mesmos campos do POST.

DELETE /api/v1/companies/{id} Grátis

Exclui uma empresa.

Configurações

GET /api/v1/settings Grátis

Retorna as configurações do usuário (valor/hora, extras, descontos, etc.).

PUT /api/v1/settings Grátis

Atualiza as configurações do usuário.

Campo	Tipo	Descrição
hourly_rate	number opcional	Valor por hora (R$)
extra_value	number opcional	Valor extra fixo (R$)
discount_value	number opcional	Desconto fixo (R$)
on_call_hourly_rate	number opcional	Valor por hora de sobreaviso (R$)
auto_save_tracking	boolean opcional	Salvar tracking automaticamente

Tracking

Controle o tracking de horas em tempo real.

GET /api/v1/tracking Grátis

Retorna o status atual do tracking.

// Resposta quando ativo
{ "data": { "active": true, "started_at": "2026-05-02T09:00:00Z" } }

// Resposta quando inativo
{ "data": { "active": false, "started_at": null } }
                

POST /api/v1/tracking/start Grátis

Inicia o tracking. Retorna HTTP 409 se já existe um tracking ativo.

POST /api/v1/tracking/stop Grátis

Para o tracking e retorna as horas trabalhadas. Não salva o lançamento automaticamente — use POST /time-entries para registrar.

// Resposta 200
{
  "data": {
    "started_at": "2026-05-02T09:00:00Z",
    "stopped_at": "2026-05-02T12:30:00Z",
    "hours": 3.5
  }
}
                

Sobreaviso Premium

Gerencie períodos de sobreaviso. Requer assinatura Premium.

GET /api/v1/on-call Premium

Lista os períodos de sobreaviso do mês.

Parâmetro	Tipo	Descrição
month	string opcional	Mês no formato `YYYY-MM`. Padrão: mês atual.

GET /api/v1/on-call/stats Premium

Retorna estatísticas de sobreaviso do mês.

POST /api/v1/on-call Premium

Cria um período de sobreaviso.

Campo	Tipo	Descrição
start_datetime	datetime obrigatório	Início do sobreaviso `YYYY-MM-DD HH:MM`
end_datetime	datetime obrigatório	Fim do sobreaviso `YYYY-MM-DD HH:MM`
hourly_rate	number obrigatório	Valor por hora de sobreaviso (R$)
project_id	integer opcional	ID do projeto vinculado
description	string opcional	Descrição

PUT /api/v1/on-call/{id} Premium

Atualiza um período de sobreaviso. Mesmos campos do POST.

DELETE /api/v1/on-call/{id} Premium

Exclui um período de sobreaviso.