Mareon-Webservices-Schnittstelle Änderungen der Schnittstelle in Version 2.3. bezogen auf die Version 2.2 (vor Mai 2012) Stand: Mai 2012

Transkript

1 Dokumentation Mareon-Webservices-Schnittstelle Änderungen der Schnittstelle in Version 2.3. bezogen auf die Version 2.2 (vor Mai 2012) Stand: Mai 2012

2 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 jeweiligen Hersteller bzw. Firmen als Marken oder eingetragene Marken geschützt Aareon. Alle Rechte vorbehalten. Seite 2 von 11

3 Inhaltsverzeichnis 1 Einleitung Beschreibung der Änderungen in der Webservice-Beschreibung (mareonhwa.wsdl)... 5 Seite 3 von 11

4 1 Einleitung Aufgrund von Erweiterungen des Service-Portals Mareon besteht die Notwendigkeit einer Schnittstellenerweiterung, um den neuen Funktionsumfang auch in der Handwerkersoftware zur Verfügung zu stellen. Durch Weiterentwicklung der bestehenden Aktionen konnte dieses Ziel erreicht werden. Zusätzlich wurden einige Korrekturen an den Schema-Definitionen vorgenommen. Seite 4 von 11

5 2 Beschreibung der Änderungen in der Webservice-Beschreibung (mareonhwa.wsdl) Aktion Änderung Erläuterung Alle alle mit Elementen vom Typ persontype alle mit Elementen vom Typ orderstatetype alle mit Elementen vom Typ attachmentinfotype alle mit Element quantity Einstiegs-URL auf " 23/soap" geändert. Namensraum wurde auf " schema" geändert. Die aktuelle WSDL kann ab mittels " /soap?wsdl" abgerufen werden. Element pn aus Struktur persontype entfernt Neue Status PP und UV in die Liste der möglichen Status aufgenommen Element currentversion steht optional zur Verfügung Element quantity überall als Dezimalzahl mit max. 3 Nachkommastellen definiert Element company in der Struktur Response kann 0 bis n mal vorkommen (bisher 1 bis n). Element pn in Struktur company kann 0 bis n mal vorkommen (bisher 1 bis n). Kommentare in Struktur settings- Type überarbeitet Die Versionierung der HWA-Schnittstelle Version 2.x wird nicht über ein Versionskennzeichen in der Nachricht, sondern über unterschiedliche Einstiegs-URLs und unterschiedliche Namensräume sichergestellt. Eine pn-angabe gibt es nicht für die durch eine solche Struktur in den Nachrichten übertragenen Personen. Kennzeichnung von geparkten Aufträgen (PP) und unter Vorbehalt angenommenen Aufträgen (UV) eingeführt. Eine Versionierung von Dateien wird zurzeit nicht unterstützt. Das Mareon-Portal unterstützt nur Mengen mit maximal 3 Nachkommastellen. Durch den bisherigen Typ double konnte es zu unerwünschten Rundungseffekten kommen. Die Aktion kann eine leere Liste zurückliefern, wenn dem Handwerker noch keine Wohnungsunternehmen zugeordnet wurden. Wenn dem Handwerker noch keine PN zugeordnet wurde, ist die Liste leer. Kommentare liefern nun wichtige Hinweise zur Anwendung der Informationen aus den gelieferten Schaltern. Seite 5 von 11

6 Element erptype in Struktur settingstype von Aufzählungstyp in Zeichenkette umgewandelt neues Element usesfpawithdiscount Vermeidung von Schnittstellenänderungen bei Unterstützung weiterer ERP- Systeme. Gibt an, ob Rabatte bei Einheitspreispositionen übertragen werden dürfen. neues Element allfpa Gibt an, ob bei der Rechnungslegung für dieses Wohnungsunternehmen alle dem Handwerker für dieses Wohnungsunternehmen zugeordneten Einheitspreisabkommen verwendet werden dürfen (=true) oder nicht (=false). neues Element enableconditionalacceptance- ForOrder Gibt an, ob Annahme unter Vorbehalt erlaubt ist (siehe Erweiterung setorderstate). neues Element enableparkingorder Gibt an, ob Parken erlaubt ist (siehe Erweiterung setorderstate). List List List List neues Element invoicewithoutworkdone Element subunr ist optional (vorher Pflichtfeld) Element presentationid in Struktur ListResponse ist nun Pflichtfeld Optionales Element fpa in Struktur ListResponse ergänzt Optionales Element person (enthält Ausführungsort) in Struktur ListResponse ergänzt Optionales Element location wird nur noch mit Lage-Information bestückt Optionales Element entrance in Struktur Response ergänzt Gibt an, ob die Rechnungsstellung erlaubt ist, wenn der Auftrag im Status Leistung erbracht (DONE) ist (siehe setorderstate). Wird die SubUnr angegeben, so werden nur die Aufträge für die angegebene SubUnr geliefert. Wird die SubUnr nicht angegeben, werden alle Aufträge zur MandantenUnr und zu allen SubUnr geliefert. Natürlich werden die weiteren Filterkriterien in beiden Fällen berücksichtigt. Achtung: Die MandantenUnr ist auch gleichzeitig eine SubUnr. Dieses Element enthält immer die anzuzeigende Auftragsnummer. Falls vorhanden, wird hier der Schlüssel des Einheitpreisabkommens aus dem Auftragskopf übertragen. Ermöglicht die Anzeige des Ausführungsorts in einer Listendarstellung, ohne für alle Aufträge ausführen zu müssen. Informationen bezüglich Eingang, Etage, Gebäude in eigene Felder ausgelagert. Separates Feld für den ggf. vorhandenen Eingang. Seite 6 von 11

