Customers

Eine Customer in go~mus ist die natürliche oder juristische Person, die eine Bestellung tätigt - der Kontakt, an den Tickets gehen, Rechnungen ausgestellt werden, Newsletter geliefert werden. Wenn du ein eigenes CRM, eine Mitglieder-Verwaltung oder ein Schulen-Portal an go~mus anbindet, ist die Customers-Resource die Brücke.

Der zentrale Mechanismus: foreign_id. Ein optionales String-Feld, in das die ID deines Systems geschrieben wird. Damit kannst du Customers in go~mus über den externen Schlüssel finden und aktualisieren, ohne erst eine Lookup-Tabelle zu pflegen.

Vollständige Endpoint- und Schema-Referenz: Swagger.

Das foreign_id-Pattern

In einer typischen CRM-Integration hast du in eurem System eine eindeutige Kunden-ID (SF-12345, BREVO-abcde, MEMBER-2026-007). du willst diese ID auch in go~mus haben, ohne mit go~mus-IDs jonglieren zu müssen.

Lösung: setzt beim Anlegen eines Customers foreign_id auf deine ID:

curl -X POST "https://demo.gomus.de/api/v4/customers" \
  -H "Authorization: Bearer YOUR_API_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "foreign_id": "SF-12345",
      "name": "Müller", "surname": "Anna",
      "email": "anna@example.com"
    }
  }'

Danach kannst du beim Lookup und Update deine ID statt der go~mus-ID verwenden:

curl "https://demo.gomus.de/api/v4/customers/SF-12345" \
  -H "Authorization: Bearer YOUR_API_USER_TOKEN"

curl -X PUT "https://demo.gomus.de/api/v4/customers/SF-12345" \
  -H "Authorization: Bearer YOUR_API_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "customer": { "tel": "+49 30 99887766" } }'

Der Server probiert erst die numerische ID, dann foreign_id - dein Code wird so deutlich kürzer als mit Lookup-Tabelle.

Endpoints im Überblick

Endpoint	Wofür	Auth
GET /api/v4/customers/salutations	Verfügbare Anreden (Frau, Herr, divers, ...)	Public
GET /api/v4/customers/titles	Verfügbare Titel (Dr., Prof., ...)	Public
POST /api/v4/customers	Customer anlegen (auch im Batch)	API-User mit Permission
GET /api/v4/customers/:id	Customer-Detail (id oder foreign_id)	API-User
PUT /api/v4/customers/:id	Customer aktualisieren	API-User mit Permission
PUT /api/v4/customers	Batch-Update via foreign_id	API-User
DELETE /api/v4/customers/:id	Customer löschen	API-User mit Permission

Alle Endpoints außer Salutations und Titles brauchen einen authentifizierten API-User. Public-Tokens reichen hier nicht.

Anatomie eines Customer-Objekts

Stammdaten:

• id - go~mus-Primärschlüssel
• foreign_id - deine externe ID (optional, aber empfohlen für CRM-Sync)
• name, surname - Vor- und Nachname
• email, tel, mobile, fax - Kontaktwege
• customer_salutation_id, customer_title_id - Anrede und Titel via vorhandene IDs (siehe Salutations/Titles)
• is_institution - Boolean: ist es eine Organisation, kein Privatperson
• institution - Organisationsname, falls is_institution: true
• notes - Freitext-Notizen
• language_id - bevorzugte Sprache für E-Mail-Templates
• date_of_birth - falls altersrelevant
• vat_number - USt-ID

Adresse als Sub-Objekt: alle Adressfelder werden mit Prefix addr_ übergeben:

• addr_street, addr_zip, addr_city, addr_country_id
• addr_institution_id - falls die Adresse einer hinterlegten Institution zugeordnet ist
• addr_category - Preisgruppe für diese Adresse (PTA-Name oder ID)

Beim Update werden die addr_*-Felder auf der ersten hinterlegten Adresse des Customers angewandt.

Häufige Aufgaben

Anreden und Titel laden (für Formulare)

curl "https://demo.gomus.de/api/v4/customers/salutations?locale=de"
curl "https://demo.gomus.de/api/v4/customers/titles?locale=de"

Public, kein Token nötig. Liefert IDs, die du beim Anlegen als customer_salutation_id / customer_title_id verwendest.

Customer anlegen

curl -X POST "https://demo.gomus.de/api/v4/customers" \
  -H "Authorization: Bearer YOUR_API_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "foreign_id": "MEMBER-2026-007",
      "name": "Schmidt", "surname": "Lukas",
      "email": "lukas@example.com",
      "tel": "+49 30 12345",
      "is_institution": false,
      "addr_street": "Beispielallee 12",
      "addr_zip": "10115",
      "addr_city": "Berlin",
      "addr_country_id": 1
    }
  }'

