Geschäftspartner per KI-Agent anlegen und pflegen

Die Werkzeuge für Stammdaten

Partner anlegen: Felder und Prüfungen

partner_kind ist customer (Kunde, Debitor), supplier (Lieferant, Kreditor) oder both. Dazu kommen optional Firmierung, USt-IdNr., Steuernummer, Ansprechpartner, Telefon, Anschrift, Land, Personenkonto, Standardkontierung, Zahlungsziel und Skonto.

• Vor dem Anlegen soll der Agent laut Werkzeug mit list_business_partners prüfen, ob es den Partner schon gibt. Eine Wiederholung mit derselben UUID legt keinen zweiten an.
• Personenkonten folgen festen Nummernkreisen: Debitoren 10000 bis 69999, nur bei customer oder both; Kreditoren 70000 bis 99999, nur bei supplier oder both.
• Ein Standard-Gegenkonto (default_account) für Buchungsvorschläge gibt es nicht bei both; einen Standard-Steuerschlüssel nicht bei Kleinunternehmern.
• Skontofrist nur zusammen mit Skontosatz und Zahlungsziel; der Skontosatz hat höchstens zwei Nachkommastellen.
• Die fachlichen Prüfungen laufen wie im Partnerformular der App, einschließlich bereits vergebener Personenkonten.

Warum IBAN und E-Mail besonders geschützt sind

Ein Agent liest fremde Texte: Belege, E-Mails, Verwendungszwecke. Stünde darin „Unsere Bankverbindung hat sich geändert“, könnte ein Agent ohne Schranke die IBAN eines Lieferanten umstellen — und der nächste Zahllauf ginge an den Betrüger. Deshalb sind IBAN und BIC über die Schnittstelle nicht änderbar. Der Agent kann sie lesen; ändern können Sie sie nur in der App. Eine dort geänderte IBAN löst vor dem nächsten Zahllauf einen Hinweis aus.

E-Mail-Adressen (email, einvoice_email) sind die einzigen Ziele, an die der Agent Rechnungen versenden darf. Sie anzulegen oder zu ändern verlangt deshalb zusätzlich das Recht send; ohne es antwortet der Server mit send_scope_required. Der Agent legt den Partner dann ohne Adresse an, und Sie tragen sie in der App nach.

Auch mit send gilt: E-Mail-Adressen setzt der Agent nur, wenn Sie den Wert ausdrücklich genannt oder bestätigt haben — nie aus einem Beleg, einer E-Mail, einem Verwendungszweck oder einem anderen fremden Text.

Ändern mit Historie

update_business_partner ändert nur die Felder, die der Agent mitsendet. Jede Änderung steht in der Stammdaten-Historie, die get_business_partner zeigt. Ein Personenkonto, auf das schon gebucht wurde, bleibt fest — so passen Journal und offene Posten weiter zusammen.

Partner deaktivieren oder zusammenführen bietet die Schnittstelle nicht; das erledigen Sie in der App. list_business_partners mit include_inactive zeigt dem Agenten auch inaktive und zusammengeführte Partner.

Konten und Einstellungen

upsert_account verlangt account_number. Für ein Katalogkonto setzt der Agent eine eigene Bezeichnung (account_name), einen anderen Posten in Bilanz oder GuV (hgb_key wie in list_accounts) oder blendet es mit is_active false aus. Ein eigenes Sachkonto legt er mit is_custom true an: vier- oder sechs- bis achtstellig, mit Bezeichnung, Posten und Normalseite (is_debit_normal). Fünfstellige Personenkonten entstehen mit dem Geschäftspartner. Nicht genannte Felder bleiben unverändert, die Änderung steht in der Stammdaten-Historie.

get_entity_settings liest Kontenrahmen, wirksame Gewinnermittlung (Bilanz oder EÜR), Kleinunternehmer-Status, Soll- oder Ist-Versteuerung, Voranmeldungszeitraum, Dauerfristverlängerung, Bilanzstichtag und ob Steuernummer, USt-Steuernummer und USt-IdNr. hinterlegt sind. Diese Angaben braucht der Agent, um richtig zu buchen — ändern können Sie sie nur in der App.

Beispiel: neuen Kunden anlegen

Ein Auftrag, bevor die erste Rechnung an einen neuen Kunden geht:

Neuen Kunden anlegen: Lindenhof Catering GmbH,
Hauptstraße 12, 10115 Berlin, USt-IdNr. DE123456789,
Zahlungsziel 14 Tage, 2 % Skonto bei Zahlung in 7 Tagen.
Rechnungen gehen an rechnung@lindenhof-catering.example.

Schritt 1: list_business_partners mit q „Lindenhof“ — der Agent prüft, ob es den Kunden schon gibt.

Schritt 2: create_business_partner mit neuer UUID, partner_kind customer, name, street, postal_code, city, vat_id, payment_terms_days 14, skonto_percent 2, skonto_days 7 und email. Die Adresse haben Sie im Auftrag selbst genannt; das ist die Voraussetzung, dass der Agent sie setzt.

Schritt 3: Fehlt dem Schlüssel das Recht send, lehnt der Server mit send_scope_required ab. Der Agent sendet die übrigen Stammdaten ohne email und bittet Sie, die Adresse in der App einzutragen.

Schritt 4: Die Antwort enthält den angelegten Partner. Mit get_business_partner kann der Agent ihn samt Historie zeigen, bevor die erste Rechnung entsteht.

Häufige Fragen

Kann der Agent die IBAN eines Lieferanten ändern?

Nein. IBAN und BIC von Geschäftspartnern sind über die Schnittstelle nicht änderbar, nur lesbar. So kann kein Text in einem Beleg oder einer E-Mail den Agenten dazu bringen, Zahlungen umzuleiten. Bankverbindungen pflegen Sie in der App.

Warum braucht eine E-Mail-Adresse das Recht send?

Weil der Agent Rechnungen nur an die beim Partner hinterlegten Adressen versenden darf. Wer eine Adresse setzt, bestimmt also das Versandziel. Deshalb verlangt das Anlegen oder Ändern von email und einvoice_email zusätzlich das Recht send.

Legt der Agent Partner doppelt an?

Das Werkzeug weist ihn an, vorher mit list_business_partners zu suchen. Eine Wiederholung nach einem Abbruch mit derselben UUID legt keinen zweiten Partner an. Ein bereits vergebenes Personenkonto lehnt der Server ab.

Kann der Agent Partner löschen oder deaktivieren?

Nein, das bietet die Schnittstelle nicht. Deaktivieren und Zusammenführen erledigen Sie in der App. Der Agent kann inaktive und zusammengeführte Partner mit include_inactive aber lesen.

Kann der Agent den Kontenrahmen oder die Versteuerungsart umstellen?

Nein. get_entity_settings liest die Einstellungen der Gesellschaft nur. Kontenrahmen, Gewinnermittlung, Versteuerungsart und Voranmeldungszeitraum ändern Sie in der App.

Kann der Agent ein Personenkonto umnummerieren?

Solange noch nicht darauf gebucht wurde, ja — im passenden Nummernkreis. Ein bebuchtes Personenkonto bleibt fest, damit Journal und offene Posten zusammenpassen.