Data Mapping Gridware to ERP Next

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.