Lima

Was ist die Lima-Integration?

Lima ist das Abrechnungssystem (Customer Information System), das viele Stadtwerke und Energievertriebe für die Verwaltung ihrer Kunden, Verträge, Zähler und Rechnungen einsetzen. Damit epilot und Lima im Alltag wie ein einziges System wirken, sorgt die Lima-Integration für drei Aufgaben:

1. Neukundenakquise (NKZ) – ein in epilot abgeschlossener Auftrag wird in Lima als echter Kunde mit Vertrag angelegt.
2. Aus Lima übernehmen (Inbound) – Änderungen aus Lima fließen zurück nach epilot, damit Service-Mitarbeitende und Endkunden im Portal immer aktuelle Daten sehen.
3. An Lima senden (Outbound) – Änderungen, die der Kunde oder ein Agent in epilot vornimmt (z. B. Bankverbindung, Zählerstand, Abschlag), werden nach Lima geschrieben.

Dieser Artikel beschreibt, wie diese drei Aufgaben funktionieren – mit besonderem Fokus auf die Neukundenakquise, weil dort die meisten projektspezifischen Entscheidungen getroffen werden.

Das große Bild

Die Integration besteht nicht aus einer einzigen großen Schnittstelle, sondern aus mehreren kleinen, klar abgegrenzten Datenflüssen. Jeder Fluss hat einen eindeutigen Auslöser, eine zugeordnete Lima-Operation und ein klares Ergebnis – entweder in epilot oder in Lima.

Neukundenakquise (NKZ)

NKZ - die Schnittstelle in Lima, über die ein neuer Kunde samt Vertrag angelegt wird. Sobald ein Tenant mit Lima verbunden ist und ein Auftrag in epilot unterschrieben wird, klopft die Integration genau hier an, um den Kunden im Abrechnungssystem zu registrieren.

Der Ablauf, Schritt für Schritt

