Kunde anlegen

Legt einen Kunden an und liefert ihn mit geladenen Adressen, Verantwortlichen, Kategorien und dynamischen Attributen zurück.

Verfügbarkeit: Nur Vollversion — eine Clock-Instanz antwortet auf diesen Endpunkt mit 404.

Request

POST /api/v1/customers

curl --request POST \
     --url 'https://www.zep-online.de/zepinstanz/next/api/v1/customers' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {token}' \
     --header 'Content-Type: application/json' \
     --data '{
       "customer_number": "K-12345",
       "name": "EU",
       "additional_name": "ACME Corp",
       "website": "www.acme-corp.com",
       "email": "erika.mustermann@acme-corp.de",
       "phone": "+49 30 12345678",
       "fax": "+1-555-0124",
       "currency": "EUR",
       "comments": "Wichtiger Kunde - mit Sorgfalt behandeln",
       "industry": "Technologie",
       "vat": 1.5,
       "tax_number": "DE123456789",
       "iban": "DE89370400440532013000",
       "bic": "COBADEFFXXX",
       "payment_target": 30,
       "payment_target_discount": 2,
       "inactive": false,
       "billing_procedure": true,
       "automated_invoicing": true,
       "debit_payment": false,
       "department_id": 1,
       "dynamicAttributes": [
         [
           "string"
         ]
       ],
       "categories": [
         "string"
       ],
       "travel_expense_flat_per_day": 1,
       "travel_expense_flat_per_journey": 1,
       "status": 1
     }'

Request-Body

Name
customer_number
Type
string, erforderlich
Description
Die eindeutige Kennung des Kunden — muss über alle Kunden hinweg eindeutig sein.
Name
name
Type
string, erforderlich
Description
Name des Kunden.
Name
additional_name
Type
string, nullable
Description
Zusätzliche Namenszeile des Kunden, wird auf Dokumenten unter name gedruckt.
Name
website
Type
string, nullable
Description
Website-URL des Kunden.
Name
email
Type
string (email), nullable
Description
Allgemeine Kontakt-E-Mail-Adresse des Kunden.
Name
phone
Type
string, nullable
Description
Telefonnummer des Kunden.
Name
fax
Type
string, nullable
Description
Faxnummer des Kunden.
Name
currency
Type
string, erforderlich
Description
Der ISO-Währungscode, der für Angebote und Rechnungen dieses Kunden verwendet wird.
Name
comments
Type
string, nullable
Description
Interne Freitext-Notizen zum Kunden.
Name
industry
Type
string, nullable
Description
Name der Branche, der dieser Kunde angehört.
Name
vat
Type
number, nullable
Description
Umsatzsteuersatz des Kunden in Prozent.
Name
tax_number
Type
string, nullable
Description
Die Steuernummer des Kunden.
Name
iban
Type
string, nullable
Description
IBAN des Kunden, wird für das SEPA-Lastschriftverfahren verwendet.
Name
bic
Type
string, nullable
Description
BIC des Kunden, wird zusammen mit iban für das SEPA-Lastschriftverfahren verwendet.
Name
payment_target
Type
integer, nullable
Description
Anzahl der Tage, die der Kunde zur Zahlung einer Rechnung hat, gerechnet ab Rechnungsdatum.
Name
payment_target_discount
Type
integer, nullable
Description
Anzahl der Tage, innerhalb derer dem Kunden bei Zahlung ein Skonto gewährt wird.
Name
inactive
Type
boolean, nullable
Description
Ob der Kunde als inaktiv markiert und aus den Listen aktiver Kunden ausgeblendet werden soll.
Name
billing_procedure
Type
boolean, nullable
Description
Ob dieser Kunde per Standardrechnung oder im Gutschriftverfahren (Self-Billing) abgerechnet wird.
Name
automated_invoicing
Type
boolean, nullable
Description
Ob Rechnungen für diesen Kunden automatisch statt manuell erzeugt werden sollen.
Name
debit_payment
Type
boolean, nullable
Description
Ob dieser Kunde per SEPA-Lastschrift statt per Überweisung zahlt.
Name
department_id
Type
integer, erforderlich
Description
Die ID der Abteilung, der dieser Kunde zugeordnet ist. Ohne Angabe wird die Standardabteilung verwendet.
Name
dynamicAttributes
Type
Liste von array, nullable
Description
Werte benutzerdefinierter dynamischer Attribute, die am Kunden gesetzt werden, mit dem Attributnamen als Schlüssel.
Name
categories
Type
Liste von string, nullable
Description
Die IDs der Kategorien, die dem Kunden zugeordnet werden sollen.
Name
travel_expense_flat_per_day
Type
integer, nullable
Description
Welche Reisekostenpauschale pro Tag für diesen Kunden gilt, falls vorhanden.
Name
travel_expense_flat_per_journey
Type
integer, nullable
Description
Welche Reisekostenpauschale pro Fahrt für diesen Kunden gilt, falls vorhanden.
Name
status
Type
integer, nullable
Description
Deprecated alias for the inverse of inactive: 1 means active, 0 inactive. An explicit inactive wins, and an unparseable value is ignored rather than guessed.

