Kapitel 5 – Vertragsmanagement

Ziel dieses Kapitels

Das Vertragsmanagement bildet die fachliche Grundlage für die spätere Verarbeitung und Abrechnung von Ladevorgängen.

5.1 Fachlicher Hintergrund und Zweck des Gridware Contracts

Der Gridware Contract beschreibt die geschäftliche Beziehung zwischen den beteiligten Parteien. Er legt fest, wer eine Leistung zur Verfügung stellt, wer diese Leistung nutzt und unter welchen vertraglichen sowie kaufmännischen Bedingungen die Leistung abgerechnet wird.

Der Vertrag regelt insbesondere:

welche Partei die Leistung bereitstellt (Supplier/Contract Giver)
welche Partei die Leistung nutzt (Customers)
in welchem Zeitraum der Vertrag gültig ist (active_from, active_until)
welches Vertrags- und Abrechnungsmodell angewendet wird (contract_type)
welche Partei die Zahlung leistet
welche Partei eine Vergütung erhält
welche Partei die Rechnungsstellung beziehungsweise Verrechnung übernimmt (contractor_invoicing)

Damit bildet der Gridware Contract sowohl den eingehenden Geldfluss als auch den ausgehenden Geldfluss ab.

Der Gridware Contract (Nummernkreis GWC- plus Ziffern) steuert, wie Sessions berechnet und gutgeschrieben werden. Ohne Vertrag keine saubere CUD/SUD.

Warum wurde der Gridware Contract als Custom DocType entwickelt?

Der Gridware Contract wurde als projektspezifischer DocType entwickelt, um die in Gridware vorhandenen Verträge vollständig innerhalb von ERPNext abzubilden und als Grundlage für die weitere kaufmännische Verarbeitung zu verwenden.

Der Standard-DocType Contract in ERPNext bildet die benötigte Gridware-Struktur nicht ausreichend ab. Insbesondere fehlen dort Funktionen und Datenstrukturen für:

mehrere beteiligte Parteien innerhalb eines Vertrags,
getrennte Kunden- und Lieferantenrollen,
Gridware-spezifische Identifikatoren,
Preis- und Steuerinformationen,
Informationen zur abrechnenden Partei,
Verknüpfungen zu den einzelnen Ladevorgängen,
sowie die Grundlage für die Aggregation und Abrechnung von Kunden- und Lieferantennutzungen.

Der Custom DocType dient daher nicht nur als Kopie eines Vertrags aus Gridware, sondern als zentrale kaufmännische Integrationsschicht innerhalb von ERPNext. Er verbindet die Vertragsdaten aus Gridware mit den Stammdaten, Nutzungsdaten und späteren Abrechnungsprozessen in ERPNext.

Langfristig soll der Gridware Contract außerdem Teile der Vertragslogik übernehmen, die derzeit noch über ERPNext Subscriptions abgebildet werden.

Datenhoheit und Anlage des Vertrags

Gridware ist das führende System für sämtliche Vertragsdaten.

Ein Vertrag wird grundsätzlich in Gridware angelegt:

durch becharged,
oder durch den jeweiligen Lieferanten beziehungsweise Betreiber.

Anschließend wird der Vertrag nach ERPNext synchronisiert und dort als Gridware Contract gespeichert. Der Datensatz in ERPNext stellt damit das kaufmännische Abbild des ursprünglichen Gridware-Vertrags dar.

Eine manuelle Neuanlage eines Gridware Contracts in ERPNext ist nicht Bestandteil des vorgesehenen Standardprozesses. Änderungen an Vertragsdaten sollen ebenfalls grundsätzlich im führenden System Gridware vorgenommen und anschließend nach ERPNext synchronisiert werden.

5.2 Der Synchronisationsprozess

Ein wesentliches Architekturprinzip der Integration ist, dass die Synchronisation immer mit dem Gridware Contract beginnt.

Über die Becharged Settings kann aktuell ein Vertrag per Gridware-ID gezogen werden; dann läuft der komplette Synchronisationsprozess automatisch ab.

Verträge abrufen lädt die gesamte Vertragsmenge und ist nicht leicht rückgängig

Der grundsätzliche Ablauf ist:

Gridware Contract
        ↓
Synchronisation des Vertrags nach ERPNext
        ↓
Ermittlung aller beteiligten Personen und Organisationen
        ↓
Anlage oder Aktualisierung der Gridware Parties
        ↓
