Data Mapping Gridware to ERP Next

In Log the Raw Data is stored

Mapping to Party Master DocType for Master Data 

Organisation

Gridware field	API	Ziel-Doctype	Ziel-Feld in ERPNext	Bemerkung
id (Organization ID)	/services/organizations	Master Party	gridware_organization_id	Eindeutige Org-ID
id (Organization ID)	/services/organizations	Master Party	gridware_subject_id	Normalisierte Haupt-ID
“ORGANIZATION" set by API URL	/services/organizations	Master Party	gridware_subject_type	Für einheitliche Importlogik
name	/services/organizations	Master Party	organization_name	Official Name
name	/services/organizations	Master Party	display_name	Display Name
type	/services/organizations	Master Party	is_customer / is_supplier	CUSTOMER → is_customer = 1, is_supplier = 0 SUPPLIER → is_customer = 0, is_supplier = 1 BOTH → is_customer = 1, is_supplier = 1
customerNumber	/services/organizations	Master Party	gridware_customer_number	Falls vorhanden
supplierNumber	/services/organizations	Master Party	gridware_supplier_number	Falls vorhanden
API Payload	/services/organizations	Master Party	raw_payload	Für Debugging/Sync
Import Datetime	/services/organizations	Master Party	last_imported_at	Systemseitig setzen

Person:

Gridware Feld	API	Ziel-Doctype	Ziel-Feld in ERPNext	Bemerkung
ID (Person ID)	/services/persons/export	Master Party	gridware_person_id	Eindeutige Personen-ID
ID (Person ID)	/services/persons/export	Master Party	gridware_subject_id	Normalisierte Haupt-ID
"PERSON" set by API URL	/services/persons/export	Master Party	gridware_subject_type	Für einheitliche Importlogik
Firstname	/services/persons/export	Master Party	first_name	Vorname
Lastname	/services/persons/export	Master Party	last_name	Nachname
Firstname + Lastname	/services/persons/export	Master Party	display_name	Zusammengesetzter Anzeigename
Account.email	/services/persons/export	Master Party	email	Haupt-E-Mail
API Payload komplett	/services/persons/export	Master Party	raw_payload	Für Debugging/Sync
Import-Zeitpunkt	/services/persons/export	Master Party	last_imported_at	Systemseitig setzen

Adress for Organisation or Person

Gridware Feld	API	Ziel-Doctype	Ziel-Feld in ERPNext	Bemerkung
ID (Address)	/services/addresses/for-organization/{organizationId}/{addressType} OR /services/addresses/for-person/{personId}	Master Party Address	external_address_id	Externe Address-ID
Address Type	services/addresses/for-organization/{organizationId}/{addressType} OR /services/addresses/for-person/{personId}	Master Party Address	address_type	Postal / Billing / Invoice
Street	services/addresses/for-organization/{organizationId}/{addressType} OR /services/addresses/for-person/{personId}	Master Party Address	street	Straße
Streetno	services/addresses/for-organization/{organizationId}/{addressType} OR /services/addresses/for-person/{personId}	Master Party Address	street_no	Hausnummer
zipCode	services/addresses/for-organization/{organizationId}/{addressType} OR /services/addresses/for-person/{personId}	Master Party Address	zip_code	PLZ
City	/services/addresses/for-organization/{organizationId}/{services/addresses/for-organization/{organizationId}/{addressType} OR /services/addresses/for-person/{personId}}	Master Party Address	city	Ort
Country	services/addresses/for-organization/{organizationId}/{addressType} OR /services/addresses/for-person/{personId}	Master Party Address	country	Map on ERPNext Country
Telephone	services/addresses/for-organization/{organizationId}/{addressType} OR /services/addresses/for-person/{personId}	Master Party Address	telephone	Telefon
Email	services/addresses/for-organization/{organizationId}/{addressType} OR /services/addresses/for-person/{personId}	Master Party Address	email	Falls auf Address-Level vorhanden
Primary Flag	?	Master Party Address	is_primary	Falls Gridware so etwas liefert
erzeugter ERPNext Address Datensatz	Link	Master Party Address	erpnext_address	Optional nachgelagert

Payment Methode:

Gridware Feld	API adress	Ziel-Doctype	Ziel-Feld in ERPNext	Bemerkung
ID (Payment Method)	/services/payment-methods	Master Party Payment Method	external_payment_id	Haupt-ID
Type	/services/payment-methods	Master Party Payment Method	payment_type	z. B. SEPA / Direct Debit

Then: 

Gridware Feld	API adress	Ziel-Doctype	Ziel-Feld in ERPNext	Bemerkung
Iban	/services/payment-methods/ID	Master Party Payment Method	iban	Wichtig für Bankkonto
BankName	/services/payment-methods/ID	Master Party Payment Method	bank_name	Falls Detail-Endpoint das liefert
MandateID	/services/payment-methods/ID	Master Party Payment Method	mandate_id	Wichtig für SEPA Mandate
CreatedAt	/services/payment-methods/ID	Master Party Payment Method	created_at
erzeugtes ERPNext Bank Account	LINK	Master Party Payment Method	erpnext_bank_account	Optional nachgelagert
erzeugtes ERPNext SEPA Mandate	LINK	Master Party Payment Method	erpnext_sepa_mandate	Optional nachgelagert

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.