Zum Hauptinhalt gehen

Kunden – Attribute, Schlagworte & Kontakte

Svenja Jacobs
Aktualisiert

Zu jedem Kunden kannst du benutzerdefinierte Attribute setzen, Schlagworte vergeben und Ansprechpartner (Kontakte) verwalten – alles über eigene API-Endpunkte.

 

Hinweis: Dieser Artikel beschreibt die drei Unterressourcen eines Kunden. Die Stammdaten des Kunden selbst (Name, Adresse, Bankdaten etc.) findest du im Artikel Kunden (clients).

 

Teil 1: Benutzerdefinierte Attribute

In Billomat kannst du Kunden mit eigenen Attributen versehen – zum Beispiel eine Abteilung, eine Kundenkategorie oder einen internen Score. Diese Attribute werden zuerst als Attributdefinition angelegt (unter Einstellungen > Kunden-Attribute) und dann pro Kunde mit einem Wert befüllt.

Die Werte werden über den Endpunkt /api/client-property-values verwaltet.

Folgende Attributtypen gibt es:

Typ Beschreibung
TEXTFIELD Einzeiliges Textfeld
TEXTAREA Mehrzeiliges Textfeld
CHECKBOX Ja/Nein-Feld (0 oder 1)

 

Alle Attributwerte auflisten

Request:

GET /api/client-property-values

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/client-property-values?format=json

Response (200 OK):

{
  "client-property-values": {
    "@page": "1",
    "@per_page": "100",
    "@total": "2",
    "client-property-value": [
      { "id": "1", "client_id": "789", "client_property_id": "3", "type": "TEXTFIELD", "name": "Abteilung", "value": "Marketing" },
      { "id": "2", "client_id": "789", "client_property_id": "7", "type": "CHECKBOX", "name": "Premium-Kunde", "value": "1" }
    ]
  }
}

Filterparameter:

Parameter Beschreibung
client_id Alle Attribute eines bestimmten Kunden
client_property_id Alle Werte eines bestimmten Attributs (ressourcenübergreifend)
value Filter nach Attributwert

 

Beispiel: Alle Attribute von Kunde 789:

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/client-property-values?client_id=789&format=json

 

Einzelnen Attributwert abrufen

Request:

GET /api/client-property-values/{id}

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/client-property-values/1?format=json

Response (200 OK):

{
  "client-property-value": {
    "id": "1",
    "client_id": "789",
    "client_property_id": "3",
    "type": "TEXTFIELD",
    "name": "Abteilung",
    "value": "Marketing"
  }
}

 

Attributwert setzen

Attributwerte werden immer per POST gesetzt – auch wenn der Wert bereits existiert (dann wird er überschrieben). Alle drei Felder sind Pflichtfelder.

Request:

POST /api/client-property-values

curl -X POST \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/json' \
  -d '{
    "client-property-value": {
      "client_id": "789",
      "client_property_id": "3",
      "value": "Innendienst"
    }
  }' \
  https://{deineBillomatID}.billomat.net/api/client-property-values

Response (201 Created):

{
  "client-property-value": {
    "id": "1",
    "client_id": "789",
    "client_property_id": "3",
    "type": "TEXTFIELD",
    "name": "Abteilung",
    "value": "Innendienst"
  }
}

Tipp: Die client_property_id findest du über GET /api/client-properties – dort sind alle definierten Attribute mit ihren IDs aufgelistet. Die Attributdefinitionen selbst werden in den Einstellungen unter Einstellungen > Kunden-Attribute angelegt, nicht über diesen Endpunkt.

 

 

Teil 2: Schlagworte (Tags)

Schlagworte dienen zur freien Kategorisierung von Kunden. Du kannst beliebig viele Tags pro Kunde vergeben und Kunden später gezielt danach filtern.

 

Alle Schlagworte (Tagcloud) abrufen

Liefert alle verwendeten Tags mit ihrer Häufigkeit – nützlich für eine Übersicht oder Autocomplete-Funktion.

Request:

GET /api/client-tags

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/client-tags?format=json

Response (200 OK):

{
  "client-tags": {
    "@total": "2",
    "client-tag": [
      { "id": "1", "name": "VIP", "count": "12" },
      { "id": "2", "name": "Stammkunde", "count": "7" }
    ]
  }
}

 

Schlagworte eines Kunden abrufen

Request:

GET /api/client-tags?client_id={id}

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/client-tags?client_id=789&format=json

Response (200 OK):

{
  "client-tags": {
    "@total": "2",
    "client-tag": [
      { "id": "5", "client_id": "789", "name": "VIP" },
      { "id": "6", "client_id": "789", "name": "Stammkunde" }
    ]
  }
}

 

Schlagwort vergeben

Beide Felder sind Pflichtfelder.

Request:

POST /api/client-tags

curl -X POST \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/json' \
  -d '{"client-tag": {"client_id": "789", "name": "VIP"}}' \
  https://{deineBillomatID}.billomat.net/api/client-tags

Response (201 Created):

{
  "client-tag": {
    "id": "5",
    "client_id": "789",
    "name": "VIP"
  }
}

 

Schlagwort entfernen

Request:

DELETE /api/client-tags/{id}

curl -X DELETE \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/client-tags/5

Response (200 OK) – kein Body.

