ProSonata API

Projekte

Folgende HTTP-Methoden stehen für Projekte zur Verfügung:

Zugriff ab Benutzergruppe Zeiterfasser 2.
Lesender Zugriff auf »meine Projekte« für Benutzergruppen bis Zeiterfasser 1.

alle Projekte auflisten

GET /api/v1/projects

Antwort:

{
  "meta": {
    "status": 200,
    "perPage": 100,
    "page": 1,
    "totalCount": 64,
    "requestUserID": 1,
    "requestUsername": "Admin1",
    "usergroupName": "Administrator",
    "apiLimitRemaining": 498,
    "apiLimitReset": 883
  },
  "data": [
    {
      "projectID": 1,
      "projectNo": "19-12-001",
      "projectName": "Kundenmailing",
      "customerID": 12,
      "customerName": "Versandmode Becker",
      "contactID": 53,
      "firstName": "Christiane",
      "lastName": "Maier",
      "projectDate": "2019-01-18",
      ...
    },
    ...
  ]
}

Filterung/Suche

Über Parameter kann gefiltert werden:

GET /api/v1/projects?projectName=Testprojekt

Parameter	Beschreibung
projectNo	Projektnummer
projectName	Bezeichnung des Projekts
customerID	ID des Kunden (Firma/Gruppe)
customerName	Bezeichnung des Kunden (Firma/Gruppe)
contactID	ID des Kunden Ansprechpartners
lastName	Nachname des Kunden Ansprechpartners
userID	zugeordnete Projekte des Benutzers mit der ID, Sonderwert: String »myself« für Projekte des anfragenden Benutzeraccounts
projectStatus	Status des Projekts: 0 = offen 1 = in Abrechnung 2 = abgeschlossen 3 = abgebrochen 4 = bereit zur Abrechnung
financeStatus	Faktura-Status des Projekts: 0 = kein Angebot/Rechnung 1 = Angebot 2 = Rechnung 3 = 1. Mahnung 4 = 2. Mahnung 5 = 3. Mahnung
activeStatus	Aktiv-Status des Projekts (offenes Projekt »ruht«): 0 = inaktiv 1 = aktiv
projectDate	Datum des Projekts durch Angabe von > oder < vor dem Datum kann eine Suche ab dem bzw. bis zum Datum erfolgen
projectDateEnd	Enddatum des Projekts durch Angabe von > oder < vor dem Datum kann eine Suche ab dem bzw. bis zum Datum erfolgen
projectQuickInfo	Kurzinfo zum Projekt
projectTags	Tags des Projekts
internalDepartment	interne Abteilung (0 bis 9)
recurringProject	wiederkehrendes Projekt: 0 = nicht wiederkehrend 1 = monatlich 2 = zweimonatlich 3 = quartalsweise 4 = halbjährlich 5 = jährlich 6 = zweijährlich
userResponsibleID	ID des verantwortlichen Benutzers

Sortierung

Nach folgenden Parametern kann sortiert werden (Sortierrichtung ggf. mit ASC bzw. DESC ergänzen):

projectID, projectName, customerID, customerName, contactID, lastName, projectDate, projectDateEnd, projectStatus, timeNeeded

ein Projekt aufrufen

GET /api/v1/projects/{id}

Antwort:

{
  "meta": {
    "status": 200,
    "requestUserID": 1,
    "requestUsername": "Admin1",
    "usergroupName": "Administrator",
    "apiLimitRemaining": 491,
    "apiLimitReset": 493
  },
  "data": {
    "projectID": 45,
    "projectNo": "19-11-001",
    "projectName": "Frühstücks-Flyer",
    "customerID": 11,
    "customerName": "Bäckerei Back",
    "contactID": 50,
    "firstName": "Hans",
    "lastName": "Back",
    "projectDate": "2019-01-13",
    "projectDateEnd": null,
    "recurringProject": 0,
    "createdByUserID": 4,
    "userResponsibleID": null,
    "projectStatus": 1,
    "financeStatus": 3,
    "activeStatus": 1,
    "projectInfo": "",
    "projectQuickInfo": "",
    "projectTags": "",
    "projectLinks": [
      {
        "name": "Testlink Website",
        "url": "https://www.baeckerei-back-test.de"
      },
      {
        "name": "ProSonata",
        "url": "https://www.prosonata.de"
      }
   ],
    "timePlanned": 20,
    "timeNeeded": 15.25,
    "projectCostRate": null,
    "internalDepartment": 0,
    "projectGroupID": null,
    "isProjectTemplate": 0,
    "usersAssigned": [
      {
        "userID": 2,
        "username": "Designer2",
        "userFirstName": "",
        "userLastName": ""
      },
      {
        "userID": 3,
        "username": "Admin2",
        "userFirstName": "Max",
        "userLastName": "Mustermann"
      }
    ]
  }
}

