Data Mapping Gridware to ERP Next

Perfekt — dann hier eine konkrete ERPNext-Zielarchitektur für deinen Fall, mit finalen Doctypes, Beziehungen und klarer Prozesslogik.

Ich mache das bewusst so, dass es für dich als Umsetzungsgrundlage für ERPNext + Gridware API taugt.

Zielbild

Architekturfluss

Master Party
→ Customer / Supplier
→ Contract
→ Single Session
→ Billing Run
→ Sales Invoice / Purchase Invoice / SEPA XML / Payment Entry

Das ist aus meiner Sicht die sauberste Struktur, weil du damit trennst zwischen:

Stammdaten
Vertragslogik
Transaktionsdaten
Abrechnung
Zahlung

1. Zielstruktur der Doctypes

Ich würde das in 3 Ebenen teilen:

A. Stammdaten

Master Party
Customer
Supplier
Contact
Address
Bank Account
SEPA Mandate
End User

B. Vertrags- und Nutzungsdaten

Contract
Charging Point / EVSE Mapping
Single Session

C. Abrechnung und Zahlung

Billing Run
Billing Run Item
Sales Invoice
Purchase Invoice / Credit Settlement
Payment Entry
SEPA Export Batch

2. Die Doctypes im Detail

2.1 Master Party

Zentrale reale Entität. Eine Person oder Organisation soll nur einmal existieren.

Zweck

Abbildung einer realen Partei unabhängig von ihrer Rolle.

Typ

Custom Doctype

Wichtige Felder

party_type → Person / Organization
party_name
display_name
external_source → Gridware / Manual / Other
gridware_person_id
gridware_organization_id
gridware_customer_number
gridware_supplier_number
tax_id
vat_id
is_customer
is_supplier
is_end_user
is_contract_giver
status
raw_payload

Beziehungen

1 Master Party kann haben:
- 0..1 Customer
- 0..1 Supplier
- 0..n Contacts
- 0..n Addresses
- 0..n Bank Accounts
- 0..n SEPA Mandates
- 0..n Contracts
- 0..n End Users

Warum wichtig

Damit dieselbe reale Entität nicht doppelt als Customer und Supplier angelegt wird.

2.2 Customer

ERPNext Standard-Doctype, erweitert.

Zweck

Abrechnungsrelevanter Debitor.

Zusätzliche Felder

master_party → Link Master Party
gridware_customer_id
gridware_customer_number
default_contract_role
customer_classification
use_case_classification

Nutzung

Für Sales Invoice
Für Debitorenlogik
Für Vertragszuordnung

2.3 Supplier

ERPNext Standard-Doctype, erweitert.

Zweck

Abrechnungsrelevanter Kreditor / Gutschriftempfänger.

Zusätzliche Felder

master_party → Link Master Party
gridware_supplier_id
gridware_supplier_number
supplier_classification
contract_giver_flag

Nutzung

Für Purchase Invoice / Gutschriften / Auszahlungen

2.4 Contact

ERPNext Standard.

Zusätzliche Felder

master_party
gridware_contact_reference
is_billing_contact
is_operational_contact

2.5 Address

ERPNext Standard.

Zusätzliche Felder

master_party
gridware_address_reference
address_role → Billing / Installation / Legal / Other

2.6 Bank Account

Kann ERPNext Standard oder eigener Doctype sein, je nach Bedarf.

Zusätzliche Felder

master_party
customer
supplier
iban
bic
account_holder
is_default_incoming
is_default_outgoing

2.7 SEPA Mandate

Eigener oder bestehender Doctype.

Felder

master_party
customer
iban
bic
mandate_reference
mandate_granted_at
status
is_active
creditor_scheme_id
bank_account

Nutzung

Direct Debit XML
Zahlungsabwicklung

2.8 End User

Würde ich als eigenen Custom Doctype anlegen.

Zweck

Nutzende Person, die laden darf oder lädt, ohne zwingend Rechnungsempfänger oder Lieferant zu sein.

Wichtige Felder

end_user_name
master_party optional
customer
contract
gridware_user_id
recipient_name
recipient_number
rfid_token
app_user_reference
vehicle_reference
employee_reference
status

Warum wichtig

Damit „Mitarbeiter“, „Dienstwagenfahrer“, „Nutzer“, „Empfänger in Sessiondaten“ nicht im Customer/Contact verschwimmen.

3. Vertrags- und Nutzungsdaten

3.1 Contract

Zentraler Kern-Doctype.

Zweck

Technische und fachliche Abbildung eines Gridware Contracts in ERPNext.

Pflichtfelder

contract_id / gridware_contract_id
contract_number
master_party
customer
supplier
end_user optional
contract_type
classification
payment_method
price_rule
billing_period
active_from
active_until
status

Zusätzliche Fachfelder

usage_classification
billing_case
credit_case
invoice_case
settlement_logic
payment_execution_type

Externe Referenzen

gridware_customer_id
gridware_supplier_id
gridware_creditor_reference
gridware_debtor_reference
raw_payload