1. Auftrag wird in epilot abgeschlossen. Entweder über eine Customer-Journey („Checkout & Unterschrift") oder manuell durch einen Mitarbeiter in epilot 360.
2. Webhook wird ausgelöst. Die Automatisierung in epilot schickt die Order-Entität an den NKZ-Endpunkt. Der Auslöser ist konfigurierbar - meistens „Auftrag erstellt", manchmal an einen bestimmten Workflow-Schritt, einen Button oder eine Statusänderung gebunden.
3. Payload wird gemappt. Ein JSONata-Ausdruck in der Webhook-Automatisierung transformiert die epilot Bestellung in die Form, die NKZ erwartet (siehe Mapping-Referenz weiter unten).
4. Straßensuche. NKZ ruft Limas Straßensuche mit der Lieferadresse auf. Das prüft, ob die Straße vom Versorger beliefert wird, und liefert die internen Felder BEZIRKNR und STRASSENNR zurück, die Lima benötigt, um den Vertrag dem richtigen Netzgebiet zuzuordnen.
5. SOAP-Aufruf writeneukunde. NKZ baut den SOAP-Umschlag (Kundenblock p3SATZ + Vertragsblock p4SATZ) und ruft Limas writeneukunde-Operation auf.
6. Kundennummer wird zurückgeschrieben. Bei Erfolg liefert Lima eine KUNDENNUMMER. NKZ schreibt diese als customer_number in den Rechnungskontakt in epilot zurück. Damit weiß jede nachgelagerte Synchronisation (Delta-Sync, Self-Service, CRM-Export), dass dieser Kontakt nun ein echter Lima-Kunde ist.

Schlägt ein Schritt fehl – Straße nicht beliefert, Validierungsfehler, Lima-Ablehnung - wird der Fehler an die Automatisierung zurückgemeldet, der Kontakt wird nicht mit einer Kundennummer markiert, und der Auftrag kann nach Korrektur erneut versendet werden.

Warum Webhook + JSONata?

NKZ ist ein einfacher HTTP-Endpunkt mit einer strikten, Werk-unabhängigen Eingabeform. Jedes Werk hat aber einen eigenen Produktkatalog, eigene Journey-Fragen und eigene Konventionen – ein universelles Mapping ist daher nicht möglich. Die Trennung zwischen Integration und JSONata-Mapping bedeutet:

• Werke können ihr eigenes Mapping ausliefern, ohne dass Integrationscode geändert wird.
• Neue Produktattribute, Bonusregeln oder Journey-Felder lassen sich in Minuten anbinden.
• Derselbe NKZ-Service unterstützt beliebig viele Werke mit völlig unterschiedlichen Eingangs-Strukturen.
• Werk-spezifische Eigenheiten (Bonuslogik, Abrechnungsgruppen, Energieart-Erkennung) bleiben außerhalb des Integrationscodes.

Die Integration übernimmt nur die generischen, Werk-übergreifenden Transformationen (Straße/Telefon/Datum validieren, Straßensuche, SOAP-Umschlag). Alles Werk-spezifische ist Daten, kein Code.

Mapping-Referenz: Welches epilot-Feld geht wohin in Lima?

So liest sich diese Referenz: Für jedes Feld im NKZ-Request stehen Typ, ob es Pflicht ist, das Standard-Mapping aus der epilot-Order und eine Bemerkung dazu, was das Feld in Lima steuert. Wenn der eigene Produktkatalog andere Attributnamen verwendet, zeigt der JSONata-Ausdruck einfach auf die richtigen Felder – die Integration prüft nur die Form des Ergebnisses.

Metadaten

Kunde (Lieferadresse + Person) – wird zu p3SATZ in Lima

Vertrag – wird zu p4SATZ in Lima

Produkt & Energie

Zähler & Verbrauch

Preis & Abrechnungsgruppe

Belieferung – steuert VERSORGUNGAB und ZUGANGSART

Diese Felder werden als Eingabe an die Integration übergeben; die finalen Lima-Felder berechnet der Server.

Zahlung

Abweichende Rechnungsadresse (nur wenn sie sich von der Lieferadresse unterscheidet)

Das Standard-Mapping fügt den Block contract.billing_address nur ein, wenn Straße, Hausnummer oder PLZ von der Lieferadresse abweichen. Inhalt: dieselben Felder wie bei der Lieferadresse plus Anrede und name1.

Bonus & Coupons (optional)

Die Bonusfelder kommen entweder aus dem Produkt (_product.bonusart, _product.bonusbetrag, _product.bonusname, _product.bonustext, _product.sofortbonus_betrag, _product.mindestlaufzeit_bonus) oder – wenn der Tenant epilot-Coupons nutzt – aus line_items[0]._coupons[0]. Wichtig: Wenn bonusart gesetzt ist, müssen auch bonusname und bonusbetrag vorhanden sein. Lima lehnt unvollständige Bonusblöcke ab.

Was die Integration zentral übernimmt (du musst nichts selbst rechnen)

Manche Transformationen sind entweder rein generisch oder erfordern einen Lima-Aufruf. Diese laufen serverseitig – jedes Werk bekommt sie automatisch:

Fehlerfälle – woran scheitert ein NKZ-Aufruf?

Da in jedem Fehlerfall die customer_number nicht auf dem Kontakt landet, kann der Webhook nach Korrektur einfach neu angestoßen werden, ohne Duplikate zu erzeugen.

Was nach erfolgreicher Anlage passiert

• Der nächste Nightly-Sync bzw. Delta-Sync verknüpft den neuen Lima-Vertrag zurück mit dem Kontakt.
• Self-Service-Funktionen (Zählerstand melden, Adresse ändern, Bankverbindung ändern, dynamische Tarifkurven) sind ab sofort nutzbar.
• Der Kontakt gilt nun als Bestandskunde. Künftige Aufträge derselben Person verwenden die vorhandene Kundennummer weiter, statt ein Duplikat anzulegen.

Mapping selbst erweitern – das Vorgehen

1. Den Wert in der Order finden. In epilot 360 lässt sich die eingehende Entität in der Webhook-Automatisierung inspizieren.
2. In JSONata referenzieren: $entity.dein_feld für Top-Level-Attribute, $entity.line_items[0]._product.dein_feld für Produktattribute, $contact.dein_feld für Rechnungskontakt-Attribute.
3. In der JSONata-Sandbox testen (epilot bietet eine direkt im Automation-Editor). Form der Ausgabe gegen die Tabellen oben prüfen.
4. Speichern und mit einer Test-Order über die Journey live durchspielen. Die Integrations-Logs zeigen den tatsächlichen NKZ-Request.

Wenn der angelegte Lima-Kunde ein falsches oder fehlendes Feld hat, ist die Lösung fast immer eine JSONata-Änderung – kein Deployment im Integrationscode.

Inbound-Synchronisation: Lima → epilot

Damit epilot ein vollständiges, aktuelles Bild des Kunden zeigt, gibt es drei eingehende Flüsse aus Lima. Sie überschneiden sich bewusst, weil jeder eine andere Lücke schließt.

Wie die Daten aus Lima auf die Felder in epilot übertragen werden, ist im Integration Hub definiert. Über ein Standard-Blueprint bekommt jeder Tenant ein vorkonfiguriertes Mapping, das die typischen Felder (Stammdaten, Vertrag, Zähler, Rechnungen, Dokumente) sofort abdeckt. Möchte ein Kunde einzelne Felder anders abbilden oder eigene Attribute hinzufügen, kann er das direkt im Integration Hub anpassen – ohne dass am Integrationscode etwas geändert werden muss.

On-Demand-Sync

Sobald ein Mitarbeiter in epilot 360 einen Kontakt öffnet oder ein Endkunde sich im Portal anmeldet, ruft epilot die Integration auf und holt synchron alles, was zum Kunden gehört: Stammdaten, Verträge mit Geräten, Abschlägen, Verlauf, Tarifen und VG50-Daten, dazu Zahlwege, Vermerke, Objekte, Rechnungen und Dokumente. Die wichtigsten Daten (Name, Adresse, Vertragsliste) erscheinen typischerweise nach einer Sekunde, Dokumente kommen in den folgenden Sekunden nach. So sehen Service-Mitarbeitende und Endkunden in epilot immer den aktuellen Stand aus Lima, ohne ihn aktiv anstoßen zu müssen.

 

Delta-Sync

Alle paar Minuten fragt ein Poller Limas Änderung ab (Kunden-, Vertrags-, Forderungs- und Debitorenfeed). Jede Änderung wird auf eine Kundennummer reduziert, dedupliziert und in eine Warteschlange pro Kunde gestellt. Ein Prozessor zieht jeden Eintrag heraus und holt die vollständigen Stammdaten nach. So fließen auch Änderungen, die niemand in epilot angeklickt hat (z. B. nachts erstellte Rechnungen oder Back-Office-Korrekturen) automatisch nach epilot. Wichtig zu wissen: Der Delta-Sync meldet nur, was sich geändert hat – er gleicht nicht den gesamten Datenbestand ab. Da Lima zudem nicht für alle Bereiche eine Änderungsmeldung anbietet, ergänzen die On-Demand-Übernahme (für die Sicht im Moment des Öffnens) und die nächtliche Vollübernahme (für lückenlosen Abgleich) das Bild.

 

Nightly-Sync (CRM-Export)

Einmal pro Nacht stellt Lima einen vollständigen CRM-Export bereit. epilot speichert diesen Export, vergleicht ihn mit dem Export des Vortags und schickt nur die tatsächlich geänderten Datensätze in epilot – die Briefhistorie ist dabei ausgenommen. So landen auch Massenänderungen, Korrekturen aus dem Back-Office und nachgereichte Zählerstände zuverlässig in epilot, selbst wenn an dem Tag keine Lima-Schnittstelle aufgerufen wurde. Die nächtliche Vollübernahme ist langsamer als die anderen Flüsse, aber dafür vollständig und unabhängig von der Tagesform der Lima-APIs.

Wie die drei zusammenspielen

An Lima senden (Outbound)

Aus epilot heraus können bestimmte Selbstbedienungs-Vorgänge direkt in Lima ausgeführt werden. Die unterstützten Anwendungsfälle sind:

• Zählerstand melden
• Rechnungsadresse ändern
• Kontaktdaten ändern
• Bankverbindung ändern
• Abschlag ändern
• Tarifwechsel anstoßen (in Erprobung)

Welche dieser Anwendungsfälle aktiv sind, hängt vom jeweiligen Tenant ab. Sie werden über ein Blueprint installiert – also als vorkonfiguriertes Paket aus Journey, Automatisierung und Mapping, das nur noch auf den Tenant ausgerollt wird.

TODO: Dieser Abschnitt braucht noch mehr Detail (z. B. genaue Eingangsereignisse, Voraussetzungen pro Use Case, Fehlerbilder). Bitte ergänzen.

Dynamische Tarife

Bei einem dynamischen Tarif ändert sich der Energiepreis stündlich nach dem EPEX-Markt. Damit Endkunden verstehen, was sie zahlen und sparen, zeigt das Portal drei Diagramme: Preisverlauf, Kostenverlauf (Preis × eigener Verbrauch) und Verbrauchsverlauf. Eine eigene, schreibgeschützte API der Integration liefert diese Zeitreihen live aus Lima – sie werden nicht zwischengespeichert. Voraussetzungen für die Anzeige im Portal: Die Lima-App muss für installiert sein, und der Zähler des Vertrags muss ein intelligentes Messsystem (iMS) sein. Konventionelle Zähler liefern nicht den nötigen 15-Minuten-Lastgang, und ohne die Lima-App fehlt das Widget im Portal.