Jobstaff API

Ja, wir haben eine API für Entwickler. Genauer: einen RESTful Webservice auf Basis von JSON. Bitte benutzen Sie GET-, POST- oder HEAD-Requests. Wie Sie diese API genau nutzen können, wollen wir Ihnen nicht verheimlichen. Los gehts.

Allgemeines

URL Struktur
Alle Jobstaff Anfragen starten mit api.jobstaff.de. Das nächste Segment des URL-Pfads bezeichnet die aufzurufende Methode unter Angabe des Parameters action gefolgt von Übergabe-Parametern wie z.B. dem API Key.

API Key
Ihren API-Key erhalten Sie über den einmaligen Aufruf der Methode login (siehe unten). Bitte übergeben Sie den key mit jeder Anfrage an unsere API wie im unten stehenden Beispiel.

App ID
Die App ID (Application Identifier) identifiziert Ihre Anwendung. Sie können beliebig viele App IDs für Anwendungen erzeugen. In den Einstellungen Ihres Jobstaff Accounts finden Sie die entsprechende Verwaltung. Die App ID wird mit dem Parameter appid übergeben und muss bei jedem API-Request angegeben werden.

UUID
Eine UUID (Universally Unique Identifier) identifiziert ein Objekt in der Jobstaff-Datenbank. Dies können z.B. folgende Objekte sein:

» Projekt
» Aufgabe
» Mitarbeiter
» Kunde
» etc.

Beispiel

http://api.jobstaff.de/v1/?action=saveTheWorld&appid=xxxxxxxx&key=abcabcabcabc123123123123

Lernende Dokumentation

Um Ihnen die Arbeit mit der Jobstaff API zu erleichtern, geben Sie nachfolgend Ihre App ID und einen API Key ein. Alle folgenden API-Requests in dieser Dokumentation passen sich damit automatisch an Ihre Umgebung an.

App ID: API Key:

Methoden

login

ParameterInfo
appid
mailKlartext
passwordsha1 encrypted

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=login&mail=mail%40example.com&password=xxxxx
Beispiel Antwort: 
{
	"result": 1, 
	"key": "xxxxx",
	"uuid": "ap9asfnA8asdDFHnfasd0fadsf",
	"username": "Max Mustermann",
	"usertype": 2
}

register

ParameterInfo
appid
name
mail
passwordsha1 encrypted

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=register&name=Max Mustermann&mail=max@example.com&password=1211212121212
Beispiel Antwort: 
{
	"result": 1, 
	"key": "xxxxx",
	"uuid": "ap9asfnA8asdDFHnfasd0fadsf",
	"username": "Max Mustermann",
	"usertype": 2
}

setUserPassword

ParameterInfo
key
appid
oldPasswordsha1 encrypted
newPasswordsha1 encrypted

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=setUserPassword&oldPassword=aaaaa&newPassword=bbbbb&key=xxxxxx
Beispiel Antwort: 
{
	"result": 1
}

setUserData

ParameterInfo
key
appid
identifiergültige Werte: "username", "usertel"
value

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=setUserData&identifier=username&value=Max Mustermann&key=xxxxx
Beispiel Antwort: 
{
	"result": 1
}

getUserTypeByUserID

ParameterInfo
key
appid

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=getUserTypeByUserID&key=xxxxx
Beispiel Antwort: 
{
	"result": 1,
	"userType": 3,
	"userTypeValue": "Admin"
}

getTimer

ParameterInfo
key
appid

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=getTimer&key=xxxxx
Beispiel Antwort: 
{
	"result": 1,
	"timerstatus": "1",
	"jobtaskname": "Beispielaufgabe",
	"jobtasklink": "xxxxx",
	"timerstartpoint": "2013-05-02 16:34:22",
	"timervalue": "0:48",
	"joblink": "yyyyy",
	"jobname": "Beispielprojekt"
}

getJobs

ParameterInfo
key
appid

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=getJobs&key=xxxxx
Beispiel Antwort: 
{
	"result": 1,
	"rowCount": 16,
	"data":[
		{
			"joblink": "xxxxx",
			"jobname": "Ein Projekt",
			"jobdescription": "Eine Beschreibung, die ganz lang ist.",
			"jobshortdescription": "Eine Beschreibung",
			"jobarchive": "0",
			"subscribed": "1",
			"maxrequired": "9",
			"permission": "0",
			"jobcustomerid": "4",
			"customername": "Beispielkunde", 
			"jobcreationdate": "2013-01-01 10:00:00"
		},
		{
			...
		}
	]
}

getJob