Beispielwerte für Klassifikationen

usage_classification

COMPANY_CAR_HOME_CHARGING
EMPLOYEE_CHARGING
PUBLIC_ADHOC
PUBLIC_POSTPAID
TENANT_CHARGING

billing_case

EMPLOYER_INVOICED
END_USER_INVOICED
DIRECT_PAY_NO_INVOICE
NO_INVOICE

credit_case

CONTRACT_GIVER_CREDIT
SUPPLIER_CREDIT
NO_CREDIT

invoice_case

MONTHLY_CONSOLIDATED
CONSUMPTION_ONLY
STATIC_PLUS_CONSUMPTION
ATTACHMENT_PER_END_USER

Warum Contract so wichtig ist

Der Contract ist dein Default-Entscheider für:

Wer zahlt
Wer Gutschrift bekommt
Wie gruppiert wird
Wie fakturiert wird
Welche Sessions dazugehören

3.2 Charging Point / EVSE Mapping

Optional, aber sehr sinnvoll.

Zweck

Zuordnung technischer Ladepunkte zu Verträgen / Orten / Parteien.

Felder

evse_id
charging_point_name
contract
customer
supplier
location
gridware_reference
status

Nutzung

Session-Zuordnung
Plausibilitätsprüfungen
Reporting

3.3 Single Session

Eigener Doctype. Ganz wichtig.

Zweck

Jeder einzelne Ladevorgang aus Gridware.

Pflichtfelder

session_id / external_session_id
document_number
contract
customer
supplier
end_user
evse_id
charging_point
start_datetime
end_datetime
consumption_kwh

Kosten- und Tarifdaten

payment_amount_net
payment_amount_vat
payment_amount_gross
energy_net
parking_net
service_fee_net
currency

Technische Daten

usage_medium
authorization_type
billing_period
import_run
source_system
raw_payload

Abgeleitete Felder

derived_usage_classification
derived_billing_case
derived_credit_case
derived_invoice_case
classification_status
classification_note
included_in_billing_run
billing_run
is_billable
is_credited

Warum wichtig

Das ist die belastbare Basis für:

Anhänge
Rechnungen
Gutschriften
Rekonstruktion
Korrekturen
Reporting

4. Abrechnungsebene

4.1 Billing Run

Eigener Doctype. Würde ich auf jeden Fall ergänzen.

Zweck

Abrechnungscontainer für einen Zeitraum und eine bestimmte fachliche Kombination.

Felder

billing_run_name
period_from
period_to
customer
supplier
contract
billing_case
credit_case
invoice_case
currency
status → Draft / Ready / Invoiced / Settled / Error
session_count
total_consumption_kwh
total_amount_net
total_amount_vat
total_amount_gross

Verlinkungen

sales_invoice
purchase_invoice
payment_entry
sepa_export_batch

Zweck in der Praxis

Der Billing Run ist die Ebene, auf der du sagst:

Für Kunde X, Vertrag Y, Zeitraum März 2026, invoice_case MONTHLY_CONSOLIDATED, credit_case CONTRACT_GIVER_CREDIT — diese 173 Sessions gehören zusammen.

Ohne diesen Zwischenschritt wird es später chaotisch.

4.2 Billing Run Item

Kind-Table oder eigener Child-Doctype.

Zweck

Zuordnung der Sessions zum Billing Run.

Felder

single_session
customer
supplier
contract
end_user
amount_net
amount_vat
amount_gross
consumption_kwh
invoice_relevant
credit_relevant

Vorteil

Dann kannst du später Billing Runs einfrieren und nachvollziehen, was genau enthalten war.

5. ERPNext Output-Dokumente

5.1 Sales Invoice

ERPNext Standard.

Erzeugt aus

Billing Run, wenn billing_case eine Kundenrechnung verlangt.

Typische Fälle

Arbeitgeber wird belastet
End User wird belastet
monatliche Sammelrechnung
statisch + Verbrauch
Verbrauch only

Empfehlung

Die Invoice sollte nicht direkt aus Single Sessions gebaut werden, sondern aus Billing Run.

5.2 Purchase Invoice oder Supplier Credit Settlement

Für Gutschriften / Auszahlungen an Contract Giver / Supplier.

Je nach ERPNext-Setup:

Purchase Invoice mit neg./positiver Logik
oder eigener Auszahlungs-Doctype mit späterem Payment Entry
oder Gutschriftenprozess

Erzeugt aus

Billing Run, wenn credit_case != NO_CREDIT

5.3 SEPA Export Batch

Eigener Doctype.

Zweck

Gruppierung von Direct-Debit-Zahlungen für XML-Erzeugung.

Felder

batch_id
company
creditor_scheme_id
collection_date
payment_type
message_id
payment_info_id
control_sum
number_of_transactions
status
xml_file
sales_invoices

Nutzung

pain.008 XML
Nachverfolgung
Bankexport

5.4 Payment Entry

ERPNext Standard.

Nutzung

Eingang von Customer-Zahlungen
Auszahlung an Supplier
Verrechnung mit Invoices