Anlage beziehungsweise Verknüpfung von Customer und Supplier
        ↓
Synchronisation der zum Vertrag gehörenden Gridware Usages
        ↓
Aggregation zu Customer Usage Data und Supplier Usage Data
        ↓
Kunden- und Lieferantenabrechnung

┌─────────────────────────────────────────────────────────────────┐
│                    SYNCHRONISATIONSABLAUF                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  PHASE 1: API AUTHENTIFIZIERUNG                                │
│  ├─ GridwareClient() wird initialisiert                        │
│  ├─ JWT-Token wird abgerufen (2FA falls nötig)                │
│  └─ Gridware Sync Log: Status = "Authenticated"               │
│                                                                 │
│  PHASE 2: CONTRACT ABFRAGE                                    │
│  ├─ GET /services/contracts?limit=100&offset=0               │
│  ├─ Alle Verträge werden gepagiert abgerufen                 │
│  └─ Gridware Sync Log: HTTP 200 OK, Response Time            │
│                                                                 │
│  PHASE 3: FÜR JEDEN CONTRACT                                  │
│  ├─ GET /services/contracts/{contract_id}                    │
│  │  └─ Contract Details (allgemeine Infos, Supplier, VAT)    │
│  │                                                            │
│  ├─ GET /services/contracts/{contract_id}/customer           │
│  │  └─ Liste aller Customers (möglicherweise gepagiert)      │
│  │                                                            │
│  └─ GET /services/transactions/allTransactionSummaries       │
│     └─ Alle Usages (Transaktionen) für Contract              │
│                                                                 │
│  PHASE 4: PARTEIEN-SYNCHRONISATION (Background Job)          │
│  ├─ find_or_create_party() für Contract Giver                │
│  ├─ find_or_create_party() für jeden Customer                │
│  ├─ Erstelle Gridware Parties falls nicht vorhanden          │
│  └─ Verknüpfe zu Customer/Supplier                           │
│                                                                 │
│  PHASE 5: USAGES SYNCHRONISATION (Background Job)            │
│  ├─ Für jede Transaction: fetch_single_usage()              │
│  ├─ GET /backoffice/usages/{usage_id}                       │
│  └─ Erstelle Gridware Usage (Status: Complete)              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Der Vertrag ist damit der Ausgangspunkt für die gesamte nachgelagerte Datenverarbeitung.

Über die becharged Settings kann aktuell ein Vertrag per Gridware ID gezogen werden, dann läuft der komplette Synchronisationsprozess wie oben dargestellt automatisch ab.

Schritt für Schritt

~~ID kopieren:~~
~~Fetch Contract by ID~~:

~~Link all Parties um alle ERP Next Parteien zuverlässig zu verbinden~~
~~Danach werden automatisch: Gridware Parties mit Customer & Supplier & Contact & Adress, sowie die Usage erstellt.~~

5.6 Aufbau des Gridware Contract Doctypes

Der Doctype gliedert sich fachlich in folgende Bereiche:

Connections
General Information
Supplier Details
Contract Customers
Invoicing Section

5.7 Connections

Im oberen Bereich des Dokuments werden die mit dem Vertrag verbundenen Vorgänge dargestellt.

Aktuell bestehen Verknüpfungen zu:

Gridware Usage
Customer Usage Data
Supplier Usage Data

Diese Verknüpfungen ermöglichen es, von einem Vertrag direkt auf die zugehörigen Transaktionen und Abrechnungsbatches zuzugreifen.

5.8 General Information

Der Bereich General Information enthält die grundlegenden Vertragsinformationen aus Gridware.

Contract ID

Die numerische Gridware-ID des Vertrags.

Sie dient als externer Identifikator für die Synchronisation.

UUID

Die eindeutige technische UUID des Vertrags in Gridware.

Contract Number

Die fachliche Vertragsnummer.

Contract Type

Der Contract Type bestimmt das zugrunde liegende Geschäftsmodell und beeinflusst die spätere Verarbeitung der zugehörigen Usages.

Active From

Datum und Uhrzeit, ab denen der Vertrag gültig ist.

Internal Information

Interne Vertragsbezeichnung beziehungsweise Beschreibung.

Customer Information

Kundenbezogene Beschreibung des Vertrags.

