Rondleiding
Ervaringen
Prijs
Inloggen Meld je gratis aan!

Timi API Documentatie

Algemeen

Klanten

Projecten

Activititeiten

Geregistreerde uren

Authenticatie voorbeeld

Voor de Timi API moet je een Timi account hebben. Om een Timi account te maken ga je naar timiapp.com/aanmelden. Als je een account hebt kan met je unieke API token verbinding maken met onze API. Deze token kan je vinden door in te loggen en naar je profiel te gaan. Deze token gebruik je altijd in combinatie met je e-mail adres.

Je kan op drie manieren de token en het e-mail adres doorgeven:

  1. X-Api-Key header

    Via de X-Api-Key header combineer je je e-mail en token in één header:

    curl -X GET 'https://timiapp.com/api/v1/services.json' \
    -H 'X-Api-Key: [email protected]:abc123xyz123'
  2. Basic Auth

    Authenticatie via HTTP Basic Authentication.

  3. URL parameters

    Via de URL parameters token en email:

    curl -X GET 'https://timiapp.com/api/v1/[email protected]&token=abc123xyz123'

Als het inloggen niet goed gaat krijg je het volgende JSON response met een HTTP 401 code:

{
  "message": "unauthorized"
}
Terug naar boven

Rate limiting

Om misbruik van de API te voorkomen hebben we rate limiting ingebouwd. Dit betekent dat je maar een beperkt aantal requests per minuut kan doen. Als je te veel requests doet krijg je een HTTP 429 code terug. Hieronder zie je een voorbeeld van een response.

{"message":"rate limit exceeded"}
Terug naar boven

Klanten

Doormiddel van deze call haal je klanten op die de gebruiker op. Een voorbeeld:

GET /api/v1/clients.json
curl -X GET 'https://timiapp.com/api/v1/[email protected]&token=abc123xyz123'

Je krijgt dan een JSON resultaat wat er als volgt uit ziet:

[
  {
    "id": 618,
    "name": "Klant A",
    "projects": [
      {
        "id": 3327,
        "name": "Banners",
        "aliases": [
          "Erik",
          "Martijn",
          "Wilco"
        ]
      }
    ]
  }
]
Terug naar boven

Projecten

Het is mogelijk om de projecten en persoonlijke aliasen op te halen.

GET /api/v1/projects.json
curl -X GET 'https://timiapp.com/api/v1/[email protected]&token=abc123xyz123'

Je krijgt dan een JSON resultaat wat er als volgt uit ziet:

[
  {
    "id": 2,
    "name": "Timi",
    "aliases": [
      "Jankees",
      "Rowan",
      "Tango"
    ]
  }
]
Terug naar boven

Projecten

Projecten aanmaken via de API kan als volgt.

POST /api/v1/projects.json
curl -X POST https://timiapp.com/api/v1/projects.json \
  -d 'name=Nieuw project' \
  -d 'active=true' \
  -d 'token=abc123xyz123' \
  -d '[email protected]'
Attribuut Verplicht/optioneel Uitleg
name
 verplicht De naam van het nieuwe project
active
 optioneel Is het project actief? (of gearchiveerd) deze optie staat standaard op actief. (opties: true / false)

Je krijgt dan een JSON resultaat wat er als volgt uit ziet:

{
    "active": true,
    "aliases": [],
    "id": 42,
    "name": "Nieuw project"
}
Terug naar boven

Het is ook mogelijk om projecten aan te passen via de API

PATCH /api/v1/projects/{ID}.json
curl -X PATCH http://timi.dev/api/v1/projects/42.json \
  -d 'name=Nieuwe naam' \
  -d 'token=abc123xyz123' \
  -d '[email protected]'

Je krijgt dan een JSON resultaat wat er als volgt uit ziet:

{
    "active": true,
    "aliases": [],
    "id": 42,
    "name": "Nieuwe naam"
}
Terug naar boven

Activiteiten

Het is mogelijk om de activiteiten en persoonlijke aliasen op te halen.

GET /api/v1/services.json
curl -X GET 'https://timiapp.com/api/v1/[email protected]&token=abc123xyz123'

Je krijgt dan een JSON resultaat wat er als volgt uit ziet:

{
    "id": 1,
    "name": "Development",
    "aliases": [
      "coden",
      "css",
      "html",
      "programmeren",
      "rails"
    ]
  }
Terug naar boven

Geregistreerde uren