Antwort: das angelegte Customer-Objekt mit id und allen gesetzten Feldern.

Customer im Batch anlegen

curl -X POST "https://demo.gomus.de/api/v4/customers" \
  -H "Authorization: Bearer YOUR_API_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": [
      { "foreign_id": "M-001", "name": "Schmidt", "surname": "Lukas", "email": "..." },
      { "foreign_id": "M-002", "name": "Meier", "surname": "Tina", "email": "..." }
    ]
  }'

Statt eines einzelnen Objekts ein Array. Es gibt eine instance-spezifische Obergrenze pro Batch - bei sehr großen Imports in mehreren Calls senden.

Customer finden über foreign_id

curl "https://demo.gomus.de/api/v4/customers/MEMBER-2026-007" \
  -H "Authorization: Bearer YOUR_API_USER_TOKEN"

Der Server probiert numerische ID zuerst, fällt auf foreign_id zurück. Saubere Vorbedingung: dein foreign_id-Format kollidiert nicht mit numerischen IDs.

Customer aktualisieren

curl -X PUT "https://demo.gomus.de/api/v4/customers/MEMBER-2026-007" \
  -H "Authorization: Bearer YOUR_API_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "tel": "+49 30 99887766",
      "addr_street": "Neue Straße 5"
    }
  }'

Felder, die nicht im Body stehen, bleiben unverändert.

Batch-Update via foreign_id

curl -X PUT "https://demo.gomus.de/api/v4/customers" \
  -H "Authorization: Bearer YOUR_API_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": [
      { "foreign_id": "M-001", "tel": "+49 30 11..." },
      { "foreign_id": "M-002", "email": "tina-neu@..." }
    ]
  }'

Pro Eintrag ist foreign_id der Schlüssel - go~mus findet den passenden Customer und aktualisiert die mitgeschickten Felder.

Customer in der Order

Beim Order-Create gibt es zwei Wege, einen Customer dranzuhängen:

• Customer-Daten direkt im Order-Body - go~mus legt einen Customer an oder findet einen existierenden über E-Mail
• Customer-ID referenzieren - wenn du den Customer schon angelegt hast, hängt nur die customer_id (oder foreign_id) am Order

Pattern für CRM-Sync: erst Customer anlegen mit foreign_id, dann Order auf diese foreign_id referenzieren. So bleiben deine Datensätze in beiden Systemen konsistent verlinkt.

Beziehungen

Customer
 ├── foreign_id ............. deine externe ID (optional)
 ├── CustomerSalutation ..... Anrede
 ├── CustomerTitle .......... Titel
 ├── CustomerAddress (1..n) . erste wird über addr_* aktualisiert
 ├── Institution (über addr) wenn institutionell
 ├── PriceTargetAudience .... Preisgruppe
 ├── Order (0..n) ........... Bestellungen dieser Person
 └── NewsletterSubscription (0..n)

Stolperdrahte

• API-User-Auth ist Pflicht. Customer-Endpoints (außer Salutations/Titles) sind nicht öffentlich. Token niemals im Frontend einbetten - serverseitig durchreichen.
• foreign_id-Format mit numerischen IDs nicht überlappen. Wenn deine CRM-IDs zufällig wie go~mus-IDs aussehen (12345), wird der Lookup-Vorrang erst die numerische ID probieren - du siehst möglicherweise nicht den erwarteten Customer. Präfixe wie SF-, MEMBER-, BREVO- sind deine Freunde.
• Adress-Update geht nur auf der ersten Adresse. addr_*-Felder im Update zielen immer auf die erste Adresse des Customers. Wer mehrere Adressen pro Customer pflegt (Rechnungs- vs Lieferadresse), muss diese außerhalb der Customers-Endpoints separat synchronisieren.
• Customers haben Bestellungs- und Newsletter-Bezug. Ein Customer-Delete kaskadiert nicht - Bestellungen und Newsletter-Subscriptions bleiben. Wer DSGVO-konforme Löschung braucht, sollte sich der Order-Bezüge im eigenen Code bewusst sein und vorab anonymisieren oder löschen.
• Salutations/Titles vor dem Anlegen holen. Die IDs sind instance-spezifisch (Custom-Salutations sind möglich). Cache die Liste lokal, aber holt sie beim Setup einmal frisch.
• Batch-Limit beachten. Für sehr große Imports kommt sonst customer(s) could not be saved mit Detail-Fehlern.

Verwandte Seiten

• Authentifizierung - API-User-Token, Permissions, foreign_id im Order-Kontext
• Best Practices - foreign_id für Customer-Mapping, Idempotenz
• Errors - 422-Validierungsfehler bei Customer-Anlage
• Konzepte - Order, foreign_id-Pattern