Feld	Datentyp	Quelle	Beschreibung
`contract_id`	Text (unique)	Gridware API	Externe Identifikator (contractId)
`uuid`	Text	Gridware API	Eindeutige technische UUID
`contract_number`	Text	Gridware API	Fachliche Vertragsnummer
`contract_type`	Select	Gridware API	Vertragstyp (s. Kapitel 5.9)
`active_from`	Datetime	Gridware API	Gültigkeit Start
`active_until`	Datetime	Gridware API	Gültigkeit Ende
`internal_information`	Text Editor	Gridware API	Interne Notizen
`customer_information`	Text Editor	Gridware API	Kundenspezifische Infos

status Text Gridware API Active, Inactive, Closed, Expired

5.9 Contract Types und deren Verarbeitung

USAGE_POSTPAID

Vertragstyp: Nachträgliche Abrechnung von Ladevorgängen

Ladevorgänge werden während einer Billing Period erfasst
Am Ende der Periode werden Kunden- und Lieferantenrechnungen erstellt
Standard-Verarbeitung über Customer Usage Data / Supplier Usage Data

API Verarbeitung:

Alle Customers werden normal verarbeitet
Usages werden normal aggregiert
Item-Mapping: USAGE_POSTPAID + VAT → Item Code

USAGE_HUBJECT_CPO_ROAMING

Vertragstyp: CPO-Roaming über Hubject

Gridware liefert möglicherweise keine regulären Kundendaten
Verwendet einen definierten Standardkunden aus BeCharged Settings

USAGE_ADHOC

Vertragstyp: Ad-hoc-Ladevorgänge (nicht über normale Rechnungslogik)

Spezialbehandlung:

# customer_usage_data.py :: create_customer_usage_data()

if contract_type in ["USAGE_ADHOC"]:
    # Überspringe diese Usages - werden nicht über normale Logik abgerechnet
    frappe.log_error(
        title=f"Gridware Usage {usage.name} has contract_type {contract_type}",
        message="Skipping aggregation for USAGE_ADHOC"
    )
    continue

EMP_USAGE_INTERNAL

Vertragstyp: Interne Dienstwagennutzung

Behandlung wie USAGE_POSTPAID
Standard-Verarbeitung

5.10 Supplier Details

Jedem Gridware Contract kann genau ein Lieferant beziehungsweise Contract Giver zugeordnet sein.

Der Contract Giver ist in der Regel der CPO, der die Ladeinfrastruktur beziehungsweise die zugrunde liegende Leistung zur Verfügung stellt.

Im Bereich Supplier Details werden unter anderem folgende Informationen gespeichert:

Contract Giver ID

Gridware-interne ID des Contract Givers.

Contract Giver Identifier

Name beziehungsweise fachliche Bezeichnung des Contract Givers.

Contract Giver Contractor ID

Gridware-ID der zugehörigen Person oder Organisation.

Contract Giver Contractor Type

Kennzeichnet, ob der Contract Giver eine Person oder Organisation ist.

Gridware Supplier Party

Verknüpfung zur zugehörigen Gridware Party.

Supplier

Verknüpfung zum ERPNext Supplier.

Feld	Datentyp	Quelle	Beschreibung
`supplier_name`	Text	Gridware API (`supplierFirst.identifier`)	Name des Lieferanten/CPO
`api_supplier_reference`	Text	Gridware API (`supplierFirst.id`)	Eindeutige Referenz
`contractor_id`	Text	Gridware API (`supplierFirst.contractorId`)	Subject ID des Contractors
`contractor_type`	Select	Gridware API	ORGANIZATION / PERSON
`gridware_supplier_party`	Link	Auto (Phase 1)	Verknüpfung zu Gridware Party
`supplier`	Link	Auto (Phase 1)	Verknüpfung zu ERPNext Supplier

5.11 Contract Customers

Einem Vertrag können mehrere Kunden zugeordnet sein.

Dabei kann es sich um:

mehrere Personen,
mehrere Organisationen,
oder eine Kombination aus Personen und Organisationen

handeln.

Jede Zeile der Child Table repräsentiert eine beteiligte Kundenentität und enthält unter anderem:

Feld	Datentyp	Quelle	Beschreibung
`customer_id`	Text	Gridware API	Eindeutige Customer ID
`customer_number`	Text	Gridware API	Kundennummer
`subject_id`	Text	Gridware API (`subjectId`)	Subject ID (Person/Org)
`subject_type`	Select	Gridware API	ORGANIZATION / PERSON
`subject_name`	Text	Gridware API	Name (Person/Org)
`subject_salutation`	Text	Gridware API	Anrede
`active`	Check	Gridware API	Ist Kunde aktiv
`gridware_party`	Link	Auto (Phase 1)	Verknüpfung zu Gridware Party
`customer`	Link	Auto (Phase 1)	Verknüpfung zu ERPNext Customer
`assignment_periods_json`	JSON	Gridware API	Zuordnungsperioden