ParameterInfo
key
appid
linkProjekt UUID

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=getJob&link=xxxxx&key=xxxxx
Beispiel Antwort: 
{
	"result": 1,
	"data": {
		"jobname": "Ein Projekt",
		"jobdescription": "Eine Beschreibung",
		"jobcustomerid": "0",
		"jobcustomername": "Mustermann GmbH",
		"jobcreationdate": "2013-01-01 10:00:00",
		"jobhourrate": "36.00",
		"jobneedsauth": "0",
		"jobarchive": "0",
		"subscribed": "1",
		"maxrequired": "9"
	}
}

addJob

ParameterInfo
key
appid
nameProjektname
descBeschreibung
customerKunden ID, Integer > 0 oder 0 = internes Projekt
hourrate(optional) Stundenlohn für das Projekt. Float: 14.00

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=addJob&name=Projektname&desc=Projektbeschreibung&customer=23442&hourrate=36.00&key=xxxxx
Beispiel Antwort: 
{
	"result": 1,
	"link": "xxxxx"
}

editJob

ParameterInfo
key
appid
nameProjektname
descBeschreibung
linkProjekt UUID
customerKunden ID, Integer > 0 oder 0 = internes Projekt

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=editJob&name=Projektname&desc=Projektbeschreibung&customer=23442&link=xxxxx&key=xxxxx
Beispiel Antwort: 
{
	"result": 1
}

deleteJob

ParameterInfo
key
appid
linkProjekt UUID

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=deleteJob&link=xxxxx&key=
Beispiel Antwort: 
{
	"result": 1
}

getTasks

ParameterInfo
key
appid
linkProjekt UUID

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=getTasks&link=xxxxx&key=xxxxx
Beispiel Antwort: 
{
	"result": 1,
	"job": {
		"jobname": "Ein Projekt",
		"jobdescription": "Eine Beschreibung",
		"jobcustomerid": "0",
		"viewpermission": "1",
		"customername": "Beispielkunde"
	},
	"taskCount": 3,
	"tasks": [
		{
			"jobuseruuid": "kajhakshdaksd7865876fiG",
			"jobtasklink": "xxxxx",
			"jobtaskname": "Konzeption",
			"jobtaskdescription": "Konzeption",
			"jobtaskshortdescription": "Konzeption",
			"jobtaskrequired": "3",
			"jobtaskdatefrom": "2013-05-21 10:00:00",
			"jobtaskdateto": "2013-05-24 10:00:00",
			"jobtasksuccess": "0",
			"jobtaskallowsubscription": "1",
			"subscribers": "1",
			"mesubscribed": "1",
			"permission": "1"
		},
		{
			...
		}
	]
}

getTask

ParameterInfo
key
appid
linkAufgabe UUID

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=getTask&link=xxxxx&key=xxxxx
Beispiel Antwort: 
{
	"result": 1,
	"data": {
		"jobtaskname": "Konzeption",
		"jobtaskdescription": "Konzeption",
		"jobtasklink": "xxxxx",
		"jobtaskrequired": "3",
		"jobtaskdatefrom": "2013-05-21 10:00:00",
		"jobtaskdateto": "2013-05-24 10:00:00",
		"jobtaskbillable": "1",
		"jobtaskhourrate": "36.00",
		"jobtasksuccess": "0",
		"jobtaskallowsubscription": "1",
		"joblink": "xxxxx",
		"jobname": "Ein Projekt",
		"jobdescription": "",
		"jobcreationdate": "2013-03-26 20:00:00",
		"jobhourrate": "12.00",
		"jobneedsauth": "0",
		"jobarchive": "0",
		"viewpermission": "1",
		"permission": "1",
		"timeractive": "1",
		"timervalue": "0:58",
		"subscribers": "1",
		"mesubscribed": "1"
	},
	"countSubscribers": 2,
	"subscribers": [
		{
			"useruuid": "jhlkjhasd7HGKH6r67kh",
			"username": "Demoaccount"
		}, 
		{
			...
		}
	]
}

addTask

ParameterInfo
key
appid
nameAufgaben-Name
descBeschreibung
requiredBenötigte Mitarbeiter
linkProjekt UUID
fromDateTime: "2000-01-01 00:00:01"
toDateTime: "2000-01-01 00:00:01"
hourrate(optional) Stundenlohn für die Aufgabe. Float: 14.00
billable(optional) Abrechenbarkeit der Aufgabe. Ja = 1, Nein = 2

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=addTask&name=Aufgabenname&desc=Aufgabenbeschreibung&required=4&link=xxxxx&from=2013-01-01 10:00:00&to=2013-12-31 14:00:00&hourrate=38.00&billable=1&key=xxxxx
Beispiel Antwort: 
{
	"result": 1,
	"link": "tn6y8VPUuUNbi6kfSxS0QlT2bMqkcuQ7md7"
}

