Skip to main content

Kapitel 5 – Vertragsmanagement

Ziel dieses Kapitels

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

Der Gridware Contract beschreibt, welche Partei eine Leistung bereitstellt oder nutzt, unter welchen Bedingungen dies geschieht und wie die daraus entstehenden Geldflüsse verarbeitet werden. Er bildet das Verhältnis zwischen Kunden, Lieferanten und der für die Verrechnung verantwortlichen Organisation ab.

Während die Gridware Party eine Entität – also eine Person oder Organisation – repräsentiert, definiert der Gridware Contract, in welcher Rolle diese Entität innerhalb einer konkreten Geschäftsbeziehung auftritt.

Der Gridware Contract dient damit als Grundlage für:

    die Zuordnung von Kunden und Lieferanten,

    die Verarbeitung der zugehörigen Ladevorgänge,

    die Ermittlung der Abrechnungsbedingungen,

    die Kundenabrechnung,

    die Lieferantenabrechnung,

    sowie perspektivisch die Ablösung der bisherigen Subscription-basierten Vertragslogik.

    4.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,

      bereitstellt (Supplier/Contract Giver)

    • welche Partei die Leistung nutzt,

      nutzt (Customers)

    • in welchem Zeitraum der Vertrag gültig ist,

      ist (active_from, active_until)

    • welches Vertrags- und Abrechnungsmodell angewendet wird,

      wird (contract_type)

    • welche Partei die Zahlung leistet,

      leistet

    • welche Partei eine Vergütung erhält,

      erhält

    • und welche Partei die Rechnungsstellung beziehungsweise Verrechnung übernimmt.

      übernimmt (contractor_invoicing)

    Damit bildet der Gridware Contract sowohl den eingehenden Geldfluss als auch den ausgehenden Geldfluss ab. Er stellt die Verbindung zwischen Kunde, Lieferant und abrechnender Partei her und bildet die fachliche Grundlage für die spätere Kunden- und Lieferantenabrechnung.

    Während die Gridware Party eine einzelne Entität – also eine Person oder Organisation – repräsentiert, beschreibt der Gridware Contract die konkrete geschäftliche Beziehung zwischen diesen Entitäten. Erst durch den Vertrag wird festgelegt, welche Rolle eine Gridware Party innerhalb des jeweiligen Geschäftsprozesses übernimmt.

    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.

    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

    1. ID kopieren: image.png

    2. Fetch Contract by ID:ID:

      image.png

    3.  

      Link all Parties um alle ERP Next Parteien zuverlässig zu verbinden 
       Screenshot 2026-07-23 at 20.12.37.png 
    4. 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:

    1. Connections

    2. General Information

    3. Supplier Details

    4. Contract Customers

    5. Invoicing Section

    Screenshot 2026-07-23 at 21.15.11.png

    Screenshot 2026-07-23 at 21.14.42.png

    Screenshot 2026-07-23 at 21.14.54.png

    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

    5.9 Contract Types und deren Verarbeitung

    USAGE_POSTPAID

    AktuellVertragstyp: wurdenNachträgliche folgendeAbrechnung Vertragsartenvon genannt:Ladevorgängen

    • Ladevorgänge

      USAGE_POSTPAID

    Dienstwagen: USAGE_POSTPAID

    USAGE_HUBJECT_CPO_ROAMING

    USAGE_ADHOC

    EMP_USAGE_INTERNAL

    USAGE_POSTPAID

    Vertrag für die nachträgliche Abrechnung von Ladevorgängen.

    Diewerden während einer Billing Period entstandenenerfasst

    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 gesammeltnormal undaggregiert anschließendItem-Mapping: kunden-USAGE_POSTPAID sowie+ gegebenenfallsVAT lieferantenseitig→ abgerechnet.Item Code

      USAGE_HUBJECT_CPO_ROAMING

      Vertragsmodell fürVertragstyp: CPO-Roaming über Hubject.Hubject

      Aus

      denGridware Pullliefert Requests ist bekannt, dass für diesen Vertragsfall ein definierter Standardkunde verwendet werden kann, wenn Gridwaremöglicherweise keine regulären Kundendaten liefert.Verwendet einen definierten Standardkunden aus BeCharged Settings

      image.png

      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 die normale Customer-Usage-RechnungslogikLogik verarbeitet.abgerechnet

      Diefrappe.log_error( Implementierung verhindert daher die reguläre Rechnungserstellung aus Customertitle=f"Gridware Usage Data{usage.name} fürhas diesencontract_type Contract{contract_type}", Type.message="Skipping aggregation for USAGE_ADHOC" ) continue

      EMP_USAGE_INTERNAL

      Vertragstyp: Interne Dienstwagennutzung

      EMP_USAGE_INTERNAL

      Dieser Vertragstyp ist bestätigt, er wird behandelt

      Behandlung wie derUSAGE_POSTPAID UsageStandard-Verarbeitung Postpaid Type. 

      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

        Subject

        customer TypeLink Auto (Phase

        Subject1)

        IDVerknüpfung zu ERPNext

        SubjectCustomer

        Name assignment_periods_json JSON Gridware API Zuordnungsperioden

        Der Contract Customer ist der zahlende Kunde innerhalb der Vertragsbeziehung.

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

        Zusätzliche Zähler zeigen die Anzahl der zugeordneten:

          Personen,

          Organisationen.

          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:

          1. die Verträge synchronisiert wurden,

          2. die zugehörigen Gridware Parties angelegt wurden,

          3. 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.