Kundendaten

API Dokumentation – Kunden

Alle Endpunkte unter /api/customers/ zum Abruf, zur Auflistung und zur Anlage von Kunden.

Authentifizierung
Alle Endpunkte erfordern den Parameter token mit dem gueltigen API-Token.
Bei ungueltigem Token wird {"status": 0, "message": "Invalid Token"} zurueckgegeben.

Endpunkte

GET
/api/customers/list

Gibt eine paginierbare Liste aller Kunden zurueck. Jeder Kunde enthaelt zusaetzlich ein Array cars mit seinen zugeordneten Kundenfahrzeugen.

Parameter

Name Typ Beschreibung
token string API-Token Pflicht
take integer Anzahl der Ergebnisse (Limit) optional
offset integer Startposition fuer Paginierung optional
typeid integer Nach Kundentyp filtern (customer_prefix_kind) optional
Paginierung: Ohne take und offset werden alle Kunden ausgegeben. Fuer grosse Datenmengen empfohlen: z. B. offset=0&take=50, dann offset=50&take=50 usw.
Erfolgreiche Antwort
{
  "data": {
    "200": {
      "id": 200,
      "title_id": 1,
      "title": "Herr",
      "company": "Muster GmbH",
      "forename": "Max",
      "lastname": "Mustermann",
      "street": "Musterstr. 1",
      "zip": "12345",
      "city": "Berlin",
      "country": "Deutschland",
      "phone_mobile": "0170 1234567",
      "phone_primary": "030 1234567",
      "email_primary": "max@muster.de",
      "kind_id": 1,
      "kind_name": "Kunde",
      "type_id": 1,
      "type_name": "Privatkunde",
      "type_shortcode": "PK",
      "cars": [
        {
          "id": 1085,
          "intern_id": "KFZ-001",
          "fabricator_id": 3,
          "fabricator_name": "Volkswagen",
          "name": "Golf VII",
          "model": "1.4 TSI",
          "chassis_number": "WVWZZZ3CZWE123456",
          "license_plate": "B-AB 1234",
          "first_registration": "15.03.2019",
          "mileage": 85000,
          "general_inspection": "01.03.2026",
          "next_service": "01.09.2026",
          "color": "Schwarz",
          "power_ps": 150,
          "power_kw": 110,
          "cubic": 1395
        }
      ],
      "..."
    }
  },
  "status": 1,
  "message": "Success"
}
Alle Felder im Kunden-Objekt anzeigen
Feld Beschreibung
id Kunden-ID
title_id Anrede-ID
title Anrede (z. B. „Herr“, „Frau“)
company Firmenname
forename Vorname
lastname Nachname
extra Zusatz
street Strasse
zip PLZ
city Stadt
country Land
phone_mobile Mobilnummer
phone_primary Telefon (privat)
phone_secondary Telefon (geschaeftlich)
email_primary E-Mail
email_secondary E-Mail 2
email_tertiary E-Mail 3
kind_id Kundenart-ID
kind_name Kundenart (z. B. „Kunde“)
type_id Kundentyp-ID
type_name Kundentyp (z. B. „Privatkunde“)
type_shortcode Kundentyp-Kuerzel (z. B. „PK“)
bank_name Bankname
bank_account_holder Kontoinhaber
bank_iban IBAN
bank_bic BIC
birthday Geburtstag (dd.mm.YYYY)
online_invoice Online-Rechnung (0/1)
cars Array der zugeordneten Fahrzeuge (siehe unten)
Felder im Fahrzeug-Objekt (cars[]) anzeigen
Feld Beschreibung
id Fahrzeug-ID
intern_id Interne Nummer
fabricator_id Fabrikat-ID
fabricator_name Fabrikat-Name
name Fahrzeugbezeichnung
model Modellbezeichnung
chassis_number Fahrgestellnummer (VIN)
license_plate Kennzeichen
first_registration Erstzulassung (dd.mm.YYYY)
mileage Kilometerstand
general_inspection HU/AU Datum
next_service Naechster Service
color Farbe
power_ps Leistung in PS
power_kw Leistung in kW
cubic Hubraum in ccm

GET
/api/customers/byid

Ruft einen einzelnen Kunden anhand seiner ID ab.

