Toggl API 호환성
쓰던 Toggl 스크립트, CLI, 에이전트를 OpenTickly로 옮기는 방법입니다. 어떤 URL을 쓰는지, API 토큰으로 어떻게 인증하는지, 옮기기 전에 무엇을 테스트할지 정리했습니다.
OpenTickly는 Toggl과 같은 API를 씁니다. Toggl용으로 만든 스크립트, CLI, 에이전트는 URL과 토큰만 바꾸면 OpenTickly 인스턴스와 통신할 수 있습니다. 따라가는 Toggl API는 Track v9, Reports v3, Webhooks v1 세 가지입니다.
기본 URL
https://your-instance.example을 내 OpenTickly 서버의 공개 주소로 바꿔서 쓰세요.
| API | 기본 URL |
|---|---|
| Track v9 | https://your-instance.example/api/v9 |
| Reports v3 | https://your-instance.example/reports/api/v3 |
| Webhooks v1 | https://your-instance.example/webhooks/api/v1 |
인터넷을 통해 접속한다면 HTTPS를 붙이세요. Docker 컨테이너 자체는 일반 HTTP만 제공하므로, 보통 Nginx나 Caddy 같은 리버스 프록시에서 HTTPS를 처리합니다.
API 토큰 받기
OpenTickly 웹 앱에 로그인해 아바타 메뉴에서 프로필을 열고 API 토큰을 찾으세요. 토큰은 비밀번호처럼 다뤄야 합니다. git에 커밋하거나, 이슈에 붙여 넣거나, 로그에 찍지 마세요.
인증 방식은 Toggl과 같습니다. HTTP Basic 인증에서 사용자명에 토큰을, 비밀번호에 api_token이라는 문자열을 그대로 넣습니다.
curl --user "${OPENTICKLY_API_TOKEN}:api_token" \
https://your-instance.example/api/v9/me먼저 셸에 OPENTICKLY_API_TOKEN을 설정해 두세요. 내 사용자 정보가 돌아오면 토큰이 제대로 동작하는 겁니다.
쓰던 도구를 OpenTickly로 바꾸기
대부분의 도구는 두 가지만 바꾸면 됩니다.
- Toggl API 주소를 위 표에 있는 OpenTickly 주소로 바꿉니다.
- Toggl 토큰 대신 OpenTickly API 토큰을 씁니다.
toggl-cli라면 이렇게 합니다.
toggl auth <YOUR_API_TOKEN> \
--api-type opentoggl \
--api-url https://your-instance.example/api/v9Toggl 주소가 앱 안에 박혀 있고 바꿀 설정이 없는 서드파티 앱은 OpenTickly에 연결할 수 없습니다.
옮기기 전에 테스트하기
API 전체가 아니라, 내 도구가 실제로 보내는 요청을 테스트하세요. 본격적으로 쓰기 전에:
GET /api/v9/me로 현재 사용자를 불러옵니다.- 워크스페이스, 프로젝트, 태그, 최근 시간 항목 목록을 불러옵니다.
- 테스트용 시간 항목을 만들고 정지합니다.
- 스크립트에서 쓰는 리포트 쿼리를 그대로 실행해 봅니다.
- 웹훅을 쓴다면 테스트용 구독을 만들고, 끝나면 삭제합니다.
- 오류 처리, 페이지네이션, 날짜, 시간대를 확인합니다.
아직 모든 Toggl 엔드포인트가 똑같이 동작하지는 않습니다. Toggl에서는 되는데 OpenTickly에서 안 되는 게 있다면 보낸 요청과 받은 응답을 담아 GitHub 이슈를 열어 주세요.
알아서 돌아가는 스크립트라면 URL과 토큰을 코드에 직접 쓰지 말고, 필요한 워크스페이스에만 접근할 수 있는 계정을 쓰고, 토큰이 유출되면 재설정하세요.