Response

{
  "data": {
    "customer_number": "K-12345",
    "name": "EU",
    "additional_name": "ACME Corp",
    "website": "www.acme-corp.com",
    "email": "erika.mustermann@acme-corp.de",
    "phone": "+49 30 12345678",
    "fax": "+1-555-0124",
    "currency": "EUR",
    "comments": "Wichtiger Kunde - mit Sorgfalt behandeln",
    "industry": "Technologie",
    "vat": "string",
    "tax_number": "DE123456789",
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX",
    "payment_target": "string",
    "payment_target_discount": 2,
    "inactive": false,
    "status": {
      "value": 0,
      "label": "Inactive"
    },
    "created": "2024-07-20T11:30:00.000000Z",
    "modified": "2024-07-20T12:30:00.000000Z",
    "billing_procedure": true,
    "automated_invoicing": true,
    "debit_payment": false,
    "department_id": 1,
    "addresses": [
      {
        "id": 1,
        "name": "EU",
        "address": "Musterstraße 123",
        "address_line_2": "string",
        "address_line_3": "string",
        "zip_code": "10115",
        "city": "Berlin",
        "country": "Deutschland",
        "is_default": true,
        "is_billing_address": true,
        "is_shipping_address": true,
        "email": "erika.mustermann@acme-corp.de",
        "email_cc": "string",
        "email_bcc": "string",
        "country_code": "string",
        "inactive": false,
        "machine_readable_invoice_version": {
          "id": 1,
          "name": "ZUGFeRD1"
        }
      }
    ],
    "managers": [
      {
        "username": "max.mustermann",
        "has_edit_customer_data_permission": true,
        "has_budget_responsibility_permission": true,
        "is_primary_employee": true
      }
    ],
    "categories": [
      {
        "name": "EU",
        "description": {
          "de": "string",
          "en": "string",
          "fr": "string",
          "es": "string",
          "pl": "string"
        },
        "type": {
          "id": "string",
          "name": "Mitarbeiter/in"
        }
      }
    ],
    "dynamicAttributes": [
      {
        "name": "EU",
        "value": "Max Mustermann (Bruder)",
        "type": "Text",
        "description": {
          "de": "string",
          "en": "string",
          "fr": "string",
          "es": "string",
          "pl": "string"
        }
      }
    ],
    "addresses_count": 2,
    "managers_count": 1,
    "categories_count": 0,
    "dynamicAttributes_count": 0,
    "contacts_count": 3,
    "priceTables": [
      {
        "id": 1,
        "start_date": "2024-01-15T00:00:00.000000Z",
        "customer_number": "K-12345",
        "project_id": 16,
        "type": {
          "id": "string",
          "name": "Basispreistabelle"
        },
        "prices": [
          {
            "id": 1,
            "price_group": "Junior-Entwickler",
            "price": 1.5,
            "price_table_id": "string",
            "type": {
              "id": "string",
              "name": "Stundensatz"
            },
            "activity": "string",
            "ahr_factor": 1.5
          }
        ],
        "factors": [
          {
            "id": 1,
            "day": {
              "id": 1,
              "name": "So"
            },
            "start_time": "11:10:49",
            "end_time": "15:10:49",
            "factor": 1.5,
            "price_table_id": 1,
            "activity_id": 1
          }
        ]
      }
    ]
  }
}