7 setorderstate setorderstate setorderstate setorderstate getinvoicelist Optionales Element floor in Struktur Response ergänzt Optionales Element building in Struktur Response ergänzt Optionales Element priority in Struktur Response ergänzt Optionales Element referencenumber in Struktur Response ergänzt Element flatrateorder in Struktur Response ergänzt Optionales Element orderidentifier in Struktur Response ergänzt Element creationdate in Struktur Response ergänzt Neue Status in Aufzählung von Element state (PARKED, CONDITIONALACCEPTANCE) Definition des optionalen Elements cancellationreason korrigiert (Länge auf 350 Zeichen gesetzt) Optionales Element parkingreason ergänzt Optionales Element parkingnote ergänzt Element subunr ist optional (vorher Pflichtfeld) Separates Feld für die ggf. vorhandene Etagen-Angabe Separates Feld für die ggf. vorhandene Gebäudeangabe. Separates Feld für die ggf. vorhandene Prioritätsangabe. Separates Feld für die ggf. vorhandene Referenznummer. Separates Feld für die Angabe, ob es sich um einen Auftrag mit pauschalierter Leistung handelt, für den keine Rechnung geschrieben werden darf.. Separates Feld für die ggf. vorhandene Angabe der Auftragskennung. Separates Feld für die Angabe des Erzeugungsdatums. Neue Statusangabe Parken bzw. Annahme unter Vorbehalt. Diese Status dürfen gesetzt werden, wenn die entsprechenden Schalter (enableparkingorder, enableconditionalacceptancefororder) in Response den Wert true enthalten. Vereinheitlichung von Schnittstellendefinition in Response und setorderstate. Statusübergang auf PARKED erfordert die Angabe eines Parkgrundes (Quelle ist die Liste der cancellationreason- Liste aus Response). Beim Statusübergang PARKED kann zusätzlich ein Vermerk übertragen werden. Wird die SubUnr angegeben, so werden nur die Rechnungen für die angegebene SubUnr geliefert. Wird die SubUnr nicht angegeben, werden alle Rechnungen zur MandantenUnr und zu allen SubUnr geliefert. Natürlich werden die weiteren Filterkriterien in beiden Fällen berücksichtigt. Achtung: Die Mandantenunr ist auch Seite 7 von 11

8 gleichzeitig eine SubUnr. getinvoicelist getinvoice getfpanames getfpanames getfpa Optionales Element since in last- Change (analog zu List) umbenannt In der Struktur getinvoiceresponse beim Element position die Angabe minoccurs=1 entfernt da Standardwert In der Struktur getfpanamesresponse steht das Element fpa nun optional zur Verfügung. In der Struktur fpa stehen die Elemente deduction und surcharge nun optional zur Verfügung. In der Struktur getfparesponse steht das Element article nun optional zur Verfügung. Bedeutung des Filterkriteriums: letztes Änderungsdatum. Strukturbereinigung (keine funktionale Auswirkung). Es kann auch eine leere Ergebnismenge geliefert werden, wenn dem Handwerker für die angegebene PN-UNR- SubUnr-Kombination kein Einheitspreisabkommen zugeordnet ist. Es gibt Einheitspreisabkommen ohne Ab- bzw. Zuschläge. Es kann leere Einheitspreisabkommen geben. putattachment Element ordermareonid ergänzt Es ist nur möglich einen Anhang zu einer Rechnung oder zu einem Auftrag hochzuladen (bisher nur Rechnung). listattachment In der Struktur listattachmentresponse steht das Element attachment nun optional zurverfügung. Es gibt Fälle, in denen zu einem Auftrag bzw. zu einer Rechnung keine Anhänge existieren. Element pdftext entfernt Anpassung an die neue Oberfläche der Rechnung. Definition des Elements text geändert Max. Länge Element price bei Standardpositionen (invoicepositionrequesttype) ist nun Pflichtfeld Element text bei Standardpositionen (invoicepositionrequesttype) ist nun Pflichtfeld Implementierungshinweis: Abhängig vom Wert des Elements archive in Response sind 650 (false) bzw Zeichen (true) erlaubt. Standardpositionen ohne Preis wurden von der Geschäftslogik bereits abgelehnt. Die Definition war falsch. Standardpositionen ohne Text wurden von der Geschäftslogik bereits abgelehnt. Die Definition war falsch. Seite 8 von 11