Het belangrijkste object binnen Timi zijn de geregistreerde uren van een gebruiker Deze kun je ophalen met behulp van je API token (zie authenticatie).

GET /api/v1/time_entries.json

In het onderstaande voorbeeld halen we pagina 2 van de uren van een gebruiker op:

curl -X GET 'https://timiapp.com/api/v1/[email protected]&token=abc123xyz123&page=2'
Attribuut Verplicht/optioneel Uitleg
date
 optioneel De datum voor de uren
start_date
 optioneel Filter de uren vanaf deze datum
end_date
 optioneel Filter de uren tot en met deze datum
project_ids
 optioneel Filter de uren gebaseerd op project id (komma gescheiden)
service_ids
 optioneel Filter de uren gebaseerd op service id (komma gescheiden)
client_ids
 optioneel Filter de uren gebaseerd op service id (komma gescheiden)
page
 optioneel De huidige pagina

Je krijgt dan een JSON resultaat wat er als volgt uit ziet:

{
  "current_page": 2,
  "per_page": 100,
  "total_entries": 102,
  "time_entries": [
    {
      "id": 108085,
      "body": "8 uur voor Timi gewerkt vanuit huis",
      "duration": 28800,
      "start_time": "",
      "end_time": "",
      "date": "2016-01-20",
      "project": {
        "id": 3327,
        "name": "Website",
        "client": {
          "id": 1,
          "name": "Timi"
        }
      },
      "user": {
        "id": 1,
        "display_name": "Jankees"
      }
    },
    {
      "id": 107991,
      "body": "1 uur voor Timi vanuit huis",
      "duration": 3600,
      "start_time": "",
      "end_time": "",
      "date": "2016-01-19",
      "project": {
        "id": 3327,
        "name": "Website",
        "client": {
          "id": 1,
          "name": "Timi"
        }
      },
      "user": {
        "id": 2,
        "display_name": "Rowan"
      }
    }
  ]
}
POST /api/v1/time_entries.json
Let op! De Api van Timi is nog ontwikkeling, controlleer altijd goed wat je aangemaakt hebt via de API.

Ook de tekstherkenning van Timi is te gebruiken via de API, hieronder zie je een voorbeeld:

curl -X POST https://timiapp.com/api/v1/time_entries.json \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'body=2,5 uur met Rowan aan Timi gewerkt' \
  -d 'token=abc123xyz123' \
  -d '[email protected]'
Attribuut Verplicht/optioneel Uitleg
body
 verplicht Dit is de tekst waarop Timi tekstherkenning toepast
date
 optioneel Dit is de datum van de registratie, bijvoorbeeld 27-03-2016
service_id
 optioneel Dit is het
id
van de activiteit die je wil gebruiken (dit overschrijft de activiteit die gevonden is door de tekstherkenning)
project_id
 optioneel Dit is het
id
van het project die je wil gebruiken (dit overschrijft het project dat gevonden is door de tekstherkenning)
duration
 optioneel Hiermee kan je de herkende tijd overschrijven (de duration is in secondes)

Als de registratie goed is opgeslagen krijg je het restultaat te zien:

{
    "id": 123979,
    "body": "2,5 uur met Rowan aan Timi gewerkt",
    "date": "2016-03-28",
    "duration": 9000,
    "start_time": null,
    "end_time": null,
    "project": {
        "id": 47,
        "name": "Timi"
    }
}

Het kan echter ook mis gaan, dan krijg je een "errors" object terug:

{
  "errors": {
    "duration": [
      "is geen getal"
    ]
  }
}
PATCH /api/v1/time_entries/[id].json

Naast het aanmaken van een registratie kan je er ook een bewerken, daarvoor kan je dezelfde attributen gebruiken als bij het aanmaken.

curl -X PATCH https://timiapp.com/api/v1/time_entries/123968.json \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'token=abc123xyz123' \
  -d '[email protected]' \
  -d 'body=10 uur met Rowan gewerkt'

Het is ook mogelijk om te kijken of er een timer loopt, dat doe je met deze call:

GET /api/v1/time_entries/timer.json
{
   "id":1035,
   "body":"Mijn timer",
   "duration":720,
   "start_time":null,
   "end_time":null,
   "date":"2017-01-26",
   "timer_started_at":"2017-01-26T13:33:51.453+01:00"
}

Je krijgt dat dit als resultaat:

Terug naar boven