Kontakte: Firmen/Gruppen

Folgende HTTP-Methoden stehen für Firmen/Gruppen zur Verfügung:

Zugriff ab Benutzergruppe Zeiterfasser 2.

alle Firmen/Gruppen auflisten

GET /api/v1/customers

Bitte beachten Sie: Die Ressource bietet (anders als der Name vermuten lässt) Zugriff auf alle Firmen der Kontaktverwaltung, also Kunden, Lieferanten, Interessenten etc. Die größte Menge der Einträge wird aber Kunden betreffen, daher die Bezeichnung, die als Parameter auch in anderen Ressourcen zu finden ist (customerID, customerName).

Der Parameter invoiceCounter hat nur eine Bedeutung für Accounts, die als Rechnungsnummernmodus den Zähler pro Kunde aktiviert haben.

Antwort:

{
  "meta": {
    "status": 200,
    "perPage": 100,
    "page": 1,
    "totalCount": 23,
    "requestUserID": 1,
    "requestUsername": "Admin1",
    "usergroupName": "Administrator",
    "apiLimitRemaining": 443,
    "apiLimitReset": 812
  },
  "data": [
    {
      "customerID": 10,
      "customerName": "Testfirma",
      "companyCode": "",
      "companyStatus": 0,
      "comments": "",
      ...
    },
    ...
  ]
}

Filterung/Suche

Über Parameter kann gefiltert werden:

GET /api/v1/customers?customerName=Testfirma
Parameter Beschreibung
customerName Bezeichnung der Firma/Gruppe
companyCode Kürzel der Firma/Gruppe
companyStatus Status der Firma:
0 = Kunde
1 = Lieferant
2 = Interessent
3 = Akquise
4 = PR/Presse
5 = inaktiv/gekündigt
6 = Sonstige
comments Anmerkungen zur Firma/Gruppe
hourlyRateDiscount Rabatt (Prozent) auf den allgemeinen Stundensatz
customerCostRate individueller Stundensatz des Kunden
customerPaymentTarget individuelles Zahlungsziel des Kunden
customerCashDiscountRate individueller Skontosatz des Kunden
customerCashDiscountPaymentTarget individuelles Zahlungsziel für den Skontobetrag

Angabe von Dezimalwerten mit Punkt als Trennzeichen.

Sortierung

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

customerID, customerName, companyCode, companyStatus, hourlyRateDiscount, customerCostRate, customerPaymentTarget, customerCashDiscountRate

eine Firma/Gruppe aufrufen

GET /api/v1/customers/{id}

Antwort:

{
  "meta": {
    "status": 200,
    "requestUserID": 1,
    "requestUsername": "Admin1",
    "usergroupName": "Administrator",
    "apiLimitRemaining": 486,
    "apiLimitReset": 642
  },
  "data": {
    "customerID": 10,
    "customerName": "ABC Versicherung",
    "companyCode": "ABC",
    "companyStatus": 0,
    "comments": "",
    "projectCounter": 32,
    "projectCounterYear": 2019,
    "invoiceCounter": 1,
    "invoiceCounterYear": 2015,
    "hourlyRateDiscount": 0,
    "customerCostRate": 80,
    "customerPaymentTarget": 7,
    "customerCashDiscountRate": null,
    "customerCashDiscountPaymentTarget": null,
    "companyViaApi": 0,
    "addressesAssigned": [
      {
        "addressID": 36,
        "name1": "ABC Versicherung AG",
        "name2": "",
        "name3": "",
        "addressName": "",
        "street": "Unfallstraße",
        "streetNo": 23,
        "postalCode": 12345,
        "city": "Hamburg",
        "country": ""
      }
    ],
    "contactsAssigned": [
      {
        "contactID": 48,
        "firstName": "Karl",
        "LastName": "Schmidt",
        "position": "",
        "department": "",
        "email": "karl.schmidt@versicherung.de",
        "email2": "",
        "telephone": "01234 5678945",
        "mobile": ""
      },
      ...
    ]
  }
}

eine Firma/Gruppe erstellen

POST /api/v1/customers

Die Firmennummer (customerNo) wird beim Anlegen automatisch generiert!

Notwendige und mögliche Parameter im Body:

Parameter Beschreibung Typ Default-Wert Pflichtfeld
customerName Bezeichnung der Firma/Gruppe String   ja
companyCode Kürzel der Firma/Gruppe String    
companyStatus Status der Firma/Gruppe:
0 = Kunde
1 = Lieferant
2 = Interessent
3 = Akquise
4 = PR/Presse
5 = inaktiv/gekündigt
6 = Sonstige
Int 0  
comments Anmerkungen zur Firma/Gruppe String    
hourlyRateDiscount Rabatt (Prozent) auf den allgemeinen Stundensatz Dec 0  
customerCostRate individueller Stundensatz des Kunden Dec null  
customerPaymentTarget individuelles Zahlungsziel des Kunden Int null  
customerCashDiscountRate individueller Skontosatz des Kunden Dec null  
customerCashDiscountPaymentTarget individuelles Zahlungsziel für den Skontobetrag Int null  

Angabe von Dezimalwerten mit Punkt als Trennzeichen.

Beispiel:

{
    "customerName": "Testfirma API",
    "companyCode": "TAPI",
    "customerPaymentTarget": 7
}

eine Firma/Gruppe bearbeiten

PUT /api/v1/customers/{id}

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

Es stehen die Parameter zum Erstellen der Ressource zur Verfügung (s.o.).