Compatibilidade com a API Toggl

O OpenTickly fala a mesma API que o Toggl. Scripts, CLIs e agentes feitos para o Toggl conseguem conversar com a sua instância do OpenTickly depois que você troca a URL e o token. Seguimos três APIs do Toggl: Track v9, Reports v3 e Webhooks v1.

URLs baseCopy Anchor Link

Troque https://sua-instancia.example pela URL pública do seu servidor OpenTickly.

Se os clientes acessam sua instância pela internet, coloque-a atrás de HTTPS. O container Docker em si só serve HTTP simples, então o HTTPS normalmente fica a cargo de um proxy reverso, como Nginx ou Caddy.

Pegue um token de APICopy Anchor Link

Entre no app web do OpenTickly, abra o menu do seu avatar, escolha Perfil e procure API Token. Trate o token como uma senha: não faça commit dele no git, não cole em issues e não imprima em logs.

A autenticação funciona igual à do Toggl: HTTP Basic, com o token como usuário e o texto literal api_token como senha:

curl --user "${OPENTICKLY_API_TOKEN}:api_token" \
  https://sua-instancia.example/api/v9/me

Defina OPENTICKLY_API_TOKEN no terminal antes. Se voltarem os dados do seu usuário, o token está funcionando.

Troque uma ferramenta existente para o OpenTicklyCopy Anchor Link

A maioria das ferramentas só precisa de duas mudanças:

1. Trocar o endereço da API do Toggl pelo endereço do seu OpenTickly, conforme a tabela acima.
2. Usar o token de API do OpenTickly no lugar do token do Toggl.

Para o toggl-cli:

toggl auth <YOUR_API_TOKEN> \
  --api-type opentoggl \
  --api-url https://sua-instancia.example/api/v9

Se um app de terceiros tem o endereço do Toggl fixo no código e não oferece nenhuma opção para mudá-lo, não dá para apontá-lo para o OpenTickly.

Teste antes de trocarCopy Anchor Link

Teste as requisições que a sua ferramenta realmente faz, não a API inteira. Antes de depender dela:

1. Leia o usuário atual com GET /api/v9/me.
2. Liste o espaço de trabalho, os projetos, as tags e os registros de tempo recentes.
3. Crie e pare um registro de tempo de teste.
4. Rode a mesma consulta de relatório que o seu script usa.
5. Se usa webhooks, crie uma assinatura de teste e apague depois.
6. Confira o tratamento de erros, a paginação, as datas e os fusos horários.

Nem todo endpoint do Toggl se comporta exatamente igual ainda. Se algo funciona no Toggl e não no OpenTickly, abra uma issue no GitHub com a requisição e a resposta que você recebeu.

Para scripts que rodam sozinhos, deixe a URL e o token fora do código, use uma conta com acesso só aos espaços de trabalho necessários e gere um token novo se ele vazar.