6. Beziehungen als Zielmodell

So würde ich die Beziehungen definieren:

Stammdaten

Master Party 1 → 0..1 Customer
Master Party 1 → 0..1 Supplier
Master Party 1 → n Contact
Master Party 1 → n Address
Master Party 1 → n Bank Account
Master Party 1 → n SEPA Mandate
Master Party 1 → n End User

Verträge

Contract n → 1 Customer
Contract n → 1 Supplier
Contract n → 0..1 End User
Contract n → 1 Master Party optional als Ursprungsentität

Sessions

Single Session n → 1 Contract
Single Session n → 1 Customer
Single Session n → 1 Supplier
Single Session n → 0..1 End User
Single Session n → 0..1 Charging Point / EVSE

Abrechnung

Billing Run n → 1 Contract
Billing Run n → 1 Customer
Billing Run n → 0..1 Supplier
Billing Run 1 → n Billing Run Item
Billing Run Item n → 1 Single Session

Output

Billing Run 1 → 0..1 Sales Invoice
Billing Run 1 → 0..1 Purchase Invoice
Billing Run 1 → 0..1 SEPA Export Batch
Sales Invoice 1 → 0..1 Payment Entry
Purchase Invoice 1 → 0..1 Payment Entry

7. Prozessfluss

Schritt 1: Stammdatenimport

Aus Gridware:

Person / Organization
Customer-Daten
Supplier-Daten
Contract-Daten

In ERPNext:

Master Party erstellen/finden
daraus Customer und/oder Supplier erzeugen
Contact / Address / SEPA / Bank anlegen
externe IDs speichern

Schritt 2: Contract Import

Contract aus Gridware anlegen/aktualisieren
Customer/Supplier verlinken
Klassifikationsfelder ableiten:
- usage_classification
- billing_case
- credit_case
- invoice_case

Schritt 3: Session Import

Single Sessions importieren
Contract zuordnen
Customer/Supplier/End User ableiten
Session-Klassifikation ableiten
Billing Period setzen

Schritt 4: Billing Run erzeugen

Gruppierung z. B. nach:

period
customer
supplier
contract
billing_case
credit_case
invoice_case

Dann:

passende Sessions sammeln
Summen bilden
Billing Run erstellen
Billing Run Items schreiben

Schritt 5: Fakturierung / Gutschrift

Je nach Klassifikation:

Sales Invoice erzeugen
Purchase Invoice / Credit erzeugen
Anhänge auf Basis Sessions generieren

Schritt 6: Zahlung

Je nach Zahlungsweg:

Rechnung offen lassen
SEPA XML erzeugen
Payment Entry buchen
Supplier-Auszahlung buchen

8. Minimalversion für den Start

Falls ihr nicht alles sofort bauen wollt, würde ich mit dieser Minimalversion starten:

Phase 1

Customer erweitern
Supplier erweitern
Contract
Single Session
Billing Run
SEPA Mandate
optionale Master Party light

Phase 2

End User
Charging Point Mapping
Billing Run Item
SEPA Export Batch
Party Master vollständig

Phase 3

Automatische Klassifikationsengine
automatische Gutschriftenlogik
Fehler-/Review-Queue
Rebuild von Billing Runs

9. Meine konkrete Empfehlung für euch

Wenn du mich fragst, wie ich es wirklich implementieren würde, dann so:

Unbedingt custom bauen

Master Party
Contract
End User
Single Session
Billing Run
Billing Run Item
SEPA Export Batch
EVSE Mapping

ERPNext Standard verwenden

Customer
Supplier
Contact
Address
Sales Invoice
Purchase Invoice
Payment Entry

ERPNext Standard erweitern

Customer
Supplier
Contact
Address
ggf. Bank / SEPA

10. Einfache visuelle Zielkette

So soll es am Ende logisch aussehen:

Gridware API
→ importiert Party / Contract / Session
→ ERPNext normalisiert zu Customer / Supplier / End User / Contract / Single Session
→ Sessions werden pro Zeitraum in Billing Runs gruppiert
→ Billing Runs erzeugen Sales Invoice / Supplier Credit / SEPA XML / Payment Entry

11. Mein Fazit

Ja — so sollte es aussehen, wenn du eine robuste, ausbaufähige Architektur für becharged bauen willst.

Der wichtigste Unterschied zu einem reinen ER-Modell ist:

nicht nur Tabellen definieren,
sondern klare Prozessanker einbauen:
- Contract für Default-Logik
- Single Session für Nachvollziehbarkeit
- Billing Run für Abrechnungskontrolle
- Master Party für Dublettenfreiheit
- End User für fachliche Sauberkeit

Als nächsten Schritt kann ich dir das jetzt in einer von zwei Formen aufbereiten:

Variante A: als saubere Tabelle pro Doctype mit Feldname, Feldtyp, Pflicht/optional, Beschreibung
oder
Variante B: als Mermaid ER-Diagramm / Architekturdiagramm zum direkten Kopieren in Doku oder Ticket.