editTask

ParameterInfo
key
appid
linkAufgabe UUID
nameAufgaben-Name
descBeschreibung
requiredBenötigte Mitarbeiter
fromDateTime: "2000-01-01 00:00:01"
toDateTime: "2000-01-01 00:00:01"
hourrate(optional) Stundenlohn für Aufgabe. Float: 14.00
billable(optional) Abrechenbarkeit der Aufgabe. Ja = 1, Nein = 2

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=editTask&name=Aufgabenname&desc=Aufgabenbeschreibung&required=4&link=xxxxx&from=2013-01-01 10:00:00&to=2013-12-31 10:00:00&hourrate=38.00&billable=2&key=xxxxx
Beispiel Antwort: 
{
	"result": 1
}

deleteTask

ParameterInfo
key
appid
linkAufgabe UUID

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=deleteTask&link=xxxxx&key=xxxxx
Beispiel Antwort: 
{
	"result": 1
}

subscribeTask

ParameterInfo
key
appid
linkAufgabe UUID

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=subscribeTask&link=xxxxx&key=xxxxx
Beispiel Antwort: 
{
	"result": 1
}

unsubscribeTask

ParameterInfo
key
appid
linkAufgabe UUID

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=unsubscribeTask&link=xxxx&key=xxxxx
Beispiel Antwort: 
{
	"result": 1
}

getJobParticipations

ParameterInfo
key
appid

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=getJobParticipations&key=xxxxx
Beispiel Antwort: 
{
	"result": 1,
	"dataCount": 4,
	"data": [
		{
			"jobname": "Ein Projekt",
			"joblink": "xxxxx",
			"jobtaskname": "Eine Aufgabe",
			"jobtasklink": "xxxxx",
			"jobtaskdatefrom": "2013-01-01 10:00:00",
			"jobtaskdateto": "2013-12-31 10:00:00",
			"dateinfo": null
		},
		{
			...
		}
	]
}

getStaff

ParameterInfo
key
appid

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=getStaff&key=xxxxx
Beispiel Antwort: 
{
	"result":1,
	"rowCount":4,
	"data":[
		{
			"username":"Bernd Mueller",
			"useremail":"info@jobstaff.de",
			"useraccount":"r15N_WlH78gasdXo68e8tdjV50GyB",
			"usertype":"2",
			"userlogo":"05a677964e9e227af95183c4bfe109c5.png",
			"userhourrate":"12.00",
			"usertel":"017112345678",
			"usertypename":"Mitarbeiter",
			"userOpenMinutes":"42.76"
		},
		{
			...
		}
	]
}

getUser

ParameterInfo
key
appid

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=getUser&key=xxxxx
Beispiel Antwort: 
{
	"result":1,
	"data":{
		"username":"Demoaccount",
		"useremail":"demo",
		"usertel":"0172987612345",
		"useraccount":"m2z0tasdfsdfasdfascZG3uSkEzDz3u7X",
		"userbelongsto":"m2z0tasdfsdfasdfascZG3uSkEzDz3u7X",
		"userpremium":"1",
		"useractive":"1",
		"usertype":"3",
		"userlogo":"05a677335663433c4bfe109c5.png",
		"userhourrate":"60.00"
	}
}

addStaff

ParameterInfo
key
appid
nameMitarbeiter-Name
mailE-Mail Adresse
phoneTelefonnummer
usertypeInteger > 0
hourrate(optional) Stundenlohn für Mitarbeiter. Float: 14.00

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=addStaff&name=Max Mustermann&mail=max@example.com&phone=1234567890&usertype=2&key=xxxxx
Beispiel Antwort: 
{
	"result": 1,
	"link": "xxxxx"
}

inviteStaff

ParameterInfo
key
appid
linkAufgabe UUID
userAccounts
modeGibt an, ob ein Mitarbeiter eingeladen oder zugewiesen werden soll. 1 = Einladen, 2 = Zuweisen

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=inviteStaff&link=xxxxx&userAccounts=[aaaaa,bbbbb]&mode=1&key=xxxxx
Beispiel Antwort: 
{
	"result": 1
}

getTimes

