Kontakte über die belegFuchs API verwalten
Auf dieser Seite erfahren Sie, wie Sie Kontakte über die API verwalten können.
API-Endpunkt
Der API-Endpunkt für Kontakte lautet https://api.belegfuchs.de/v1/contacts
.
Kontaktdaten
Feldname | Typ | Optional | Min. | Max. | Beschreibung |
---|---|---|---|---|---|
id | String/Int | --- | --- | --- | Bei der id handelt es sich um den PRIMARY_KEY . Das id -Feld wird automatisch bei der Erstellung gesetzt und kann nicht bearbeitet werden. Der Datentyp der id ist ein numerischer String . In API-Antworten wird also ein String zurückgegeben, der aber immer numerisch ist. |
number | String/Int | Nein | --- | --- | Die auf Kontoebene eindeutige und fortlaufende Nummer des Kontakts. Int oder auto . number ist nicht der PRIMARY_KEY , sondern die Kontaktnummer die z.B auf Rechnungen dargestellt wird. |
idNumber | String/Int | Ja | --- | --- | Die Kreditoren- oder Debitorennummer. Wenn Sie keine Nummer vergeben, wird automatisch eine Nummer vergeben. |
customId | String? | Ja | --- | 255 | Die Benutzerdefinierte Id. Hier können Sie beispielsweise die Stripe-customerId oder die Id Ihres Systems hinterlegen. |
isBusiness | Int | Nein | 0 | 1 | Gibt an, ob es sich um einen Geschäftskunden handelt. 0 = nein, 1 = ja. |
businessName | String | Ja | --- | 50 | Der Name des Geschäftskunden - muss nur ausgefüllt werden wenn isBusiness = 1 . |
firstname | String | Ja | --- | 30 | Der Vorname des Kontakts - muss nur ausgefüllt werden wenn isBusiness = 0 . |
lastname | String | Ja | --- | 30 | Der Nachname des Kontakts - muss nur ausgefüllt werden wenn isBusiness = 0 . |
street | String | Ja | --- | 255 | Die Straße des Kontakts. |
houseNumber | String | Ja | --- | 10 | Die Hausnummer des Kontakts. |
postalCode | String | Ja | --- | 10 | Die Postleitzahl des Kontakts. |
city | String | Ja | --- | 255 | Die Stadt des Kontakts. |
countryCode | String | Nein | 2 | 2 | Der Ländercode des Kontakts. Im ISO 3166-1 alpha-2 -Format. |
gender | Int | Ja | 0 | 1 | Das Geschlecht des Kontakts - muss nur ausgefüllt werden wenn isBusiness = 0 . 0 = weiblich, 1 = männlich |
contactType | String | Nein | --- | --- | Der Kontakttyp. Customer = Kunde, Supplier = Lieferant. |
note | String | Ja | --- | 500 | Eine Notiz zum Kontakt. |
taxNumber | String | Ja | --- | 13 | Die Steuernummer des Kontakts. |
vatNumber | String | Ja | --- | 11 | Die Umsatzsteuer-ID des Kontakts. |
emails | Array | Ja | --- | 10 | Ein Array mit Objekten von E-Mail-Adressen und Beschreibungen. |
phoneNumbers | Array | Ja | --- | 10 | Ein Array mit Objekten von Telefonnummern und Beschreibungen. |
created | String | --- | --- | --- | Das Erstellungsdatum im ISO 8601 Format. z.B 2023-12-31T00:00:00.000Z . Dieser Wert ist ein reiner Rückgabewert. |
Kontakt erstellen
Um einen neuen Kontakt zu erstellen, müssen Sie einen POST-Request an den Endpunkt senden.
Beispiel Payload
{
"number": "1000",
"idNumber": "10000",
"isbusiness": 0,
"firstname": "Max",
"lastname": "Mustermann",
"gender": 1,
"countryCode": "de",
"postalCode": "53757",
"city": "Sankt Augustin",
"street": "Teststraße",
"contactType": "Customer",
"houseNumber": "1a",
"emails": [
{
"email": "max@beispiel.com",
"description": "Privat"
},
],
"phoneNumbers": [
{
"phoneNumber": "1234",
"description": "Geschäftlich"
}
]
}
Nummerverwaltung
Die Nummer eines Kontakts muss eindeutig und fortlaufend sein. Wenn Sie versuchen einen Kontakt mit einer Nummer erstellen, die bereits existiert oder die kleiner ist als die letzte Nummer, erhalten Sie einen 409 Conflict
Fehler. Um dies zu verhindern, können Sie als number
den wert auto
übergeben. In diesem Fall wird automatisch die nächste freie Nummer oder 1
vergeben falls noch kein Kontakt existert.
Beispiel Payload mit automatischer Nummernvergabe
{
"number": "auto",
...
}
Antwort
Mögliche Antworten sind:
200 OK
: Der Kontakt wurde erfolgreich erstellt. Die Antwort enthält die Daten des erstellten Kontakts.400 Bad Request
: Es wurden nicht alle benötigten Daten übermittelt oder die Daten sind fehlerhaft.401 Unauthorized
: Der API-Key ist ungültig.409 Conflict
: Es existiert bereits ein Kontakt mit der angegebenen Nummer.
Kontakt aktualisieren
Um einen Kontakt zu aktualisieren, müssen Sie einen PUT-Request an den Endpunkt senden.
Beispiel Payload
{
"firstname": "Max",
"lastname": "Mustermann",
"gender": 1,
"countryCode": "de",
"postalCode": "53757",
"city": "Sankt Augustin",
"street": "Teststraße",
"houseNumber": "1a",
"emails": [
{
email: "max@beispiel.com",
description: "Privat"
}
],
"phoneNumbers": [
{
"phoneNumber": "1234",
"description": "Geschäftlich"
}
]
}
Wenn Sie Datenfelder leer lassen, werden diese nicht aktualisiert. Beachten Sie aber, dass die Datenfelder number
und isBusiness
nicht aktualisiert werden können. Außer dem, werden alle E-Mails und Telefonnummern des Kontakts gelöscht und durch die neuen ersetzt, wenn Sie die alten nicht mit übergeben.
Wenn Sie also die E-Mails und Telefonnummern nicht aktualisieren möchten, müssen Sie die alten mit übergeben, ansonsten werden diese gelöscht.
Antwort
Mögliche Antworten sind:
200 OK
: Der Kontakt wurde erfolgreich aktualisiert. Die Antwort enthält die Daten des aktualisierten Kontakts.400 Bad Request
: Es wurden nicht alle benötigten Daten übermittelt oder die Daten sind fehlerhaft.401 Unauthorized
: Der API-Key ist ungültig.
Kontakt mithilfe der customId aktualisieren
Um einen Kontakt mithilfe der customId
zu aktualisieren, müssen Sie einen PUT-Request in folgendem Format an den Endpunkt senden:
https://api.belegfuchs.de/v1/contacts/byCustomId
Vergessen Sie nicht die customId
in dem Payload zu übergeben.
Antwort
Mögliche Antworten sind:
200 OK
: Der Kontakt wurde erfolgreich abgerufen. Die Antwort enthält die Daten des Kontakts.401 Unauthorized
: Der API-Key ist ungültig.
Kontakte abrufen
Um alle Kontakte abzurufen, müssen Sie einen GET-Request an den Endpunkt mit folgenden parametern senden:
https://api.belegfuchs.de/v1/contacts?page=1
Parameter | Typ | Optional | Beschreibung |
---|---|---|---|
page | Int | Nein | Die aktuelle Seite. |
Antwort
Mögliche Antworten sind:
200 OK
: Die Kontakte wurden erfolgreich abgerufen. Die Antwort enthält ein Array mit den Kontakten.401 Unauthorized
: Der API-Key ist ungültig.
Einzelnen Kontakt abrufen
Um einen Kontakt abzurufen, müssen Sie einen GET-Request in folgendem Format an den Endpunkt senden:
https://api.belegfuchs.de/v1/contacts/{contactId}
Die {contactId}
ist die id
des Kontakts, nicht die number
.
Antwort
Mögliche Antworten sind:
200 OK
: Der Kontakt wurde erfolgreich abgerufen. Die Antwort enthält die Daten des Kontakts.401 Unauthorized
: Der API-Key ist ungültig.
Einzelnen Kontakt mithilfe der customId abrufen
Um einen Kontakt mithilfe der customId
abzurufen, müssen Sie einen GET-Request in folgendem Format an den Endpunkt senden:
https://api.belegfuchs.de/v1/contacts/byCustomId/{customId}
Antwort
Mögliche Antworten sind:
200 OK
: Der Kontakt wurde erfolgreich abgerufen. Die Antwort enthält die Daten des Kontakts.401 Unauthorized
: Der API-Key ist ungültig.