Compatibilité avec l'API Toggl

OpenTickly parle la même API que Toggl. Les scripts, CLI et agents écrits pour Toggl peuvent dialoguer avec votre instance OpenTickly dès que vous changez l'URL et le jeton. Nous suivons trois API de Toggl : Track v9, Reports v3 et Webhooks v1.

URL de baseCopy Anchor Link

Remplacez https://votre-instance.example par l'URL publique de votre serveur OpenTickly.

Si des clients accèdent à votre instance par Internet, passez-la en HTTPS. Le conteneur Docker ne sert que du HTTP simple : le HTTPS est donc généralement géré par un reverse proxy comme Nginx ou Caddy.

Obtenir un jeton d'APICopy Anchor Link

Connectez-vous à l'application web d'OpenTickly, ouvrez le menu de votre avatar, choisissez Profil et cherchez Jeton API. Traitez ce jeton comme un mot de passe : ne le mettez pas dans git, ne le collez pas dans une issue et ne l'affichez pas dans des logs.

L'authentification fonctionne comme chez Toggl : HTTP Basic, avec le jeton comme nom d'utilisateur et la chaîne api_token telle quelle comme mot de passe :

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

Définissez d'abord OPENTICKLY_API_TOKEN dans votre shell. Si vous récupérez vos informations d'utilisateur, le jeton fonctionne.

Faire passer un outil existant sur OpenTicklyCopy Anchor Link

La plupart des outils n'ont besoin que de deux changements :

1. Remplacer l'adresse de l'API Toggl par votre adresse OpenTickly (voir le tableau ci-dessus).
2. Utiliser votre jeton d'API OpenTickly à la place de celui de Toggl.

Pour toggl-cli :

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

Si une application tierce a l'adresse de Toggl codée en dur, sans réglage pour la changer, elle ne pourra pas être redirigée vers OpenTickly.

Tester avant de basculerCopy Anchor Link

Testez les requêtes que votre outil fait vraiment, pas toute l'API. Avant de compter dessus :

1. Récupérez l'utilisateur courant avec GET /api/v9/me.
2. Listez votre espace de travail, vos projets, vos tags et vos entrées de temps récentes.
3. Créez puis arrêtez une entrée de temps de test.
4. Lancez la même requête de rapport que votre script.
5. Si vous utilisez les webhooks, créez un abonnement de test puis supprimez-le.
6. Vérifiez la gestion des erreurs, la pagination, les dates et les fuseaux horaires.

Tous les endpoints de Toggl ne se comportent pas encore exactement de la même façon. Si quelque chose marche sur Toggl mais pas sur OpenTickly, ouvrez une issue GitHub avec la requête et la réponse obtenue.

Pour les scripts qui tournent tout seuls, gardez l'URL et le jeton hors du code, utilisez un compte qui n'a accès qu'aux espaces de travail nécessaires, et régénérez le jeton s'il fuite.