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 gültigen API-Token.
Bei ungültigem Token wird {"status": 0, "message": "Invalid Token"} zurückgegeben.

Endpunkte

GET
/api/customers/list

Gibt eine paginierbare Liste aller Kunden zurück. Jeder Kunde enthält zusätzlich 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
statusid integer Nach Status filtern: 1 = aktiv, 2 = inaktiv optional neu
activeonly integer 1 liefert nur aktive und nicht gesperrte Kunden optional neu
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.
Abwärtskompatibel: Ohne statusid und ohne activeonly verhält sich der Endpunkt exakt wie bisher und liefert alle Kunden – unabhängig von Status und Sperre. Bestehende Integrationen müssen nicht angepasst werden.
Beispiel-Aufrufe
GET /api/customers/list?token=IHRGEHEIMERCATAMATOKEN
    (alle Kunden)

GET /api/customers/list?token=IHRGEHEIMERCATAMATOKEN&activeonly=1
    (nur aktive und nicht gesperrte Kunden)

GET /api/customers/list?token=IHRGEHEIMERCATAMATOKEN&statusid=2
    (nur inaktive Kunden)

GET /api/customers/list?token=IHRGEHEIMERCATAMATOKEN&take=50&offset=0&typeid=1
    (erste 50 Kunden des Kundentyps 1)

Statusfelder im Kunden-Objekt neu

Feld Typ Beschreibung
status_type integer Auswahlfeld „Status“ in der Kundenakte: 1 = aktiver Kunde, 2 = passiver/inaktiver Kunde
active integer Bequemer Bool-Wert: 1 wenn status_type = 1, sonst 0
locked integer Checkbox „gesperrt“: 1 = gesperrt, 0 = nicht gesperrt
block_note string Sperrnotiz aus der Kundenakte; leerer String, wenn keine hinterlegt ist
Zwei unabhängige Merkmale: „aktiv/inaktiv“ (status_type) und „gesperrt“ (locked) sind in CATAMA getrennte Felder. Ein Kunde kann also aktiv und gesperrt sein. activeonly=1 deckt beide Fälle ab und liefert nur Kunden, mit denen ohne Einschränkung gearbeitet werden darf.
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",
      "birthday": "15.06.1985",
      "online_invoice": 0,
      "status_type": 1,
      "active": 1,
      "locked": 0,
      "block_note": "",
      "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)
status_type Status: 1 = aktiv, 2 = inaktiv
active Aktiv-Kennzeichen (0/1)
locked Gesperrt-Kennzeichen (0/1)
block_note Sperrnotiz (Text, ggf. leer)
cars Array der zugeordneten aktiven 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
cars ist gefiltert und nicht vollständig: Das Array enthält nur aktive Fahrzeuge, die dem Kunden aktuell zugeordnet sind. Fahrzeuge mit abweichendem Status – etwa deaktivierte oder abgemeldete – fehlen. Wer wirklich alle Fahrzeuge eines Kunden braucht, ruft /api/customerscars/byid?customerid=… auf.

Abweichende Feldnamen: Das Array cars liefert 16 Felder mit teils anderen Namen als die Kundenfahrzeug-API, die pro Fahrzeug 67 Felder zurückgibt. Diese Tabelle übersetzt zwischen beiden:

in cars[] in /api/customerscars/* Inhalt
fabricator_name fabricator Fabrikatsname
model modell Modell / Ausführung
license_plate plate Kennzeichen
first_registration registration_date Erstzulassung
next_service nextservice_at Nächster Service

Die übrigen Felder (id, intern_id, fabricator_id, name, chassis_number, mileage, general_inspection, color, power_ps, power_kw, cubic) heißen in beiden Endpunkten gleich.

Die vollständige Dokumentation der Fahrzeugdaten, der Suche über Fahrgestellnummer oder Kennzeichen sowie der Anlage neuer Kundenfahrzeuge steht im Artikel Kundenfahrzeugdaten (/api/customerscars/).
GET
/api/customers/byid

Ruft einen einzelnen Kunden anhand seiner ID ab. Die Feldstruktur entspricht /api/customers/list – inklusive der Statusfelder status_type, active, locked und block_note, jedoch ohne das Array cars.

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_type": 2,
    "active": 0,
    "locked": 1,
    "block_note": "Zahlungsrückstand, nur gegen Vorkasse"
  },
  "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)
Kein Status beim Anlegen: status_type und locked lassen sich über diesen Endpunkt nicht setzen. Neue Kunden werden als aktiv und nicht gesperrt angelegt; die Pflege erfolgt in der Kundenakte.
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