Parameter

Name Typ Beschreibung
token string API-Token Pflicht
id integer Kunden-ID Pflicht
Beispiel-Aufruf
GET /api/customers/byid?token=xxx&id=200
Erfolgreiche Antwort
{
  "data": {
    "id": 200,
    "title_id": 1,
    "title": "Herr",
    "company": "Muster GmbH",
    "forename": "Max",
    "lastname": "Mustermann",
    "street": "Musterstr. 1",
    "zip": "12345",
    "city": "Berlin",
    "country": "Deutschland",
    "phone_mobile": "0170 1234567",
    "phone_primary": "030 1234567",
    "phone_secondary": "",
    "email_primary": "max@muster.de",
    "email_secondary": "",
    "email_tertiary": "",
    "kind_id": 1,
    "kind_name": "Kunde",
    "type_id": 1,
    "type_name": "Privatkunde",
    "type_shortcode": "PK",
    "bank_name": "Sparkasse",
    "bank_account_holder": "Max Mustermann",
    "bank_iban": "DE89370400440532013000",
    "bank_bic": "COBADEFFXXX",
    "birthday": "15.06.1985",
    "online_invoice": 0
  },
  "status": 1,
  "message": "Success"
}
Fehler
{ "status": 0, "message": "Customer ID is missing" }
{ "status": 0, "message": "Invalid Customer ID" }
Hinweis: Im Gegensatz zu /api/customers/list wird hier kein cars-Array zurueckgegeben. Nutzen Sie /api/customerscars/byid?customerid=... um die Fahrzeuge eines Kunden abzurufen.

POST
/api/customers/create

Legt einen neuen Kunden an. Alle Felder sind optional und werden mit Standardwerten befuellt, wenn sie nicht angegeben werden.

Parameter

Name Typ Standard Beschreibung
token string – API-Token Pflicht
title_id integer 1 Anrede-ID (1 = Herr, 2 = Frau, …)
company string „“ Firmenname
forename string „“ Vorname
lastname string „“ Nachname
extra string „“ Zusatz (z. B. „c/o“)
street string „-„ Strasse
zip string „-„ Postleitzahl
city string „-„ Stadt
country string „Deutschland“ Laendername (Klartext)
phone_mobile string „“ Mobilnummer
phone_primary string „“ Telefon (geschaeftlich)
phone_secondary string „“ Telefon (privat)
email_primary string „“ E-Mail-Adresse
email_secondary string „“ E-Mail 2
email_tertiary string „“ E-Mail 3
kind_id integer 1 Kundenart-ID
type_id integer 1 Kundentyp-ID (Prefix-Kind)
bank_name string „“ Bankname
bank_account_holder string „“ Kontoinhaber
bank_iban string „“ IBAN
bank_bic string „“ BIC
birthday string „“ Geburtstag (z. B. „15.06.1985“)
online_invoice integer 0 Online-Rechnung (0 = Nein, 1 = Ja)
Erfolgreiche Antwort
{
  "data": {
    "title_id": 1,
    "title": "Herr",
    "company": "Muster GmbH",
    "forename": "Max",
    "lastname": "Mustermann",
    "street": "Musterstr. 1",
    "zip": "12345",
    "city": "Berlin",
    "country": "Deutschland",
    "phone_mobile": "0170 1234567",
    "email_primary": "max@muster.de",
    "kind_id": 1,
    "kind_name": "Kunde",
    "type_id": 1,
    "type_name": "Privatkunde",
    "type_shortcode": "PK",
    "..."
  },
  "status": 1,
  "message": "Success",
  "customer_id": 201
}
Fehler
{
  "data": { "..." },
  "status": 0,
  "message": "Failed",
  "customer_id": 0
}
Hinweis: Die customer_id im Response ist die ID des neu angelegten Kunden. Nutzen Sie diese ID z. B. fuer /api/customerscars/create um dem Kunden ein Fahrzeug zuzuordnen.

 

Ein Formular mit sämtlichen Werten für die title_id, kind_id, type_id finden Sie hier:
https://support.catama-software.de/api/formtest.html

Bei Fragen zur API, steht Ihnen unser Support jederzeit zur Verfügung.

Ähnliche Artikel