Tipp – Kunden nach Tags filtern:
Über den Filter ?tags=VIP beim Kunden-Endpunkt kannst du alle Kunden mit diesem Tag abrufen. Mehrere Tags kommasepariert angeben (ODER-Verknüpfung):

GET /api/clients?tags=VIP,Stammkunde

 

 

Teil 3: Kontakte (Ansprechpartner)

Zu jedem Kunden können mehrere Ansprechpartner hinterlegt werden – z.B. verschiedene Personen aus unterschiedlichen Abteilungen. Diese Kontakte haben eigene Adress- und Kommunikationsdaten. Felder, die beim Kontakt leer gelassen werden, erben automatisch den Wert des übergeordneten Kunden.

 

Kontakte eines Kunden abrufen

Kontakte können immer nur für einen bestimmten Kunden abgerufen werden – client_id ist daher Pflichtparameter.

Request:

GET /api/contacts?client_id={id}

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/contacts?client_id=789&format=json

Response (200 OK):

{
  "contacts": {
    "@page": "1",
    "@per_page": "100",
    "@total": "1",
    "contact": {
      "id": "4",
      "client_id": "789",
      "label": "Einkauf",
      "name": "",
      "salutation": "Frau",
      "first_name": "Erika",
      "last_name": "Mustermann",
      "street": "",
      "zip": "",
      "city": "",
      "state": "",
      "country_code": "",
      "phone": "",
      "fax": "",
      "mobile": "+49 151 12345678",
      "email": "erika@musterfirma.de",
      "www": ""
    }
  }
}

 

Einzelnen Kontakt abrufen

Request:

GET /api/contacts/{id}

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/contacts/4?format=json

Response (200 OK):

{
  "contact": {
    "id": "4",
    "created": "2013-05-27T12:07:37+02:00",
    "client_id": "789",
    "label": "Einkauf",
    "name": "",
    "salutation": "Frau",
    "first_name": "Erika",
    "last_name": "Mustermann",
    "street": "",
    "zip": "",
    "city": "",
    "state": "",
    "country_code": "",
    "phone": "",
    "fax": "",
    "mobile": "+49 151 12345678",
    "email": "erika@musterfirma.de",
    "www": ""
  }
}

 

Kontakt anlegen

Nur client_id ist Pflichtfeld. Alle anderen Felder sind optional – leere Felder erben automatisch den Wert des übergeordneten Kunden.

Request:

POST /api/contacts

curl -X POST \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/json' \
  -d '{
    "contact": {
      "client_id": "789",
      "label": "Einkauf",
      "salutation": "Frau",
      "first_name": "Erika",
      "last_name": "Mustermann",
      "mobile": "+49 151 12345678",
      "email": "erika@musterfirma.de"
    }
  }' \
  https://{deineBillomatID}.billomat.net/api/contacts

Response (201 Created):

{
  "contact": {
    "id": "4",
    "created": "2024-06-01T10:00:00+02:00",
    "client_id": "789",
    "label": "Einkauf",
    "name": "",
    "salutation": "Frau",
    "first_name": "Erika",
    "last_name": "Mustermann",
    "street": "",
    "zip": "",
    "city": "",
    "state": "",
    "country_code": "",
    "phone": "",
    "fax": "",
    "mobile": "+49 151 12345678",
    "email": "erika@musterfirma.de",
    "www": ""
  }
}

Alle verfügbaren Felder beim Anlegen eines Kontakts:

Feld Typ Pflicht Beschreibung
client_id INT ✓ ID des übergeordneten Kunden
label ALNUM — Bezeichnung / Funktion des Kontakts (z.B. "Einkauf", "Buchhaltung")
name ALNUM — Firmenname des Kontakts (abweichend vom Kunden)
salutation ALNUM — Anrede
first_name ALNUM — Vorname
last_name ALNUM — Nachname
street ALNUM — Straße (leer = Adresse des Kunden)
zip ALNUM — Postleitzahl
city ALNUM — Ort
state ALNUM — Bundesland, Bezirk, Region
country_code ISO 3166 — Ländercode (z.B. DE, AT, CH)
phone ALNUM — Telefon
fax ALNUM — Fax
mobile ALNUM — Mobiltelefon
email E-Mail — E-Mail-Adresse
www URL — Website (ohne http)

 

Kontakt bearbeiten

Es gelten dieselben Felder wie beim Anlegen. Nur die zu ändernden Felder müssen mitgeschickt werden.

Request:

PUT /api/contacts/{id}

curl -X PUT \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/json' \
  -d '{"contact": {"first_name": "Hans", "last_name": "Mustermann"}}' \
  https://{deineBillomatID}.billomat.net/api/contacts/4

Response (200 OK) – vollständiger aktualisierter Kontakt.

 

Kontakt löschen

Request:

DELETE /api/contacts/{id}

curl -X DELETE \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/contacts/4

Response (200 OK) – kein Body.

 

Kontaktbild abrufen

Liefert das hinterlegte Kontaktbild in der gewünschten Größe (quadratisch zugeschnitten). Die Größe in Pixel wird über den Parameter size angegeben.

GET /api/contacts/{id}/avatar?size=100

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/contacts/4/avatar?size=100

 

Verwandte Artikel

 

Verknüpfung mit

Kommentare

0 Kommentare

Zu diesem Beitrag können keine Kommentare hinterlassen werden.