Der Contract Customer ist der zahlende Kunde innerhalb der Vertragsbeziehung.

Die Zuordnung von Kunden zu einem Vertrag ist erforderlich, weil ein Vertrag beispielsweise mehreren Nutzern, Mitarbeitern oder Organisationen die Nutzung derselben bereitgestellten Leistung ermöglichen kann.

5.12 Invoicing Party

Neben Contract Giver und Contract Customer existiert die Invoicing Party, im Doctype als Contractor Invoicing abgebildet. Diese Partei ist für die Verrechnung verantwortlich.

Es handelt sich hierbei in der Regel um:

becharged,
oder Grid & Co.

5.13 Invoicing Section

Der Bereich Invoicing Section speichert die aus Gridware übernommenen Abrechnungsinformationen.

Contractor Invoicing ID

Gridware-ID der abrechnenden Partei.

Contractor Invoicing Identifier

Name der abrechnenden Partei.

Contractor Invoicing Supplier Number

Lieferantennummer der abrechnenden Partei innerhalb der Gridware-Logik.

Billing Period

Definiert den vorgesehenen Abrechnungszeitraum beziehungsweise das Abrechnungsintervall.

Price Rule

Die Price Rule wird aus Gridware übernommen. Sie wird derzeit zunächst als Information gespeichert und noch nicht vollständig als Berechnungsregel innerhalb ERPNext ausgeführt.

VAT

Der übermittelte Umsatzsteuersatz wird derzeit zu Dokumentationszwecken im Vertrag gespeichert.

Price Type

Der Price Type beschreibt, ob eine Preisangabe beispielsweise als Netto- oder Bruttopreis interpretiert wird. Dieses Feld soll insbesondere für die spätere Dienstwagenverrechnung relevant werden.

Payment Method

Die Payment Method soll zukünftig steuern, wie die Abrechnung beziehungsweise Zahlungsabwicklung erfolgt. Die genaue produktive Auswirkung wird im Zuge der weiteren Umsetzung ergänzt.

Feld	Datentyp	Quelle	Beschreibung
`contractor_invoicing_id`	Text	Gridware API	ID der abrechnenden Party
`contractor_invoicing_identifier`	Text	Gridware API	Name (z.B. "becharged GmbH")
`contractor_invoicing_supplier_number`	Text	Gridware API	Lieferantennummer
`billing_period`	Select	Gridware API	Abrechnungszeitraum
`price_rule`	Text	Gridware API	Preisregel
`vat`	Percent	Gridware API (×100)	MwSt-Satz (0.19 → 19%)
`price_type`	Select	Gridware API	NET / GROSS
`payment_method`	Select	Gridware API	SEPA / CARD / etc.

5.14 Button „Fetch Customers & Supplier“

Der Button Fetch Customers & Supplier dient aktuell als manueller Zwischenschritt innerhalb des Synchronisationsprozesses.

Er wird verwendet, nachdem:

die Verträge synchronisiert wurden,
die zugehörigen Gridware Parties angelegt wurden,
die entsprechenden Customer- und Supplier-Stammdaten erzeugt wurden.

Anschließend stellt der Button die Verknüpfungen zwischen:

Gridware Contract,
Gridware Parties,
ERPNext Customers,
ERPNext Supplier

her.

Der Button soll zukünftig durch einen vollständig automatisierten Prozess ersetzt werden.

Zusätzlich wurde eine Funktion zur übergreifenden Verknüpfung aller Contract Parties eingeführt, damit fehlende Kunden- und Lieferantenbeziehungen gesammelt ergänzt werden können.

5.15 Aktualisierung bestehender Verträge

Bestehende Gridware Contracts werden bei einer erneuten Synchronisation nicht grundsätzlich überschrieben.

Die Implementierung prüft, ob sich Vertragsfelder oder die zugehörigen Kundenbeziehungen geändert haben. Nur tatsächliche Änderungen werden übernommen.

Zusätzlich wurde die Änderungsverfolgung für den Doctype aktiviert, damit Änderungen am Vertragsabbild nachvollziehbar bleiben.