Response-Felder

Name
customer_number
Type
string
Description
Eindeutige Kennung des Kunden; wird in der URL als Primärschlüssel verwendet.
Name
name
Type
string, nullable
Description
Name des Kunden.
Name
additional_name
Type
string, nullable
Description
Zusätzliche Namenszeile des Kunden, wird auf Dokumenten unter name gedruckt.
Name
website
Type
string, nullable
Description
Website-URL des Kunden.
Name
email
Type
string, nullable
Description
Allgemeine Kontakt-E-Mail-Adresse des Kunden.
Name
phone
Type
string, nullable
Description
Telefonnummer des Kunden.
Name
fax
Type
string, nullable
Description
Faxnummer des Kunden.
Name
currency
Type
string, nullable
Description
ISO-Währungscode für Angebote und Rechnungen dieses Kunden.
Name
comments
Type
string, nullable
Description
Interne Freitext-Notizen zum Kunden.
Name
industry
Type
string, nullable
Description
Name der Branche, der dieser Kunde angehört.
Name
vat
Type
string, nullable
Description
Umsatzsteuersatz des Kunden in Prozent.
Name
tax_number
Type
string, nullable
Description
Umsatzsteuer-Identifikationsnummer des Kunden — nicht der Steuersatz, siehe vat.
Name
iban
Type
string, nullable
Description
IBAN des Kunden, wird für das SEPA-Lastschriftverfahren verwendet.
Name
bic
Type
string, nullable
Description
BIC des Kunden, wird zusammen mit iban für das SEPA-Lastschriftverfahren verwendet.
Name
payment_target
Type
string, nullable
Description
Anzahl der Tage, die der Kunde zur Zahlung einer Rechnung hat, gerechnet ab Rechnungsdatum.
Name
payment_target_discount
Type
integer, nullable
Description
Anzahl der Tage, innerhalb derer dem Kunden bei Zahlung ein Skonto gewährt wird.
Name
inactive
Type
boolean
Description
Ob der Kunde inaktiv ist und in Listen aktiver Kunden ausgeblendet wird.
Name
status
Type
object
Description
Veralteter Alias von inactive, aus Gründen der Rückwärtskompatibilität beibehalten. Lesen Sie stattdessen inactive. label wird in die Sprache des Mandanten übersetzt ausgeliefert und darf nicht ausgewertet werden — vergleichen Sie stattdessen value. Abgekündigt seit 2025-10-28. Verwenden Sie stattdessen inactive. Kann ab dem 2027-08-31 entfernt werden. Ab API v2 nicht mehr enthalten.
Name
status.value
Type
integer
Description
1, wenn der Kunde aktiv ist, 0, wenn inaktiv — das Gegenteil von inactive.
Einer der Werte: 0, 1
Name
status.label
Type
string
Description
Der Status als übersetzte, menschenlesbare Zeichenkette. Nicht parsen, sondern stattdessen value vergleichen.
Einer der Werte: "Inactive", "Active"
Name
created
Type
string (date-time), nullable
Description
Zeitpunkt, zu dem der Kundendatensatz angelegt wurde.
Name
modified
Type
string (date-time), nullable
Description
Zeitpunkt, zu dem der Kundendatensatz zuletzt geändert wurde.
Name
billing_procedure
Type
boolean, nullable
Description
Ob dieser Kunde per Standardrechnung oder im Gutschriftverfahren (Self-Billing) abgerechnet wird.
Name
automated_invoicing
Type
boolean, nullable
Description
Ob Rechnungen für diesen Kunden automatisch erzeugt statt manuell erstellt werden.
Name
debit_payment
Type
boolean, nullable
Description
Ob dieser Kunde per SEPA-Lastschrift statt per Überweisung zahlt.
Name
department_id
Type
integer
Description
ID der Abteilung, der dieser Kunde zugeordnet ist.
Name
addresses
Type
Liste von CustomerAddress
Description
Die Adressen des Kunden. Enthalten bei GET /customers/{customer}, POST /customers und PUT /customers/{customer}; nicht enthalten bei GET /customers (dem Listen-Endpunkt).
Name
addresses.id
Type
integer
Description
Eindeutige ID der Adresse.
Name
addresses.name
Type
string
Description
Der auf dieser Adresse gedruckte Empfängername.
Name
addresses.address
Type
string, nullable
Description
Erste Adresszeile (Straße und Hausnummer).
Name
addresses.address_line_2
Type
string, nullable
Description
Optionale zweite Adresszeile.
Name
addresses.address_line_3
Type
string, nullable
Description
Optionale dritte Adresszeile.
Name
addresses.zip_code
Type
string, nullable
Description
Die Postleitzahl.
Name
addresses.city
Type
string, nullable
Description
Ort, in dem sich diese Adresse befindet.
Name
addresses.country
Type
string, nullable
Description
Der Ländername.
Name
addresses.is_default
Type
boolean, nullable
Description
Ob dies die Standardadresse des Kunden ist.
Name
addresses.is_billing_address
Type
boolean, nullable
Description
Ob Rechnungen an diese Adresse gesendet werden.
Name
addresses.is_shipping_address
Type
boolean, nullable
Description
Ob Lieferungen an diese Adresse gesendet werden.
Name
addresses.email
Type
string, nullable
Description
E-Mail-Adresse, an die Dokumente für diese Adresse gesendet werden.
Name
addresses.email_cc
Type
string, nullable
Description
Zusätzliche E-Mail-Adresse, die bei Dokumenten an diese Adresse in Kopie (CC) gesetzt wird.
Name
addresses.email_bcc
Type
string, nullable
Description
Zusätzliche E-Mail-Adresse, die bei Dokumenten an diese Adresse in Blindkopie (BCC) gesetzt wird.
Name
addresses.country_code
Type
string, nullable
Description
ISO-Ländercode für die E-Rechnung (ZUGFeRD/XRechnung).
Name
addresses.inactive
Type
boolean, nullable
Description
Ob diese Adresse inaktiv ist und nicht mehr verwendet wird.
Name
addresses.machine_readable_invoice_version
Type
object, nullable
Description
Maschinenlesbares E-Rechnungsformat (z. B. ZUGFeRD, XRechnung), das diese Adresse unterstützt, sofern vorhanden.
Name
managers
Type
Liste von CustomerEmployee
Description
Die für diesen Kunden verantwortlichen Mitarbeiter. Enthalten bei GET /customers/{customer}, POST /customers und PUT /customers/{customer}; nicht enthalten bei GET /customers.
Name
managers.username
Type
string
Description
Benutzername des für diesen Kunden verantwortlichen Mitarbeiters.
Name
managers.has_edit_customer_data_permission
Type
boolean, nullable
Description
Ob dieser Mitarbeiter die Stammdaten des Kunden bearbeiten darf.
Name
managers.has_budget_responsibility_permission
Type
boolean, nullable
Description
Ob dieser Mitarbeiter Budgetverantwortung für diesen Kunden hat.
Name
managers.is_primary_employee
Type
boolean, nullable
Description
Ob dieser Mitarbeiter der Hauptverantwortliche des Kunden ist.
Name
categories
Type
Liste von Category
Description
Die diesem Kunden zugeordneten Kategorien. Enthalten bei allen vier Kunden-Endpunkten (GET /customers, GET /customers/{customer}, POST /customers, PUT /customers/{customer}).
Name
categories.name
Type
string
Description
Name der Kategorie, wird überall angezeigt, wo eine Entität damit gekennzeichnet ist.
Name
categories.description
Type
object
Description
Ausführlichere Erläuterung, wofür diese Kategorie verwendet werden soll.
Name
categories.type
Type
object
Description
Art der Entität, der diese Kategorie zugeordnet werden kann, z. B. Mitarbeiter, Projekt oder Kunde.
Name
dynamicAttributes
Type
Liste von DynamicAttribute
Description
Die benutzerdefinierten dynamischen Attribute des Kunden. Enthalten bei allen vier Kunden-Endpunkten (GET /customers, GET /customers/{customer}, POST /customers, PUT /customers/{customer}).
Name
dynamicAttributes.name
Type
string
Description
Name der Definition des dynamischen Attributs, für die dieser Wert eingegeben wurde.
Name
dynamicAttributes.value
Type
any
Description
Der gespeicherte Wert; seine Form hängt vom benachbarten Feld type ab (eine Zeichenkette, eine Zahl, ein Boolean, ein Datum, eine Mitarbeiterreferenz oder eine Liste von Optionswerten).
Name
dynamicAttributes.type
Type
string
Description
Datentyp dieses Attributs, z. B. Text, Zahl, Datum oder Optionen; bestimmt, wie value zu interpretieren ist.
Einer der Werte: "Text", "Integer", "Float", "URL", "E-Mail", "Datum", "Uhrzeit", "Datetime", "Boolean", "Betrag", "Optionen", "Prozent", "Time period", "Textarea", "Users", "Upload"
Name
dynamicAttributes.description
Type
object, nullable
Description
Erläuterung, was dieses Attribut erfasst, wie in seiner Definition konfiguriert.
Name
addresses_count
Type
integer
Description
Anzahl der Adressen dieses Kunden. Nur enthalten bei GET /customers (dem Listen-Endpunkt).
Name
managers_count
Type
integer
Description
Anzahl der für diesen Kunden verantwortlichen Mitarbeiter. Nur enthalten bei GET /customers.
Name
categories_count
Type
integer
Description
Anzahl der diesem Kunden zugeordneten Kategorien. Nur enthalten bei GET /customers.
Name
dynamicAttributes_count
Type
integer
Description
Anzahl der bei diesem Kunden gesetzten benutzerdefinierten dynamischen Attribute. Nur enthalten bei GET /customers.
Name
contacts_count
Type
integer
Description
Anzahl der Ansprechpartner dieses Kunden. Nur enthalten bei GET /customers.
Name
priceTables
Type
Liste von PriceTable
Description
Die Preistabellen des Kunden — die eigenen, falls zugewiesen, andernfalls die Basis-Preistabellen. Enthalten bei GET /customers/{customer}, POST /customers und PUT /customers/{customer}; nicht enthalten bei GET /customers (dem Listen-Endpunkt). Es gibt keinen clientseitigen Parameter, um sie anzufordern oder zu unterdrücken.
Name
priceTables.id
Type
integer
Description
Eindeutige Kennung der Preistabelle.
Name
priceTables.start_date
Type
string (date-time), nullable
Description
Datum, ab dem die Preistabelle gilt.
Name
priceTables.customer_number
Type
string, nullable
Description
Nummer des Kunden, zu dem diese Preistabelle gehört, bei einer Preistabelle auf Kundenebene.
Name
priceTables.project_id
Type
integer, nullable
Description
Kennung des Projekts, zu dem diese Preistabelle gehört, bei einer Preistabelle auf Projektebene.
Name
priceTables.type
Type
object, nullable
Description
Ob die Preistabelle einem Kunden oder einem Projekt zugeordnet ist.
Name
priceTables.prices
Type
Liste von Price
Description
In dieser Preistabelle definierte Preise.
Name
priceTables.factors
Type
Liste von PriceFactor
Description
In dieser Preistabelle definierte zeitabhängige Faktoren, z. B. für Nacht- oder Wochenendzuschläge.

Aus der OpenAPI-Spezifikation erzeugt — Änderungen gehören in den Quellcode, nicht auf diese Seite.

GET Kunde abrufen PATCH Kunde aktualisieren