Dokumentation Mareon-Webservices-Schnittstelle der Mareon Handwerkeranbindung für Webservice-Hersteller Version 2.4 Stand: Mai 2014
Die in diesen Unterlagen enthaltenen Angaben und Daten können ohne vorherige Ankündigung geändert werden. Jede Ähnlichkeit mit bestehenden Firmen, Organisationen, Produkten, Personen etc. ist rein zufällig. Ohne ausdrückliche schriftliche Erlaubnis der Aareon AG darf kein Teil dieser Unterlagen für irgendwelche Zwecke vervielfältigt, verarbeitet oder verbreitet werden, unabhängig davon, auf welche Art und Weise oder mit welchen Mitteln elektronisch, mechanisch, durch Fotokopieren, Aufzeichnen usw. dies geschieht. Die aufgeführten tatsächlichen Produktbezeichnungen, Firmennamen und Logos sind zugunsten der eweiligen Hersteller bzw. Firmen als Marken oder eingetragene Marken geschützt. 2014 Aareon. Alle Rechte vorbehalten. Seite 2 von 98
Inhaltsverzeichnis 1 Einführung... 6 1.1 Überblick über die Mareon-Schnittstelle... 7 1.1.1 Was ist die Mareon-Webservices-Schnittstelle und was kann diese?... 7 1.1.2 Wie läuft eine Zertifizierung ab?... 7 1.1.3 Was benötigt man für eine Zertifizierung?... 7 1.2 Glossar: Mareon-spezifische Fachbegriffe... 7 1.2.1 Auftrag... 7 1.2.2 Rechnung... 8 1.2.3 EPA... 8 1.2.4 FPA... 8 1.2.5 EPA-Auftrag... 8 1.2.6 UNR... 8 1.2.7 Sub-UNR... 8 1.2.8 PN... 8 1.2.9 SOAP... 8 1.2.10 Leistungsnachweis... 9 1.2.11 Qualifiziert digital signierte elektronische Rechnung... 9 1.3 Grundlagen der Mareon-Schnittstelle... 9 2 Aufträge... 10 2.1 Auftragserteilung: Wo kommen Mareon-Aufträge her?... 10 2.2 Auftragsarten... 10 2.3 Auftragsstatus... 11 2.4 Auftragsstatusablauf... 11 2.5 Auftragsdetails... 12 2.6 Unterscheidung Auftragspositionen/Leistungspositionen... 12 2.7 Einheitspreisabkommen... 12 2.7.1 Ziel eines Einheitspreisabkommens... 13 2.7.2 Stammdaten... 14 2.7.3 Freie Positionen... 14 2.7.4 Nicht-freie Positionen... 14 2.7.5 Gültigkeitszeitraum... 15 2.7.6 UNR- und Sub-UNR-bezogene EPAs... 15 2.8 Auftragsanhänge... 15 2.9 Fax-Barcode... 16 2.10 Aufträge löschen/archivieren... 16 3 Rechnungen und Leistungsnachweise... 17 3.1 Rechnungen... 17 Seite 3 von 98
3.1.1 Rechnungsstatus... 17 3.2 Rechnung/Leistungsnachweis erstellen... 18 3.2.1 Allgemeine Rechnungsdaten... 18 3.2.2 Rechnungspositionen erfassen... 19 3.3 Rechnungsanhänge erstellen... 19 3.4 Löschen von Rechnungsanhängen... 20 3.5 Erweiterte Bemerkungstexte... 20 3.6 Rechnungen und Rechnungspositionen löschen... 20 3.7 Rechnung weiterleiten... 21 3.8 Bestandsdatenmanagement... 21 3.9 Rechnungsübersichten... 21 3.9.1 Monatsabrechnung... 21 3.9.2 Sammelübersicht... 22 3.10 Besonderheiten... 22 3.10.1 Rabatte und Zuschläge... 22 3.10.2 Gutschriften... 22 3.10.3 Gewährleistungsaufträge... 22 3.10.4 Aufträge mit pauschalierter Leistung... 23 3.11 Erklärung: Was ist die Digitale Signatur?... 23 3.12 Digital signierte Rechnungen bei Mareon... 23 4 Webservices-Schnittstelle... 24 5 Beschreibung der verfügbaren Aktionen... 25 5.1 getcompanylist... 25 5.2 getorderlist... 30 5.3 getorder... 33 5.4 setorderstate... 42 5.5 putinvoice... 45 5.5.1 Rückgabeparameter putinvoice... 47 5.6 getinvoice... 50 5.6.1 Übergabeparameter getinvoice... 50 5.6.2 Rückgabeparameter getinvoice... 50 5.7 getinvoicelist... 56 5.8 forwardinvoice... 60 5.9 getrechnungstatushistorie... 62 5.10 deleteinvoice... 63 5.11 getfpanames... 65 5.12 getfpa... 68 5.13 getfpalastmodificationdate... 71 Seite 4 von 98
5.14 putattachment... 73 5.15 listattachments... 75 5.16 getattachment... 77 5.17 deleteattachment... 80 6 Beschreibung der verwendeten Datentypen... 82 6.1 articletype... 82 6.2 articletypetype... 83 6.3 attachmentinfotype... 83 6.4 contacttype... 84 6.5 invoicefreefpapositionrequesttype... 84 6.6 invoicenonfreefpapositionrequesttype... 85 6.7 invoicepositionrequesttype... 85 6.8 invoicepositiontype... 86 6.9 invoicestatetype... 87 6.10 invoicetypetype... 87 6.11 listofids... 88 6.12 kennzeichenliste... 88 6.13 order... 88 6.14 orderpositiontype... 89 6.15 orderstatetype... 90 6.16 orderperiod... 92 6.17 ordertype... 92 6.18 personrole... 92 6.19 persontype... 93 6.20 proecttype... 94 6.21 settingstype... 95 Seite 5 von 98
1 Einführung Herzlich willkommen bei Mareon! Wir freuen uns, dass Sie sich entschlossen haben, eine Schnittstelle zur Mareon Handwerkeranbindung für Ihre Software zu erstellen. Über die Handwerkeranbindung des Service-Portals Mareon werden Wohnungsunternehmen und angeschlossene Handwerksunternehmen miteinander vernetzt. In Zukunft werden Sie also Aufträge der Wohnungsunternehmen, die auch Mareon im Einsatz haben, nur noch über das Internet an den angeschlossenen Handwerksbetrieb übertragen. Im Gegenzug werden auch die Rechnungen auf Mareon erstellt und über das Internet an den Auftraggeber weitergeleitet. Mareon automatisiert also die Abwicklung von Aufträgen und Rechnungen, um diese erheblich zu beschleunigen. Lästiges Ausdrucken und Postwege entfallen. Diese Dokumentation beschreibt die Mareon-Webservices-Schnittstelle und soll Ihnen helfen, mögliche Fragen bei der Entwicklung der Schnittstelle bereits im Vorfeld zu beantworten. Da wir unser Produkt stets weiterentwickeln, können Sie die aktuellste Version der Dokumentation ederzeit in elektronischer Form auf unserer Homepage www.mareon.com einsehen, herunterladen oder ausdrucken. Die Dokumentation wird begleitend zur aktuellen Version des Produkts angepasst. Haben Sie Anregungen oder Wünsche zu unserem Produkt oder diesem Handbuch, dann senden Sie uns bitte eine E-Mail an mareon.webservices@aareon.com. Gerne beantwortet Ihnen unsere Kundenbetreuung auch Fragen unter der Telefonnummer: 01803-227366600. Wir wünschen Ihnen viel Spaß beim Arbeiten mit Mareon! Seite 6 von 98
1.1 Überblick über die Mareon-Schnittstelle 1.1.1 Was ist die Mareon-Webservices-Schnittstelle und was kann diese? Die Mareon Webservices bieten die Möglichkeit, die Funktionen der Mareon Handwerkeranbindung direkt von einem lokalen Handwerkerprogramm aus zu nutzen. So können Aufträge bearbeitet und Rechnungen geschrieben und an Mareon übermittelt werden. Es gibt keine unnötige Doppelerfassung von Daten und Handwerker können in Ihrem vertrauten Programm weiterarbeiten wie bisher. Die Anbindung an Mareon erfolgt mittels eines Webservice, der den Datenaustausch inklusive ggf. vorhandener Anhänge ermöglicht. 1.1.2 Wie läuft eine Zertifizierung ab? Wenn Sie der Meinung sind, dass Ihre Entwicklungsleistung zur Anbindung an Mareon so weit vollendet ist, dass diese von Mareon-Mitarbeitern geprüft werden kann, dann wenden Sie sich bitte an unser Mareon-Webservice-Team und vereinbaren Sie einen Zertifizierungstermin (mailto:mareon.webservices@aareon.com). Bitte beachten Sie, dass Sie evtl. eine gewisse Vorlaufzeit für den Termin einplanen müssen und nutzen Sie den Zertifizierungskalender auf der Homepage, der Ihnen die freien verfügbaren Termine langfristig anzeigt. Im Vorfeld wird es eine Vorab-Abnahme der Entwicklungsleistung per Telefonkonferenz geben (in der Regel eine Woche vor dem Zertifizierungstermin), um zu prüfen, ob alle wesentlichen Bestandteile des Funktionskatalogs abgearbeitet worden sind und funktionieren. Anschließend erfolgt die persönliche Abnahme. Für den gesamten Zertifizierungsaufwand fallen einmalig 500,- - an. Die Nutzung der Schnittstelle selbst ist kostenfrei. Die Zertifizierung erfolgt in der Regel per Fernwartungssoftware, eine Anreise zu unserem Dienstgebäude nach Mainz ist i.d.r. nicht notwendig. 1.1.3 Was benötigt man für eine Zertifizierung? Sie benötigen mindestens einen vom Mareon-Webservice-Team erstellten Testbenutzer. Diesen können Sie kostenfrei bei uns anfordern. Der Benutzername, das Passwort und das herstellerspezifische Zertifikat müssen bei allen Aktionen, die an den SOAP-Server übermittelt werden, angegeben werden. 1.2 Glossar: Mareon-spezifische Fachbegriffe 1.2.1 Auftrag Durch den Auftrag verpflichtet sich der Beauftragte, die ihm übertragenen Geschäfte (rechtlicher oder tatsächlicher Art) oder Dienste vertragsgemäß zu besorgen. Auftraggeber sind in der Regel Wohnungsunternehmen, die aus Ihrem ERP-System über Mareon Aufträge an die Auftragnehmer (i.d.r. Handwerksunternehmen) vergeben. Aufträge können über Mareon pauschal (Auftragstyp H) oder per EPA (Auftragstyp HE) erteilt werden. Seite 7 von 98
1.2.2 Rechnung Eine Rechnung oder auch Faktura ist ein Dokument, das eine detaillierte Aufstellung über eine Geldforderung für eine Warenlieferung oder eine sonstige Leistung enthält. Diese enthält Angaben über die Leistung, die Zahlung und den Aussteller. Die elektronischen Rechnungen von Mareon werden mit einer qualifizierten digitalen Signatur versehen. 1.2.3 EPA Ein Einheitspreisabkommen (kurz EPA) ist ein Vertrag zwischen einem Auftraggeber und einem Auftragnehmer über pauschalisierte Kosten bei der Erbringung von Dienstleistungen. In der Regel werden EPA in der Immobilienwirtschaft zwischen großen Wohnungsunternehmen als Auftraggeber und Handwerkern als Auftragnehmer abgeschlossen und bestehen für einen fixen Zeitraum. Das EPA wird auch als Leistungspreisabkommen oder Festpreisvereinbarung bezeichnet. 1.2.4 FPA Fixed Price Agreement, identsich zu EPA, siehe EPA 1.2.5 EPA-Auftrag Bei einem EPA-Auftrag ist ein Einheitspreisabkommen zur späteren Rechnungsstellung fix hinterlegt. Diese Art des Auftrags ist durch den Typ HE gekennzeichnet. 1.2.6 UNR Dient zur eindeutigen Kennzeichnung eines Wohnungsunternehmens. UNR können zu Mandanten zusammengefasst werden, die dann auch als Mandanten-UNR bezeichnet werden. Zugeordnete UNR heißen Sub-UNR, siehe nächsten Abschnitt. 1.2.7 Sub-UNR Die Sub-UNR ist die tiefere Zuordnungsebene der UNR. Einer UNR können beliebig viele Sub-UNR zugeordnet sein. Die Mandaten-UNR ist gleichzeitig eine Sub-UNR. 1.2.8 PN Innerhalb eines Wohnungsunternehmens stellt die PN in Verbindung mit der UNR eine eindeutige Identifizierung eines Handwerkers dar. Ein Handwerker kann beliebig viele UNR-PN- Kombinationen haben! 1.2.9 SOAP SOAP (ursprünglich für Simple Obect Access Protocol) ist ein Netzwerkprotokoll, mit dessen Hilfe Daten zwischen Systemen ausgetauscht und Remote Procedure Calls durchgeführt werden können. SOAP stützt sich auf XML zur Repräsentation der Daten und dem HTTP-Protokoll zur Übertragung der Nachrichten. Seite 8 von 98
1.2.10 Leistungsnachweis Der Leistungsnachweis stellt in Kombination mit der Monatsabrechnung (händisch zu unterzeichnende Übersicht aller innerhalb eines Monats erstellten Leistungsnachweise an einen Auftraggeber) die steuerrechtliche Rechnung des Handwerkers gegenüber dem Wohnungsunternehmen dar, wenn dieses keine qualifizierte, digitale Signatur nutzt, um sich elektronische Rechnungen durch den Handwerker zusenden zu lassen. Vom inhaltlichen Aufbau her unterscheiden sich Leistungsnachweis und Rechnung nicht. Die Zahlung zu einem Leistungsnachweis erfolgt steuerrechtlich im Gutschriftenverfahren. 1.2.11 Qualifiziert digital signierte elektronische Rechnung Hierbei handelt es sich um Rechnungen, die mit einer qualifizierten digitalen Signatur durch Mareon versehen werden und somit einer Papierrechnung gleichgestellt sind. 1.3 Grundlagen der Mareon-Schnittstelle Die Mareon Webservices bieten die Möglichkeit, Funktionen der Mareon Handwerkeranbindung direkt von einem lokalen Programm aus zu nutzen, ohne ein Browserfenster zu öffnen. So können Aufträge geholt und akzeptiert oder abgelehnt werden und Rechnungen geschrieben und im Anschluss an Mareon übermittelt werden. Damit entfallen die Doppelerfassung von Rechnungen und der damit verbundene Mehraufwand bei der Nutzung der Mareon Handwerkeranbindung. Diese Dokumentation richtet sich an Softwareentwickler, die eine Anbindung an die Mareon HWA-Webservices implementieren möchten. Die Mareon HWA-Webservices sind durch ein WSDL-Dokument spezifiziert, das Sie auf der Mareon-Homepage herunterladen können. Die Datenübertragung muss SSL-verschlüsselt über die folgende URL erfolgen: https://soap.mareon.com/hwa24/soap Die im SOAP-Request übergebenen Daten müssen ISO-8859-15-codiert werden. Ebenso werden die Antworten ISO8859-15-codiert zurückgegeben. Grundsätzlich erhalten Sie zu edem Funktionsaufruf die im WSDL-Dokument angegebenen Rückgabewerte. Im Fehlerfall wird stattdessen ein SOAP-Fault ausgelöst, der einen Fehlercode und eine textuelle Beschreibung des Fehlers enthält. Der Einstieg in die Mareon-Schnittstelle bildet die Aktion <getcompanylist>. Diese können Sie direkt nach Erstellung eines Testusers mit Benutzernamen, Passwort, Ihre Softwareversion und Zertifikat aufrufen. Die Antwort auf diese Anfrage enthält alle grundlegenden Informationen über diesen Benutzer, dessen Auftraggeber (Wohnungsunternehmen) und bestimmte Einstellungen der Wohnungsunternehmen (UNR). Die Informationen, die Sie über <getcompanylist> erhalten, sind Grundlage aller anderen Aktionen, insbesondere UNR und PN, da diese Pflichtfelder bei allen anderen Aktionen sind. Detaillierte Informationen zu dieser Aktion finden Sie in Kapitel 5.1. Beispiel für einen einfachen Auftrags.- und Rechnungsablauf über die Schnittstelle getcompanylist getorderlist getorder setorderstate -- > putinvoice forwardinvoice Seite 9 von 98
2 Aufträge 2.1 Auftragserteilung: Wo kommen Mareon-Aufträge her? Aktion: getorderlist Die über Mareon vergebenen Aufträge werden durch den Auftraggeber in einem wohnungswirtschaftlichen ERP-System von Aareon erteilt. Diese ERP-Systeme sind an Mareon angebunden und ermöglichen somit die elektronische Vergabe von Aufträgen an Auftragnehmer. Hierbei handelt es sich immer um eine 1:1-Beziehung. Preisanfragen oder Preisangebote sind über dieses System nicht möglich. 2.2 Auftragsarten Über Mareon können verschiedene Arten von Aufträgen versendet werden, die ein unterschiedliches Verhalten bei der Auftrags- und/oder Rechnungsbearbeitung hervorrufen können. Standardaufträge Telefonisch erteilte Aufträge: Telefonisch erteilte Aufträge können e nach Auftraggeber bereits im Status bestätigt ankommen. Diese Aufträge sind dann nicht im Status erteilt. Aufträge mit EPA: Hier sind Ihre Möglichkeiten bei der Rechnungslegung begrenzt. Der Handwerker kann nur noch die Mengen der im EPA definierten Leistungspositionen angeben. Die mit dem Auftraggeber vereinbarten Einheitspreise können direkt mit dem Auftrag als Leistungspositionen vom Auftraggeber mitgeliefert werden. Das genaue Verhalten ist hier vom verwendeten ERP-System des Auftraggebers abhängig und davon, wie der Auftrag dort erteilt wird. Gewährleistungsaufträge: Hier ist die Möglichkeit, eine Rechnung zu dem Auftrag zu stellen, unterbunden. Der Auftrag ist mit der Meldung des Auftragsstatus Leistung erbracht erledigt. Proektaufträge: Meist handelt es sich hierbei um Aufträge mit einem größeren Auftragsvolumen. Daher ist es meist gewünscht, zu diesen Aufträgen mehrere Abschlags- und eine Schlussrechnung zu stellen. Der Auftrag enthält außerdem diverse Zusatzinformationen. Versicherungsaufträge: Der Handwerker erhält den Auftrag zwar von seinem Auftraggeber, doch können die Leistungen auch direkt von der Versicherung bezahlt werden. Standardaufträge mit pauschalierter Leistung: Aufträge mit Wert true beim Kennzeichen <flatrateorder>. Hier ist eine Rechnungsstellung nicht möglich. Wichtig hierbei ist zu beachten, dass bei allen Auftragsarten eine Erteilung mit oder ohne EPA möglich ist. Seite 10 von 98
2.3 Auftragsstatus Aufträge können folgende Status haben (Auszug): E: erteilt der Auftrag ist neu eingetroffen G: gesehen die Detailansicht des Auftrags wurde bereits aufgerufen F: bestätigt der Auftrag wurde angenommen N: Leistung erbracht die beauftragten Arbeiten wurden ausgeführt V: erledigt für diesen Auftrag wurde eine Rechnung/ein Leistungsnachweis erstellt oder der Gewährleistungsauftrag wurde durchgeführt C: abgelehnt der Auftrag wurde durch den Handwerker abgelehnt X: storniert der Auftrag wurde durch den Auftraggeber storniert PP: geparkt UV: unter Vorbehalt angenommen Neue Aufträge haben den Auftragsstatus erteilt. Sollte der Auftraggeber dem Handwerker einen Auftrag allerdings schon telefonisch erteilt haben, so erhält der Handwerker den neuen Auftrag bereits mit dem Status bestätigt. Änderungen des Auftragsstatus werden immer auch an den Auftraggeber weitergeleitet. 2.4 Auftragsstatusablauf Aktion: setorderstate Basis eines eden Auftrags ist der Status E. Wird dieser durch den Handwerker angesehen, wechselt der Status auf G. Bei der Annahme erfolgt dann der Übergang zum Status F. Nachdem die Leistung ausgeführt wurde und der Auftrag erledigt ist, wird mit Kennzeichnung des Auftrags als erledigt der Auftragsstatus N gesetzt. Mit Erstellung der Rechnung zum Auftrag wird der Rechungsstatus V gesetzt. Sollte es in Ihrer Software nicht die Möglichkeit geben, einen Auftrag als erledigt zu kennzeichnen, wird automatisch mit der Rechnungsstellung der Status V gesetzt. Sollte ein Auftrag durch den Auftragnehmer abgelehnt werden dies ist nur bei erteilten oder bereits gesehenen Aufträgen möglich, wird der Auftragsstatus auf C gesetzt. Im Falle des Auftragsstornos durch das Wohnungsunternehmen handelt es sich um den Auftragsstatus X. Eine Auftragsstornierung ist nur bis zum Status Auftrag angenommen möglich. Zusätzlich existieren Statusübergänge zum Parken und Annehmen unter Vorbehalt. Diese Statusübergänge sind allerdings nur erlaubt, wenn die entsprechenden Kennzeichen <enableparkingorder> bzw. <enableconditionalacceptancefororder> in <getcompanylistresponse> den Wert true enthalten. Ein Auftrag kann unter Vorbehalt angenommen werden, wenn er im Status erteilt ist. Von diesem Status aus sind Statusübergänge zu angenommen und abgelehnt möglich. Seite 11 von 98
Mit der Aktion <setorderstate> können Sie den Status eines Auftrags in der oben genannten Reihenfolge setzen. Eine Rücknahme eines Status in den vorherigen Zustand ist nur zum Status geparkt möglich. Beachten Sie, dass eine Rechnungsstellung erst ab dem Status bestätigt erfolgen kann und eine Auftragsablehnung nur erfolgen kann, wenn der Status erteilt oder gesehen ist. 2.5 Auftragsdetails Aktion: getorder Einige Auftragsdetails werden hier kurz erläutert: EP: Anhand des Kennzeichens <allfpa> in <getcompanylistresponse> ist es möglich zu entscheiden, welche Positionstypen eine Rechnung enthalten darf. Der Wert true bedeutet, dass für die Rechnungsstellung alle dem Handwerker zugeordneten EPA genutzt werden dürfen. Analog bedeutet false, dass bei der Rechnungsstellung nur Positionen des im Auftragskopf vorhandenen EPA zur Rechnungslegung genutzt werden dürfen. Auftraggeber: Die Autraggeberdaten sind aus der Struktur <subcompany> in der Antwort zu <getcompanylist> zu entnehmen. Eine Besonderheit stellt der Fall der Fremdverwaltung dar. In diesem Fall weichen die Angaben der Person mit Rolle OWNER von den Angaben in <getcompanylistresponse> ab. Dies muss per String-Vergleich untersucht werden. Im Falle von Fremdverwaltung vertritt der Auftraggeber den Eigentümer. Die Rechnung muss in der Druckfunktion ihrer Software einen abweichenden Eigentümer ausweisen. Auftragswert: Der Auftragswert kann die Summe aller Leistungspositionen oder die Schätzkosten des Auftragsgebers beinhalten. Unter Umständen hat der Auftraggeber eine Prüfmöglichkeit aktiviert, die verhindert, dass Rechnungen mit Rechnungssumme > Auftragswert gestellt werden dürfen. Weitere Erläuterungen zu den Auftragsdetails finden Sie in der Beschreibung der Schnittstelle am Ende dieses Dokuments. 2.6 Unterscheidung Auftragspositionen/Leistungspositionen Die Auftragsposition ist die im Auftrag mitgegebene Position, der in der Rechnung 1 bis n Leistungspositionen zugeordnet sein können, die wiederum die Verknüpfung zum EPA darstellen. Als Leistungspositionen werden ausschließlich EPA-Positionen in der Rechnung bezeichnet. 2.7 Einheitspreisabkommen Aktion: getfpanames (liefert die zugeordneten EPAs) Seite 12 von 98
Aktion: getfpa (liefert die Artikel und Konditionen) Aktion: getfpalastmodificationdate (liefert das letzte Änderungsdatum eines EPA) 2.7.1 Ziel eines Einheitspreisabkommens Einheitspreisabkommen dienen dazu, Leistungen und Preise von Instandhaltungsrechnungen zwischen Auftraggeber (Wohnungsunternehmen) und Auftragnehmer (Handwerker) für eine bestimmte Zeit festzulegen. Wenn der Handwerker dem Wohnungsunternehmen Rechnungen im Rahmen der laufenden Instandhaltung schickt, werden dann nicht mehr die tatsächlich angefallenen Preise abgerechnet, sondern die im EPA definierten Leistungen mit den vorher definierten Preisen. Die angegebenen Preise sind immer Nettopreise. Das Wohnungsunternehmen definiert diese EPAs in seinem eigenen ERP-System und schickt diese Daten an Mareon. Sie sollten dem Handwerker auch lokal die Möglichkeit geben, aus den ihm zur Verfügung stehenden EPA-Katalogen Artikel auszuwählen. Dabei sollten Sie beachten, dass sich Preise und Artikel auch in bestehenden EPAs ändern können. Es reicht dazu aus, eine manuelle Update- Möglichkeit durch den Handwerker vorzusehen. Ein regelmäßiges automatisches Update ist in der Regel nicht notwendig, kann aber mithilfe der Aktion <getfpalastmodificationdate> umgesetzt werden. Eine automatische Aktualisierung des referenzierten EPA beim Import der Daten aus <getorderresponse> ist nicht gewünscht, da die Datenmenge die Wartezeit für den Benutzer der Software unnötig erhöht und eine unnötige Systemlast auf unseren Systemen erzeugt. Manuelle Rabatte können auf Aufträge gewährt werden sofern die entsprechenden Unternehmenseinstellungen vorliegen Kennzeichen <disablediscount> in <getcompanylistresponse> = false und <usesfpawithdiscount> in <getcompanylistresponse> = true. Rabatte können ausschließlich auf Positionsebene vergeben werden. Manuell definierte Zuschläge können durch den Handwerker nicht angegeben werden. Allerdings können im Rahmen eines EPA sowohl Rabatte als auch Zuschläge definiert sein. Diese sind gestaffelt definiert. Abschläge werden prozentual ab einem bestimmten Nettorechnungswert definiert, Zuschläge als fester Geldbetrag bis zu einer bestimmten Nettorechnungssumme. Die Zuund Abschläge werden bei der Rechnungsübermittlung an das Mareon-Portal automatisch berücksichtigt. Die Daten werden in den Einheitspreiskatalogen nur zur Nachvollziehbarkeit/Information zur Verfügung gestellt. Als Antwort auf die Aktion <putinvoice> wird der von Mareon berechnete Rechnungsbetrag zur Verfügung gestellt. Ihre Software muss darauf vorbereitet sein, dass es zu Abweichungen zum von Ihnen übertragenen Rechnungsbetrag kommen kann. Zusätzlich zu diesen genannten Rabatten hat der Auftraggeber weitere Möglichkeiten der Rechnungskürzung. Nach Rechnungsübermittlung sollten Sie deshalb über die Aktion <getinvoice> die Rechnung von Mareon abrufen und die Rechnungssummen vergleichen. Dies muss nur erfolgen wenn das in Ihrer Software gespeicherte letzte Änderungsdatum von der entsprechenden Angabe in <getinvoicelistresponse > abweicht. Sollten sich Abweichungen ergeben, empfehlen wir Ihnen bei einer Anbindung an eine FiBu Korrekturbuchungen, damit die Rechnungssumme in der FiBu Seite 13 von 98
und auf Mareon übereinstimmen. Wenn Sie Fragen zu diesem Thema haben, wenden Sie sich bitte an Ihren Mareon-Ansprechpartner. 2.7.2 Stammdaten EPAs haben in Mareon einen bis zu 14-stelligen Schlüssel und bestehen aus Leistungspositionen deren Schlüssel.bis zu 18 Stellen lang sind und die den einzelnen EPAs zugeordnet sind. Eine LP hat folgende Eigenschaften: EPA-Schlüssel Kurztext Langtext Nettopreis Einheit Typ Material (M), Dienstleistung (D) oder Frei (F) Gültigkeitszeitraum (von) Gültigkeitszeitraum (bis) 2.7.3 Freie Positionen Freie Positionen dienen dazu, in einer EPA-Rechnung auch Leistungen abrechnen zu können, die nicht im EPA definiert sind. Dies widerspricht zwar der Idee eines EPA, feste Preise für Leistungen zu definieren, aber die meisten EPAs enthalten bei Weitem nicht alle Leistungen, die in der Praxis abgerechnet werden. Fast alle Kunden haben deshalb in ihren EPAs solche freien Positionen definiert. Wählt der Handwerker in einer Rechnung eine freie Position aus, kann er im Gegensatz zu nichtfreien Positionen den Positionstext und den Einzelpreis beliebig ändern. Freie Positionen werden in der Abfrage putinvoice in einem eigenem Element positionfree übertragen. Der Unterschied zur nicht freien Prosition ist das zusätzliche Pflichtfeld FPA, welches den EPA Schlüssel enthält und die Angabe des Preises. 2.7.4 Nicht-freie Positionen Nicht-freie Positionen sind Leistungspositionen, die als Typ Material (M) oder Dienstleistung (D) definiert sind, wobei diese beiden Typen auf Mareon ausschließlich als Information dienen und nicht weiter unterschieden werden. Seite 14 von 98
Bei der Verwendung von nicht-freien Positionen in einer Rechnung kann pro Position ausschließlich die Menge verändert oder übermittelt werden. Bezeichnung, Einheit und Preis werden automatisch ermittelt. Wenn das Wohnungsunternehmen den Elektronischen Aktenordner verwendet, steht zusätzlich das Feld PDF-Text zur Verfügung, das im PDF-Format mit abgebildet wird, edoch nicht mit ins ERP-System übermittelt wird. Hierüber lassen sich in diesem Fall längere Texte übergeben. Es ist edoch zu beachten, dass diese dann nur im elektronischen Rechnungsdokument und nicht im ERP-System des Auftraggebers erscheinen. 2.7.5 Gültigkeitszeitraum Bei EPA-Rechnungen ist das Erteilt-Datum des Auftrags ausschlaggebend für die Bereitstellung der LPs in der Rechnung. Bei sich überschneidenden Gültigkeitszeiträumen von Leistungspositionen mit demselben Schlüssel zieht immer das üngste Stichtagsdatum (=gültig ab), das vor dem Erteilt-Datum des Auftrags liegt. 2.7.6 UNR- und Sub-UNR-bezogene EPAs EPAs können auf Mareon UNR- oder Sub-UNR-orientiert hinterlegt werden, wobei das Speichern auf UNR-Ebene der Standardfall ist. Ist die Einstellung der EPAs auf Sub-UNR-Ebene gewählt, findet eine automatische Übertragung dieser statt, sodass diese zur Rechnungsschreibung zur Verfügung stehen. Welcher Modus für das eweilige Wohnungsunternehmen gilt, kann aus der Antwort auf die Aktion <getcompanylist> über den Wert des Elements <usessubunrconditions> ermittelt werden. Alle oben genannten Aktionen erwarten eine UNR als auch eine Sub-UNR als Parameter. Je nach Auftraggeber stehen die EPA-Daten ausschließlich über die UNR (Mandant) zur Verfügung oder es gibt auch zusätzlich abweichende Angaben über die Sub-UNR. Wenn die EPA-Daten ausschließlich auf der Mandanten-UNR-Ebene zur Verfügung stehen, gelten diese für alle existierenden Sub- UNR. Wenn EPA-Daten für Sub-UNR existieren, sind diese auch nur für genau diese Sub-UNR gültig. In der Regel werden ausschließlich EPA-Daten für die Mandanten-UNR zur Verfügung gestellt. Daten für die Sub-UNR sind die absolute Ausnahme. 2.8 Auftragsanhänge Aktion: getattachment (liefert einen Anhang) Aktion: listattachments (liefert eine Liste von Anhängen) Aktion: putattachment (ermöglicht das Hochladen eines Dokuments zu einer Rechnung) Aktion: deleteattachment (ermöglicht das Löschen / als nicht vorgangsrelevant markierten Anhangs) Der Auftraggeber kann bei Nutzung des Elektronischen Aktenordners an eden Auftrag beliebig viele Dokumente anhängen. Hierbei ist eine Dateigröße von bis zu 10 MB pro Datei zugelassen. Seite 15 von 98
Diese Anhänge können dem Handwerker mit Auftragsübermittlung zur Verfügung gestellt werden. Es ist zu beachten, dass auch nach Auftragserteilung noch Auftragsanhänge durch den Auftraggeber eingestellt werden können. Achtung: das nachträgliche Hochladen von Auftragsanhängen löst keine Aktualisierung des Datums LastModifiefDate aus. Die einzige Möglichkeit, neue Anhänge zu finden bleibt listattachments. Ebenfalls besteht die Möglichkeit, eingestellte Anhänge im Nachgang als nicht mehr vorgangsrelevant zu markieren. Diese Information muss ebenfalls an den Handwerker weitergeleitet werden, ohne dass es zur Löschung der Datei kommt, um die Historisierung zu gewährleisten. Für das Hochladen von Dokumenten gilt die gleiche Größenbeschränkung von 10 MB pro Dokument. 2.9 Fax-Barcode Handwerker haben die Möglichkeit, zu Ihrem Auftrag bzw. zur Rechnung einen Barcode (Strichcode) auszudrucken. Das ausgedruckte Dokument kann dann an die Fax-Nummer 01805-350036 gefaxt werden und wird dort automatisiert in der Rechnung als Rechnungsanhang zur Verfügung gestellt. Der Barcode benutzt dabei den Standard Code39 und wird in der Aktion <getorder> als Element <barcode> zur Verfügung gestellt. In Ihrer Software sollten Sie die Möglichkeit zum Ausdruck eines Faxdeckblatts vorsehen. 2.10 Aufträge löschen/archivieren Aufträge können nicht gelöscht werden. Die Möglichkeit einer Archivierung auf Mareon ist gegeben. Über die Schnittstelle ist keine Archivierung möglich, allerdings werden Aufträge spätestens 14 Tage nach Bezahlung der Schlussrechnung automatisch archiviert und stehen danach nicht mehr über die Schnittstelle zur Verfügung (Aktion <getorderlist> liefert diese Aufträge nicht mehr). Dies gilt auch für die zum Auftrag gestellten Rechnungen (Aktion <getinvoicelist>). Seite 16 von 98
3 Rechnungen und Leistungsnachweise Ist die Digitale Signatur im Einsatz, werden auf Mareon Rechnungen erstellt. Wird keine Digitale Signatur eingesetzt, so werden durch Mareon Leistungsnachweise erstellt. Beide Arten der Rechnungslegung werden an den Auftraggeber über Mareon weitergeleitet. Eventuell sollten Sie den Unterschied bei der Anbindung an Ihre FiBu beachten. Für ede Rechnung erstellt Mareon automatisch nach Weiterleitung eine Rechnungsdatei im PDF- Format, die danach von Mareon auch automatisch mit einer elektronischen Signatur versehen wird. Die Rechnungsdatei wird beim Finanzamt als Originalrechnung anerkannt. Werden über Mareon Leistungsnachweise erstellt, so muss zusätzlich zu den einzelnen Leistungsnachweisen, die über Mareon an den Auftraggeber weitergeleitet werden, eweils am Ende des Monats eine Monatsabrechnung erstellt, unterschrieben und auf dem Postwege dem Auftraggeber übersendet werden. Die Monatsabrechnung kann ausschließlich auf Mareon aufgerufen und gedruckt werden. 3.1 Rechnungen Aktion: getinvoice (liefert Details zu einer Rechnung) Aktion: getinvoicelist (liefert eine Liste der Rechnungen) 3.1.1 Rechnungsstatus Rechnungen können folgende Status haben: A: Erfasst: Die Rechnung wurde erstellt und gespeichert, edoch noch nicht an den Auftraggeber weitergeleitet. Die Rechnung ist nur für den Handwerker sichtbar und kann weiterhin beliebig geändert oder gar gelöscht werden (Überschreiben mit <putinvoice>, Löschen mit <deleteinvoice> eweils unter Angabe der mareonid des bestehenden Entwurfs). B: Weitergeleitet: Die Rechnung wurde an den Auftraggeber weitergeleitet. Dieser kann die Rechnung nun einsehen. Änderungen an der Rechnung von Auftragnehmerseite können nun nicht mehr durchgeführt werden. Beachten Sie bitte, dass die Rechnungsnummer des Auftraggebers e nach verwendetem ERP-System und Einstellung des Auftraggebers erst nach einigen Minuten zur Verfügung steht. In Einzelfällen kann dies auch noch länger dauern. Eine Rechnung gilt erst dann als erfolgreich übermittelt, wenn diese Rechnungsnummer in Mareon sichtbar ist. Über die Aktion <getinvoicelist> und die dort enthaltene Angabe <lastmodificationdate> kann erkannt werden, ob die Rechnung seit dem letzten Abruf der Detailinformationen geändert wurde (z. B. Rückmeldung der Rechnungsnummer durch das ERP-System), so das dann die Rechnungsnummer des ERP-Systems nachträglich in die Datenhaltung Ihrer Software eingespielt werden kann. H: Zur Prüfung vorgesehen: Der Auftraggeber prüft Ihre Rechnung. M: Geprüft: Die Prüfung der Rechnung ist abgeschlossen. U: Bezahlt: Die Zahlung der Rechnungen wurde durch den Auftraggeber angewiesen. Seite 17 von 98
Z: Storniert: Der Auftraggeber hat die Rechnung storniert. Es muss nun eine neue Rechnung erstellt werden können, um diese erneut an den Auftraggeber weiterzuleiten. W: Durch Versicherung bezahlt: Diese Rechnung wurde direkt durch den Versicherer des Auftraggebers bezahlt. Für einen Überblick über eine Rechnungsgeschichte können Sie die Aktion < getrechnungstatushistorie> nutzen. Diese gibt Ihnen den Lebenslauf einer Rechnung zurück. Es gibt noch eine Reihe weiterer Rechnungsstatus. Für eine vollständige Liste schauen Sie bitte in das entsprechende Kapitel zum Element <invoicestatetype> in der detaillierten Beschreibung aller WSDL-Elemente. 3.2 Rechnung/Leistungsnachweis erstellen Aktion: putinvoice (speichert eine neue Rechnung auf Mareon) 3.2.1 Allgemeine Rechnungsdaten Im Bereich allgemeine Rechnungsdaten können folgende Felder gefüllt werden. Bei Rechnungstyp besteht die Möglichkeit anzugeben, ob es sich bei der Rechnung um eine Abschlags- oder eine Schlussrechnung handelt. Abschlagsrechnungen sind dabei einzelne, unabhängige Rechnungen (Teilschlussrechnungen). Sie sind nicht(!) in der Schlussrechnung enthalten. Die Schlussrechnung enthält somit ausschließlich die offenen, noch nicht in Abschlagsrechnungen abgerechneten Leistungen. Das Feld interne Nummer für Handwerker ist über die Schnittstelle im Gegensatz zur Portallösung wo auch eine automatische Vergabe einer fortlaufenden Rechnungsnummer aktiviert werden kann zwingend erforderlich. Im Feld Bemerkung können zusätzliche Anmerkungen zur Rechnung getätigt werden. Je nach Einstellungen des Auftraggebers auf Mareon können erweiterte Bemerkungstexte zur Verfügung stehen. Des Weiteren sind folgende Informationen möglich: 13b UStG: Mit diesem Kennzeichen wird dem Auftraggeber mitgeteilt, dass diese Rechnung den Bedingungen des Umsatzsteuergesetzes 13b entspricht und die Rechnung als Nettorechnung verrechnet wird. In diesem Fall führt dann der Auftraggeber die Umsatzsteuer ab. Mieterverschulden: Sollte bei der Reparatur des Schadens festgestellt werden, dass der Schaden durch den Mieter verursacht wurde, kann dies durch das Setzen dieses Flags dem Auftraggeber mitgeteilt werden. Versicherungsfall: Sollte bei der Reparatur des Schadens feststellt werden, dass es sich bei dem Schaden um einen Versicherungsfall handelt, kann dies dem Auftraggeber durch dieses Kennzeichen mitgeteilt werden. Es darf nicht automatisch gesetzt werden, wenn der Auftrag ein Versicherungsauftrag ist, da es eine gesonderte Einstellung für Wohnungsunternehmen gibt, ob Rechnungen mit aktiviertem Versicherungsfall-Kennzeichen angenommen werden (siehe <disableinsuranceclaims> in <getcompanylistresponse>). Seite 18 von 98
3.2.2 Rechnungspositionen erfassen Gemäß des Leistungsumfangs der von Ihnen zur Verfügung gestellten Software haben Sie folgende Möglichkeiten. Mareon übernimmt an dieser Stelle lediglich die übermittelten Daten. Die einzelnen Rechnungspositionen können mittels drei verschiedener Elemente in der Aktion <putinvoice> übermittelt werden: position: kann ausschließlich in Nicht-EPA-Rechnungen verwendet werden. Preis und Text können beliebig übermittelt werden (Positionsrabatte sind möglich, wenn Kennzeichen <disablediscount> in <getcompanylistresponse> den Wert false hat). positionfpa: kann ausschließlich in EPA-Rechnungen verwenden werden. Preis und Text können nicht geändert werden (Positionsrabatte sind möglich, wenn Kennzeichen <usesfpawithdiscount> in <getcompanylistresponse> den Wert true hat). positionfree: kann ausschließlich in EPA-Rechnungen verwendet werden. Der Schlüssel der freien Position muss als <articlekey> mit übermittelt werden. Preis und Text können beliebig verändert werden (Positionsrabatte sind möglich, wenn Kennzeichen <usesfpawithdiscount> in <getcompanylistresponse> den Wert true hat). Wichtig: Zu eder Einheitspreisposition muss immer der Einheitspreisschlüssel (fpa name) mitgeliefert werden. Hinweis: Aus technischen Gründen kann eine Rechnung maximal 99 Positionen enthalten. Sollten mehr Positionen benötigt werden, muss mit Abschlags- und Schlussrechnung gearbeitet werden. Außerdem können insgesamt maximal 99 Rechnungen pro Auftrag erstellt werden. Die letzte muss eine Schlussrechnung sein. 3.3 Rechnungsanhänge erstellen Aktion: putattachment Wenn ein Auftraggeber mit elektronischen Rechnungen auf Mareon arbeitet, besteht die Möglichkeit, den Rechnungen und Aufträgen beliebige Anhänge beizufügen. So können zum Beispiel vom Mieter unterschriebene Stundenzettel oder sonstige rechnungsrelevante Unterlagen zur Verfügung gestellt werden. Anhänge zu einer Rechnung kann der Handwerker auf zwei Wegen erzeugen: 1. Per Faxübersendung: Hierbei ist, wie bereits oben erwähnt, ein Dokument mit Barcode als Deckblatt zur Rechnungsanlagenübermittlung zu generieren. Dieses Dokument sollte neben dem Barcode selbst möglichst noch Informationen zu Auftrag, Auftraggeber (UNR, Name) und Handwerker enthalten, da nicht alle Faxsendungen automatisch erkannt werden. Sie können sich am Faxdeckblatt, das auf dem Mareon-Portal zur Verfügung steht, orientieren. 2. Wenn rechnungsrelevante Informationen bereits in digitaler Form vorliegen, können diese auch direkt in Mareon hochgeladen werden. Rechnungs- und Auftragsanhänge können auch nach Weiterleitung einer Rechnung noch eingestellt werden. Seite 19 von 98
3.4 Löschen von Rechnungsanhängen Aktion: deleteattachment Wenn die Rechnung an den Auftraggeber weitergeleitet wurde, können aus Sicherheits- und Dokumentationszwecken die Anhänge nicht mehr dauerhaft gelöscht werden. Anhänge können nach Weiterleitung nur noch als nicht mehr vorgangsrelevant gekennzeichnet werden. Die Anhänge werden dann standardmäßig durchgestrichen angezeigt, bleiben aber weiterhin sowohl für Auftragnehmer als auch Auftraggeber zum Download verfügbar. Diese Unterscheidung trifft der Mareon-Server selbstständig, d. h. eine Unterscheidung in der <deleteattachment>-anfrage ist nicht notwendig. Die Rechnung im PDF-Format lässt sich grundsätzlich nicht löschen und auch nicht als nicht vorgangsrelevant markieren. 3.5 Erweiterte Bemerkungstexte Element: pdftext Zusätzlich zu Rechnungsanhängen, die als gesonderte Dokumente einer Rechnung anghängt sind, besteht bei elektronischen Rechnungen auch noch die Möglichkeit, erweiterte Bemerkungstexte für ede einzelne Position einzugeben. Voraussetzung ist, dass der Auftraggeber mit digitaler Signatur arbeitet, was ein Großteil der Wohnungsunternehmen tut (erkennbar an den Werten der Elemente <archive> und <signature> in <getcompanylistresponse>). Ist dies der Fall, darf der Rechnungstext maximal 10.240 Zeichen lang sein, wenn nicht nur 650 Zeichen. Es findet kein automatisches Abschneiden statt, sondern bei zu langem Text wird eine Fehlermeldung erzeugt. Die erweiterten Bemerkungstexte werden automatisch in das Rechnungs-PDF mit übernommen und stehen auf diesem Wege dem Auftraggeber zur Verfügung. Sie werden aber nicht in dessen ERP-System übertragen. Der Rechnungstext wird vollständig in das Rechnungs-PDF übernommen. Es werden aber nur maximal 650 Zeichen an der ERP-System des Wohnungsunternehmens übertragen. 3.6 Rechnungen und Rechnungspositionen löschen Aktion: deleteinvoice Grundsätzlich können Rechnungen und Rechnungspositionen nur so lange gelöscht werden, wie diese noch nicht an Ihren Auftraggeber weitergeleitet wurden. Sind die Daten einmal an Mareon übermittelt und an den Auftraggeber weitergeleitet, lässt Mareon kein Löschen mehr zu. Hinweis: Der Auftraggeber hat die Möglichkeit, die Rechnung auf Wunsch des Auftragnehmers zu stornieren. Dann kann die Rechnung erneut geschrieben werden. Aus Dokumentationszwecken wird die alte Rechnung allerdings weiterhin mit Status storniert auf Mareon sichtbar bleiben. Seite 20 von 98
3.7 Rechnung weiterleiten Aktion: forwardinvoice Ist eine Rechnung fertiggestellt, kann diese aus Ihrer Software über Mareon an den Auftraggeber vollautomatisch übermittelt werden. Ein Login auf Mareon ist nicht erforderlich, sofern der Auftraggeber nicht mit Bestandsdatenmanagement arbeitet. Der Einsatz von Bestandsdatenmanagement ist zurzeit der Ausnahmefall. In diesem Sonderfall wird die Schnittstelle eine entsprechende Fehlermeldung liefern und Ihr Kunde muss die Rechnung über das Mareon-Portal weiterleiten. Hierbei muss er zusätzliche Eingaben tätigen. Sobald die Rechnung beim Auftraggeber eingetroffen und erfolgreich in dessen ERP-System (= Auftrags- und Rechnungsbearbeitungssystem) importiert wurde, wird durch das ERP-System des Auftraggebers für die Rechnung eine zusätzliche Rechnungsnummer vergeben und an Mareon zurückgemeldet, die ERP Rechnungsnummer. Hinweis: Eine weitergeleitete Rechnung kann nicht mehr geändert werden. 3.8 Bestandsdatenmanagement Mareon Bestandsdatenmanagement (BDM) ist ein Modul, das die Mareon Handwerkeranbindung (HWA) ergänzt und dem Handwerker die Möglichkeit bietet, zu eingebauten Materialien in einer Wohnung bzw. in einem Obekt dem Auftraggeber Informationen mitzuteilen. Neben wichtigen Daten zu neu eingebauten Materialien und Informationen zu Reparaturen werden auch das Erneuerungsdatum und die damit verbundene Gewährleistung übermittelt. Das Bestandsdatenmanagement wird in der Handwerkeranbindung automatisch aufgerufen, wenn eine Rechnung weitergeleitet wird, die bestandsverändernd ist. Da Art und Umfang dieser Daten extrem umfangreich sind, stehen diese generell nicht über die Schnittstelle zur Verfügung. Der Handwerker muss diese stattdessen manuell beim Weiterleiten der Rechnung ergänzen. Die Aktion <forwardinvoice> liefert in diesem Fall einen entsprechenden Fehler. Eine Weiterleitung von Rechnungen über die Schnittstelle ist dann nicht möglich. 3.9 Rechnungsübersichten 3.9.1 Monatsabrechnung Hinweis: Nur für Leistungsnachweise! Die Monatsabrechnung wird benötigt, um die Umsatz- und Vorsteuer beim Finanzamt auszuweisen. Die Monatsabrechnung muss ausgedruckt und unterschrieben beim Wohnungsunternehmen eingereicht werden. Diese kann nur auf Mareon erstellt und gedruckt werden. Seite 21 von 98
3.9.2 Sammelübersicht Hinweis: Nur für Rechnungen! Analog der Monatsabrechnung, edoch ohne rechtliche Relevanz. Die Sammelübersicht dient der zusätzlichen Information für Auftragnehmer. 3.10 Besonderheiten 3.10.1 Rabatte und Zuschläge Rabatte können ausschließlich auf Positionsebene vergeben werden. Rabatte können auch auf EPA Aufträge gegeben werden. Dies funktioniert nur bei dem ERP Typ Wodis und dann auch nur wenn folgende Konfiguration der Unternehmensschalter vorliegt: DISABLE_DISCOUNT EPA_MIT_RABATT NO YES Bei der Aktion putinvoice bedeutet der Wert discount im Rechnungskopf Skonto, der Wert discount auf Rechungspositionsebene bedeutet Rabatt. Manuell definierte Zuschläge können durch den Handwerker nicht angegeben werden. Allerdings können im Rahmen eines EPA sowohl Abschläge als auch Zuschläge definiert sein. Diese sind gestaffelt definiert. Abschläge werden prozentual ab einem bestimmten Nettorechnungswert definiert und Zuschläge als fester Geldbetrag bis zu einer bestimmten Nettorechnungssumme. Zusätzlich zu diesen genannten Rabatten und Abschlägen hat der Auftraggeber weitere Möglichkeiten der Rechnungskürzung. Nach Rechnungsübermittlung sollten Sie deshalb über die Aktion <getinvoice> die Rechnung von Mareon abrufen und die Rechnungssummen vergleichen. Sollten sich Abweichungen ergeben, empfehlen wir Ihnen bei einer Anbindung an eine FiBu Korrekturbuchungen, damit die Rechnungssummen in der FiBu und auf Mareon übereinstimmen. Wenn Sie Fragen zu diesem Thema haben, wenden Sie sich bitte an Ihren Mareon- Ansprechpartner. 3.10.2 Gutschriften Über Mareon können leider keine Gutschriften übermittelt werden, da die ERP-Systeme der angeschlossenen Wohnungsunternehmen nicht dafür vorbereitet sind. Dies muss auf herkömmlichem Weg (außerhalb von Mareon) durchgeführt werden. 3.10.3 Gewährleistungsaufträge Zu Gewährleistungsaufträgen können keine Rechnungen erstellt werden. Ein Gewährleistungsauftrag wird mit der Rückmeldung Ausgeführt also der Mitteilung, dass die Leistung erbracht wurde abgeschlossen. Arbeitet der Auftraggeber mit Bestandsdatenmanagement (Sonderfall), kann dieser Statuswechsel nicht über ihre Software stattfinden. Dann erhält der Anwender eine Fehlermeldung und muss den Statuswechsel im Mareon-Portal durchführen. Seite 22 von 98
3.10.4 Aufträge mit pauschalierter Leistung In der Version 2.4 basic können keine Aufträge mit pauschalierter Leistung bearbeitet werden dies geht nur in der erweiterten Version 2.4 extended: Es können keine Rechnungen, aber unter Umständen Leistungserfassungsblätter erstellt werden. Diese Aufträge werden mit der Rückmeldung Ausgeführt also der Mitteilung, dass die Leistung erbracht wurde abgeschlossen. 3.11 Erklärung: Was ist die Digitale Signatur? Mareon bietet den Wohnungsunternehmen die Funktion einer digitalen Signatur (Unterschrift). Das heißt, dass alle Rechnungen, die über Mareon von Ihnen abgerechnet werden, mit einer qualifizierten elektronischen Signatur gemäß deutschem Signaturgesetz versehen werden. Eine qualifizierte elektronische Signatur kann laut Signaturgesetz von 2001 in Geschäftsprozessen die eigenhändige Unterschrift ersetzen, um geschäftliche Dokumente zu unterschreiben, ihnen Rechtskraft zu verleihen und nachzuweisen, dass nach Erstellung des Dokuments dieses nicht mehr verändert wurde. Eine eigenhändige Unterschrift ist dann nicht mehr notwendig. Dokumente, die mit einer digitalen Signatur versehen sind, werden als Originaldokumente (im Fall von Mareon: Originalrechnung) vom deutschen Finanzamt anerkannt. Mareon hat sich die Rechtsgültigkeit des elektronischen Prozesses der digitalen Signierung von Rechnungen im Juni 2006 von der Wirtschaftsprüfungsgesellschaft KPMG bestätigen lassen. Dieses Zertifikat der KPMG können Sie auf der Homepage von Mareon abrufen und einsehen. 3.12 Digital signierte Rechnungen bei Mareon Nachdem der Bundesrat das Steuervereinfachungsgesetz 2011 und somit auch eine Erleichterung bei den elektronischen Rechnungen beschlossen hat, ist im Gegensatz zu der bisherigen Regelung nicht länger eine qualifizierte digitale Signatur ver-pflichtend vorgeschrieben. Vielmehr legt gemäß dem neuen 14 Nr. 1 UStG nun eder Unternehmer fest, in welcher Weise die Echtheit der Herkunft, die Unversehrtheit und die Lesbarkeit der Rechnung gewähr-leistet werden. Dies kann durch egliche innerbetriebliche Kon-trollverfahren erreicht werden, die einen verlässlichen Prüfpfad zwischen Rechnung und Leistung schaffen können. Da derzeit noch relativ unklar ist, welche Anforderungen sich in der Praxis aus der neuen Formulierung konkret ergeben werden, bietet Mareon weiterhin nur die qualifizierte digitale Signatur von Rechnungen an. Mit elektronisch signierten Rechnungen sind Steller und Empfänger immer auf der sicheren Seite! Elektronisch übermittelte Rechnungen dürfen wie Papier-rechnungen nach Rechnungsstellung nicht mehr verändert werden. Genau dies leistet die Digitale Signatur von Mareon. Das bedeutet für Sie, dass die Rechnungen automatisch ohne weiteres Zutun Ihrerseits von der Aareon Deutschland GmbH in Ihrem Namen signiert werden. Seite 23 von 98
4 Webservices-Schnittstelle Über die Mareon-Webservices-Schnittstelle der Handwerkeranbindung können derzeit folgende Aktionen getätigt werden: getcompanylist getorderlist getorder setorderstate putinvoice getinvoice getinvoicelist forwardinvoice deleteinvoice getrechnungstatushistorie getfpanames getfpa getfpalastmodificationdate putattachment listattachments getattachment deleteattachment Seite 24 von 98
5 Beschreibung der verfügbaren Aktionen 5.1 getcompanylist Liefert eine Liste aller dem Handwerker zugeordneten Wohnungsunternehmen, inklusive der Einstellungen, Sub-Unternehmen und deren Einstellungen sowie der Personennummern (PN) des Benutzers. Die Kombination aus UNR und PN identifiziert einen Handwerker eindeutig. Ein Benutzer kann unter Umständen mehrere Personennummern haben (z. B. wenn er unterschiedliche Gewerke bedient). Die Aufträge und Rechnungen sind aber immer einer bestimmten PN zugeordnet. Deshalb müssen sowohl UNR als auch PN in allen Anfragen mit angegeben werden. Die Sub-UNR sind ausschlaggebend für die eindeutige Auswahl eines Auftrags oder einer Rechnung und können außerdem abweichende Rechnungsadressen definieren. Optional kann auch nach bestimmten UNR und Sub-UNR gefiltert werden. Zu beachten ist, dass die Haupt-UNR auch gleichzeitig eine Sub-UNR ist. Übergabeparameter getcompanylist Name Typ Pflichtfeld /n Beschreibung unr n Mareon Haupt-UNR: Sie referenziert den Mandanten eines Wohnungsunternehmens subunr n Mareon-Sub-UNR: Sie referenziert ein Unter- Wohnungsunternehmen. Rückgabeparameter getcompanylist Name Typ Häufigkeit Beschreibung company 0 - unbegrenz t Unternehmen unr 1 Mareon Haupt-UNR: Sie referenziert eden Mandanten eines Wohnungsunternehmens address persontype 1 Anschrift settings settingstype 1 Einstellungen Seite 25 von 98
subcompany 0 - unbegrenz t Subunternehmen subunr 1 Mareon-Sub-UNR: Sie referenziert ein Unter- Wohnungsunternehmen. address persontype 1 Anschrift settings settingstype 1 Einstellungen pn String Max. Länge 10 0 - unbegrenz t Mareon-Personennummer (wenn nicht angegeben, ist der Handwerker für dieses Unternehmen noch nicht freigeschaltet) Beispiel-Nachricht: Beispiel-Anfrage: <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://soap.mareon.com/hwa24/schema"> <soapenv:header> <sch:credentials> <!--You may enter the following 5 items in any order--> <sch:name>mareon Benutzer</sch:name> <sch:pass>passwort</sch:pass> <sch:cert>herstellerzertifikat</sch:cert> <sch:lang>de</sch:lang> <sch:clientversion>versionsnummer der Software</sch:clientVersion> </sch:credentials> </soapenv:header> <soapenv:body> <sch:getcompanylist> <!--Optional:--> <sch:unr>unr</sch:unr> Seite 26 von 98
<!--Optional:--> <sch:subunr>sub-unr</sch:subunr> </sch:getcompanylist> </soapenv:body> </soapenv:envelope> Beispiel-Antwort <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:header/> <soap:body> <getcompanylistresponse xmlns="http://soap.mareon.com/hwa24/schema"> <company> <unr>83600</unr> <address> <role>location</role> <name/> <firstname>wohnungsunternehmen Anderle</firstName> <street>isaac-fulda-allee 8</street> <zip>55124</zip> <city>mainz</city> </address> <settings> <signature>true</signature> <archive>true</archive> <forcerestricttoorderpositions>false</forcerestricttoorderpositions> <disable13b>true</disable13b> <disable35a>false</disable35a> <failinvoicesum>false</failinvoicesum> <disabletenantliable>false</disabletenantliable> <disablediscount>false</disablediscount> <disableinvoicetext>false</disableinvoicetext> Seite 27 von 98