Gibt alle Zeiteinträge des Benutzer nach Datum sortiert und gruppiert zurück.
ParameterInfo
key
appid
fromDateTime: "2000-01-01 00:00:01"
toDateTime: "2000-01-01 00:00:01"
mode(optional) bei "grouped" werden alle Zeiten pro Tag gruppiert. Im Modus "plain" wird jede Zeit einzelnd zurückgegeben. Default ist "grouped"

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=getTimes&from=2013-01-01&to=2013-12-31&mode=grouped&key=xxxxx
Beispiel Antwort: 
{
	"result": 1,
	"rowCount": 43,
	"hoursAmount": 537.41,
	"data": [
		{
			"hourCount": 2,
			"date": "2013-05-09",
			"weekday": 4, 
			"hourData": [
				{
					"hourstatusvalue": "nicht erstellt",
					"hourstatuscolor": "FF7A7A",
					"hoursfrom": "2013-05-09 13:58:05",
					"hoursto": "2013-05-09 14:08:06",
					"hourstimeractive": "0",
					"hoursnotice": "",
					"hoursamount": "0.17", 
					"joblink": "xxxxx",
					"jobname": "Ein Projekt",
					"jobdescription": "Beschreibung des Projekts",
					"jobcreationdate": "2013-01-01 10:00:00",
					"jobhourrate": "40.00",
					"jobneedsauth": "0",
					"jobarchive": "0",
					"jobtaskname": "Eine Aufgabe",
					"jobtaskdescription": "Beschreibung der Aufgabe",
					"jobtasklink": "xxxxx",
					"jobtaskrequired": "1",
					"jobtaskdatefrom": "2013-03-31 10:00:00",
					"jobtaskdateto": "2013-04-30 10:00:00",
					"jobtaskbillable": "0",
					"jobtaskhourrate": "32.00",
					"jobtasksuccess": "0",
					"jobtaskallowsubscription": "1"
				},
				{
					...
				}
			]
		},
		{
			...
		}
	]
}

deleteTime

ParameterInfo
key
appid
idInteger > 0

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=deleteTime&id=123123&key=xxxxx
Beispiel Antwort: 
{
	"result": 1
}

startTimer

ParameterInfo
key
appid
joblinkProjekt UUID
tasklinkAufgabe UUID

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=startTimer&joblink=xxxxx&tasklink=yyyyy&key=xxxxx
Beispiel Antwort: 
{
	"result": 1,
	"timerstart": 1,
	"timerstartpoint": "2013-05-02 12:44:12"
}

stopTimer

ParameterInfo
key
appid
saveZeit speichern oder verwerfen: 1 || 0

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=stopTimer&save=1&key=xxxxx
Beispiel Antwort: 
{
	"result": 1,
	"data": {
		"hoursid": "8963",
		"joblink": "xxxxx",
		"jobname": "Ein Projekt",
		"jobdescription": "Die Beschreibung des Projekts. ",
		"jobtaskname": "Eine Aufgabe",
		"jobtaskdescription": "Die Beschreibung der Aufgabe",
		"jobtasklink": "yyyyy",
		"hoursamount": "3.41"
	}
}

getCustomer

ParameterInfo
key
appid

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=getCustomer&key=xxxxx
Beispiel Antwort: 
{
	"result": 1,
	"rowCount": 4,
	"data": [
		{
			"customerid": 0,
			"customername": "internes Projekt"
		},
		{
			"customerlink": "iG4XFkTsdsd7987EphZComnaQ2wiwfAs",
			"customername": "Demokunde",
			"customernumber": "10554",
			"customeraddress1": "Demostraße 13",
			"customeraddress2": "",
			"customercontact": "Max Mustermann",
			"customerzip": "10709",
			"customercity": "Berlin",
			"customercountry": "1",
			"customertel": "01234456789",
			"customertaxnumber": "",
			"customerhourrate": "40.00",
			"customeremail": "info@example.com"
		},
		{
			...
		}
	]
}

addTime

ParameterInfo
key
appid
joblinkProjekt UUID
tasklinkAufgabe UUID
date"2013-12-31"
hours"00:01"
notice(optional) Notiz zur Arbeitszeit

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=addTime&joblink=xxxxx&tasklink=yyyyy&date=2013-12-31&hours=01:30&key=xxxxx
Beispiel Antwort: 
{
	"result": 7343
}

updateHourNotice

ParameterInfo
key
appid
hourID
noticeNotiz zur Arbeitszeit

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=updateHourNotice&hourID=123&notice=Testnotiz&key=xxxxx
Beispiel Antwort: 
{
	"result": 1
}

getPremiumUserTypes

ParameterInfo
key
appid

Beispiel Anfrage: http://api.jobstaff.de/v1/?appid=xxxxx&action=getPremiumUserTypes&key=
Beispiel Antwort: 
{
	"result":1,
	"rowCount":2,
	"data":[
		{
			"usertypeid":"2",
			"usertypename":"Mitarbeiter",
			"usertypepremium":"1"
		},
		{
			...
		}
	]
}