ein Projekt erstellen

POST /api/v1/projects

Die Projektnummer (projectNo) wird beim Anlegen automatisch generiert!

Notwendige und mögliche Parameter im Body:

Parameter	Beschreibung	Typ	Default-Wert	Pflichtfeld
projectName	Bezeichnung des Projekts	String		ja
customerID	ID des Kunden (Firma/Gruppe)	Int		ja
contactID	ID des Kunden Ansprechpartners	Int		ja
activeStatus	Aktiv-Status des Projekts: 0 = inaktiv 1 = aktiv	Int	1
projectDate	Datum Projektstart	Date	aktueller Tag
projectDateEnd	Datum Projektende	Date	null
recurringProject	wiederkehrendes Projekt: 0 = nicht wiederkehrend 1 = monatlich 2 = zweimonatlich 3 = quartalsweise 4 = halbjährlich 5 = jährlich 6 = zweijährlich	Int	0
userResponsibleID	ID des verantwortlichen Benutzers	Int	null
projectQuickInfo	Kurzinfo zum Projekt	String
projectInfo	erweiterte Infos zum Projekt	String
projectTags	Tags (kommasepariert)	String
projectLinks	bis zu 5 Links pro Projekt Links werden als Arrays übergeben: name: Bezeichnung des Links url: URL des Links (inkl. https)	Array	[] leeres Array
timePlanned	geplante Zeit (in Std.) für das Projekt	Dec	0.00
projectCostRate	Stundensatz des Projekts	Dec	null
internalDepartment	interne Abteilung (0 bis 9)	Int	0
projectGroupID	ID der zugeordneten Projektgruppe	Int	null
isProjectTemplate	Projekt als Vorlage markieren	Int	0
usersAssigned	zugeordnete Benutzer speichern (ein Array der userID(s) kann übergeben werden)	Array	[] leeres Array

Angabe von Dezimalwerten mit Punkt als Trennzeichen.

Beispiel:

{
    "projectName": "Muster Projekt",
    "customerID": 10,
    "contactID": 49,
    "projectDateEnd": "25.06.2019",
    "userResponsibleID": 2,
    "projectInfo": "Hier stehen erweiterte Infos zum Projekt",
    "projectQuickInfo": "eine Kurzinfo zum Projekt",
    "projectLinks": [
      {
        "name": "ProSonata",
        "url": "https://www.prosonata.de"
      }
    ]
    "timePlanned": 20,
    "projectCostRate": 80.00,
    "internalDepartment": 2,
    "usersAssigned": [
      {
        "userID": 2
      },
      {
        "userID": 3
      }
    ]
}

ein Projekt bearbeiten

PUT /api/v1/projects/{id}

Es müssen nicht alle Parameter für eine Bearbeitung übergeben werden.

Ergänzend zum Erstellen der Ressource stehen weitere Parameter zur Verfügung:

Parameter	Beschreibung	Typ
projectNo	Projektnummer	String
projectStatus	Status des Projekts: 0 = offen 1 = in Abrechnung 2 = abgeschlossen 3 = abgebrochen 4 = bereit zur Abrechnung	Int
financeStatus	Faktura-Status des Projekts: 0 = kein Angebot/Rechnung 1 = Angebot 2 = Rechnung 3 = 1. Mahnung 4 = 2. Mahnung 5 = 3. Mahnung	Int

zurück zur Übersicht