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.

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

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}

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.