Kapitel 6 – 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.  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.