9 putnvoice putnvoice putnvoice Element articlekey bei Einheitspreis-Positionen (invoicenonfreefpapositionrequest Type) ist nun Pflichtfeld Element fpa bei Einheitspreis- Positionen (invoicenonfreefpapositionrequest Type) ist nun Pflichtfeld Optionales Element discount bei Einheitspreis-Positionen (invoicenonfreefpapositionrequest Type) ergänzt Element articlekey bei freien Einheitspreis-Positionen (invoicefreefpapositionrequesttyp e) ist nun Pflichtfeld Element text bei freien Einheitspreis-Positionen (invoicefreefpapositionrequesttyp e) ist nun Pflichtfeld Element fpa bei freien Einheitspreis- Positionen (invoicefreefpapositionrequesttyp e) ist nun Pflichtfeld Optionales Element discount bei freien Einheitspreis-Positionen (invoicefreefpapositionrequesttyp e) ergänzt Wenn Lohnkosten nicht an das Wohnungsunternehmen übermittelt werden können, gibt es nun einen Fehler statt einer Warnung. Einheitspreis-Positionen ohne Artikelschlüssel wurden von der Geschäftslogik bereits abgelehnt. Die Definition war falsch. Einheitspreispositionen ohne Einheitspreisabkommen-Schlüssel wurden von der Geschäftslogik bereits abgelehnt. Die Definition war falsch. Neue Funktionalität: Rabatte auf Einheitspreispositionen sind möglich, sofern der Schalter "usesfpawithdiscount " in Response auf true steht. Freie Einheitspreispositionen ohne Artikelschlüssel wurden von der Geschäftslogik bereits abgelehnt. Die Definition war falsch. Freie Einheitspreispositionen ohne Positionstext wurden von der Geschäftslogik bereits abgelehnt. Die Definition war falsch. Freie Einheitspreispositionen ohne Einheitspreisabkommen-Schlüssel wurden von der Geschäftslogik bereits abgelehnt. Die Definition war falsch. Neue Funktionalität: Rabatte auf freie Einheitspreispositionen sind möglich, sofern der Schalter "usesfpawithdiscount " in Response auf true steht. Überarbeitung der Rechnungsvalidierung: liefert nun generell Fehler, wenn Angaben enthalten sind, die Mareon nicht weiterleiten kann. Bisher wurden diese Angaben durch Mareon entfernt. Ob Lohnkosten zulässig sind, erkennen Sie am Setting " disable35a " in Seite 9 von 11

10 Response. Wenn Skontoangaben nicht an das Wohnungsunternehmen übermittelt werden können, gibt es nun einen Fehler statt einer Warnung. Wenn das Kennzeichen "Versicherungsfall" nicht an das Wohnungsunternehmen übermittelt werden kann, gibt es nun einen Fehler statt einer Warnung. Wenn das Kennzeichen "Mieterverschulden" nicht an das Wohnungsunternehmen übermittelt werden kann, gibt es nun einen Fehler statt einer Warnung. Information: Validierung beim Speichern von Rechnungen in der Mareon- Business-Logik wurde komplett überarbeitet. Dies hat jedoch keine direkten Auswirkungen auf die Struktur der Schnittstelle. Überarbeitung der Rechnungsvalidierung: liefert nun generell Fehler, wenn Angaben enthalten sind, die Mareon nicht weiterleiten kann. Bisher wurden diese Angaben durch Mareon entfernt. Ob Skontoangaben zulässig sind, erkennen Sie am Setting " disableskonto " in Response. Überarbeitung der Rechnungsvalidierung: liefert nun generell Fehler, wenn Angaben enthalten sind, die Mareon nicht weiterleiten kann. Bisher wurden diese Angaben durch Mareon entfernt. Ob das Kennzeichen "Versicherungsfall" zulässig ist, erkennen Sie am Setting " disableinsuranceclaims " in Response. Überarbeitung der Rechnungsvalidierung: liefert nun generell Fehler, wenn Angaben enthalten sind, die Mareon nicht weiterleiten kann. Bisher wurden diese Angaben durch Mareon entfernt. Ob das Kennzeichen "Mieterverschulden" zulässig ist, erkennen Sie am Setting " disabletenantliable " in Response. Bisherige spezifische Fehlermeldungen bleiben erhalten (z. B. Fehler 306, INVOICE_FINAL_FORWARDED). Die Fehlertexte und die Art der Fehlermeldungen im nicht spezifischen Fehler 304 wurden jedoch zum Großteil überarbeitet. Seite 10 von 11

11 getinvoice Element pdftext entfernt Anpassung an die neue Oberfläche der Rechnung. getinvoice Fehlermeldungen Definition des Elements text geändert Max. Länge In der Struktur genericfault Element any optional gemacht. Inhalt von text und pdftext verschmolzen. Es gibt Fehlermeldungen ohne Ergänzungselemente. Seite 11 von 11