1

TECHNISCHE SCHNITTSTELLENBESCHREIBUNG

für den Webservice via PEPPOL des Access Points (Corner 2) des Bundes

Version 1.0

Datum: 16.07.2018

2

INHALTSVERZEICHNIS

1 EINLEITUNG .............................................................................................................................................. 4

1.1 Ziel des Dokuments ........................................................................................................................... 4

1.2 Abgrenzung ......................................................................................................................................... 4

2 ALLGEMEINES .......................................................................................................................................... 5

2.1 PEPPOL - ein europaweites Netzwerk zum Übermitteln elektronischer Dokumente ............ 5

2.2 Infrastruktur des PEPPOL-Netzwerks (4-Corner-Modell) ........................................................... 5

2.3 XRechnung .......................................................................................................................................... 7

3 GRUNDLAGEN ZUR IMPLEMENTIERUNG DER SCHNITTSTELLE ..................................................... 8

3.1 Einordnung in das 4-Corner-Modell ............................................................................................... 8

3.2 Technischer Ablauf einer Rechnungseinlieferung ...................................................................... 9

3.3 Genereller Ablauf einer Rechnungseinlieferung ......................................................................... 9

4 AUTHENTIFIZIERUNG UND NETZWERKVERBINDUNG ................................................................... 11

4.1 Transportverschlüsselung bei der Netzwerkverbindung ......................................................... 11

4.2 Authentifizierung ............................................................................................................................. 11

4.2.1 Benutzername und Passwort ......................................................................................... 11

4.2.2 HTTPS Client Zertifikate .................................................................................................. 11

5 API BESCHREIBUNG .............................................................................................................................. 12

5.1 Aufrufbare Operationen .................................................................................................................. 12

5.1.1 Operation Rechnung validieren (checkInvoice) ......................................................... 12

5.1.2 Operation Rechnung validieren und einliefern (deliverInvoice) .............................. 13

5.1.3 Technischen Status abrufen (checkTechnicalStatus) .............................................. 15

5.2 SOAP .................................................................................................................................................. 15

5.2.1 Schnittstelle des SOAP-Webservices .......................................................................... 16

5.2.2 XML-Datentypen des SOAP-Webservices .................................................................. 16

5.3 REST ................................................................................................................................................... 16

5.3.1 Schnittstelle des REST-Services ................................................................................... 16

3

5.3.2 Datentypen/Parameter des REST-Services ................................................................ 17

6 ANLAGEN ................................................................................................................................................. 18

Version Datum Beschreibung

1.0 16.07.2018 Initiale Version

Tabelle 1: Versionshistorie

4

1 EINLEITUNG

Mit der Webservice-Schnittstelle für PEPPOL soll es Rechnungssendern (sog. Endnutzern) möglich sein, Rech-nungen im Format XRechnung an die Rechnungsempfänger des Bundes zu liefern. In diesem Dokument wird der Umgang mit der Schnittstelle aus Sicht eines Rechnungssenders beschrieben.

Als synchrones Ergebnis der Lieferung erhalten die Rechnungssender eine Rückmeldung, ob die Rechnung po-sitiv validiert wurde bzw. eine Liste mit Fehlermeldungen, die verhindern, dass die Rechnung weitergeleitet wird. Darüber hinaus ermöglicht es die Schnittstelle den aktuellen technischen Status von Rechnungen abzu-rufen.

Zukünftig könnten auch Rechnungsempfänger der Länder über PEPPOL erreicht werden. Voraussetzung hierfür ist, dass die Länder PEPPOL-Zugangspunkte aufbauen oder bestehende nutzen, an denen ihre Rechnungsemp-fänger angeschlossen sind. Diese können von den Rechnungssendern über die hier dokumentierte Schnittstelle erreicht werden.

1.1 Ziel des Dokuments

Das vorliegende Dokument soll die Integration der angebotenen Schnittstelle in das PEPPOL-Netzwerk verein-fachen. Deshalb werden neben der Bereitstellung einer WSDL- und einer XSD-Datei zusätzlich allgemeine In-formationen zur Schnittstelle und zu PEPPOL gegeben. Diese sollen den integrierenden Entwicklern helfen, die Schnittstelle korrekt umzusetzen.

1.2 Abgrenzung

Das vorliegende Dokument soll kein organisatorischer Leitfaden für Rechnungssender sein, um Zugang zu dem PEPPOL Access Point auf Corner 2 des Bundes zu erhalten. Es ist eine technische Beschreibung der Schnittstelle erweitert um allgemeine Informationen, um eine technische Integration zu vereinfachen.

Hinweis: Da die Schnittstelle zum aktuellen Zeitpunkt noch nicht umgesetzt ist, kann es zukünftig zu Anpassungen kommen. Es handelt sich folglich bei der vor-liegenden Definition lediglich um eine erste Version, wobei signifikante Verän-derungen nicht erwartet werden.

Detaillierte Informationen zur angebotenen REST-Schnittstelle (WADL- oder Swagger-Datei) werden zu einem späteren Zeitpunkt nachgeliefert. Die Operationen, Eingabe- und Ausgabeparameter orientieren sich allerdings an denen, die in Kapitel 4 des vorliegenden Dokuments beschrieben sind.

5

2 ALLGEMEINES

2.1 PEPPOL - ein europaweites Netzwerk zum Übermitteln elektronischer Dokumente

Das PEPPOL-Netzwerk ermöglicht eine lose Kopplung von Auftraggebern und Lieferanten zum Zweck des Über-tragens elektronischer Dokumente im Rahmen von Beschaffungen und Vergaben. Es existiert dabei ein klares Rahmenwerk für die Verbindung zwischen dem Rechnungssender und dem Rechnungsempfänger, die Wahl der Zugangspunkte (der sogenannten Access Points) bleibt allerdings frei und es existiert damit keine starre Bezie-hung. Aufgrund seiner Interoperabilität, seiner europaweiten Organisation und der speziellen Ausrichtung ist es für elektronische Rechnungen und zukünftige weitere elektronische Dokumente im Beschaffungswesen (und außerhalb) besonders geeignet. Der IT-Planungsrat hat daher festgestellt, dass mit PEPPOL ein geeigneter Marktstandard zur Übermittlung elektronischer Rechnungen an alle öffentlichen Auftraggeber zur Verfügung steht, der von Seiten der europäischen Kommission für die Digitalisierung des Beschaffungswesens empfohlen wird.

2.2 Infrastruktur des PEPPOL-Netzwerks (4-Corner-Modell)

PEPPOL nutzt das europäische eDelivery Network, das Teil des europäischen Programms für Investitionen in europäische Infrastruktur Connecting Europe ist (Connecting Europe Facility, CEF, https://ec.europa.eu/cefdigi-tal/wiki/display/CEFDIGITAL/eDelivery).

Das PEPPOL eDelivery Network besteht aus den folgenden Diensten:

Access Points (AP) Zugangspunkte für Rechnungssender und Rechnungsempfänger im Kontext der eRechnung

Service Metadata Publishers (SMP) Verzeichnisse für die Adressen und die Fähigkeiten der Teilnehmer

Service Metadata Locator (SML) DNS-ähnliches System, das zu einer bestimmten Teilnehmer-ID den dazugehörigen Service Metadata Publisher (SMP) findet, in dem die spezifischen Details des Teilnehmers inklusive dessen Zugangs-punkte verzeichnet sind

Zwischen dem Rechnungssender und dem Rechnungslieferanten befinden sich Access Points als weitere tech-nische Infrastruktur-Komponenten. Diese sind im folgenden „4-Corner-Modell“ zusammengefasst.

6

Abbildung 1: Das 4-Corner-Modell

Die Kopplung von Auftraggeber und Lieferant geschieht über Access Points in das Netzwerk. Über diese Access Points versenden oder empfangen die Teilnehmer die elektronischen Dokumente. In der Abbildung sind die Zugangspunkte als „Corner 2“ und „Corner 3“ gekennzeichnet.

2

Access Point zum Emp-

fang elektronischer Rech-nungen

3

Übermittlung zwischen den Zugangspunkten

SML

SMP

Lokalisieren von SMP

Daten über techn. Eigenschaften

und Adresse des Teilnehmers

Rechnungsempfänger (Freigabesysteme der Verwaltungen)

4

Access Point mit unter-schiedlichen Eingangska-

nälen

Zugriff zum Übermit-teln von Dokumenten

Corner

Rechnungssender (Lieferant)

Zugriff zum Abholen von Dokumenten

Corner

Corner

Corner

1

7

2.3 XRechnung

XRechnung ist ein XML-basiertes semantisches Datenmodell, das als Standard für elektronische Rechnungen eingeführt wird, die an die öffentlichen Verwaltungen in Deutschland gesendet werden. Der Standard XRech-nung wurde in der 23. Sitzung des IT-Planungsrats für Bund und Länder festgelegt. Mit dem Standard XRech-nung setzt Deutschland die Vorgaben des Europäischen Komitee für Normung (CEN) für die in einer elektroni-schen Rechnung enthaltenen Daten um.

Weiterführende Informationen zum Standard XRechnung können bei der Koordinierungsstelle für IT -Standards (KoSIT) erhalten werden1.

Hinweis: Aktuell nimmt der PEPPOL Access Point des Bundes auf Corner 2 über den in diesem Dokument beschriebenen Webservice Rechnungen im Format XRechnung nur mit der Syntax UBL2 an. Um die Komplexität der Schnittstelle möglichst gering zu halten ist es geplant XRechnungen in der Syntax UN/CEFACT3 erst nach einer Interimszeit, spätestens Ende des Jahres 2020 (zur Verpflichtung der Auftragnehmer des Bundes 4), anzu-nehmen und in das PEPPOL-Netzwerk einzuliefern.

1 KosIT – Standard XRechnung (https://www.xoev.de/die_standards/xrechnung-14741) 2 Universal Business Language Version 2.1 (http://docs.oasis-open.org/ubl/UBL-2.1.html) 3 UN/CEFACT CII (https://www.unece.org/cefact/xml_schemas/index) 4 E-Rechnungsverordnung (E-Rech-VO) - Verordnung über die elektronische Rechnungsstellung im öffentlichen Auftragswesen des Bundes (https://www.bmi.bund.de/SharedDocs/downloads/DE/gesetztestexte/e-rechnungsverordnung.html)

8

3 GRUNDLAGEN ZUR IMPLEMENTIERUNG DER SCHNITTSTELLE

3.1 Einordnung in das 4-Corner-Modell

Im vorliegenden Dokument soll die Schnittstelle von Corner 1 zu Corner 2 beschrieben werden. Diese Schnitt-stelle wird vom Access Point auf Corner 2 angeboten und kann von den Rechnungssendern auf Corner 1 genutzt werden, um Access Points der öffentlichen Verwaltung auf Corner 3 zu erreichen.

Die folgende Abbildung illustriert den Ausschnitt des 4-Corner-Modells (zwischen Rechnungssender und dem Zugangspunkt auf Corner 2), der nachfolgend konkreter beschrieben wird.

Abbildung 2: Einordnung des Webservices in das 4-Corner-Modell

2

Access Point zum Emp-fang elektronischer Rech-

nungen

3

Übermittlung zwischen den Zu-gangspunkten

SML

SMP

Lokalisieren von SMP

Daten über techn. Eigen-schaften und Adresse des

Teilnehmers

Rechnungsempfänger (Freigabesysteme der Verwaltungen)

4

Access Point mit einem Webservice

1

Zugriff zum Übermit-teln von Dokumenten

Corner

Rechnungssender (Lieferant)

Zugriff zum Abholen

von Dokumenten

Corner

Corner

Corner

9

3.2 Technischer Ablauf einer Rechnungseinlieferung

Der technische Ablauf einer Rechnungseinlieferung ist in der folgenden Abbildung dargestellt:

Abbildung 3: Technischer Ablauf der Übermittlung einer Rechnung

Der Rechnungssender kann eine XRechnung über den angebotenen Webservice per PEPPOL des Access Points (AP) des Bundes auf Corner 2 einliefern. Die Rechnung wird synchron validiert und bei einem positiven Validie-rungsergebnis in das PEPPOL-Netzwerk eingeleitet. Anhand der übergebenen Leitweg-ID 5 (innerhalb des Ein-gabeparameters PEPPOLReceiverID) wird die XRechnung durch das PEPPOL-Netzwerk zum korrekten Access Point (an dem der Rechnungsempfänger - im Falle eines öffentlichen Auftraggebers des Bundes - mit seiner Leitweg-ID angeschlossen ist) der öffentlichen Verwaltung (Bund oder Länder) transferiert. Den technischen Status der eingelieferten Rechnung bzw. den Status zu ihrem Transfer im PEPPOL-Netzwerk kann der Rech-nungssender nachgehend an der Schnittstelle erfragen.

3.3 Genereller Ablauf einer Rechnungseinlieferung

Die folgende Abbildung veranschaulicht den detaillierteren Ablauf einer (positiven) Rechnungsübermittlung und einer Abfrage zum technischen Status.

Zu beachten ist, dass es zukünftig möglich sein wird, nicht nur Rechnungsempfänger des Bundes zu erreichen, sondern ebenso Rechnungsempfänger der Länder. Hierfür werden neben einem Access Point des Bundes auf Corner 3 auch Access Points der Länder auf Corner 3 angeboten, an denen ihre jeweiligen Rechnungsempfänger angeschlossen sein werden.

5 Informationen zur Leitweg-ID: https://www.xoev.de/sixcms/media.php/13/20180214-Zusammenfassung-Leitweg-ID_V1.pdf

10

Abbildung 4: Detaillierter Ablauf der Übermittlung einer Rechnung

11

4 AUTHENTIFIZIERUNG UND NETZWERKVERBINDUNG

Da im Rahmen des Sendens von Rechnungen Dokumente mit sicherheitsrelevanten Informationen verschickt werden, muss möglichst sichergestellt werden, dass diese Informationen nicht von Dritten abgefangen, geän-dert oder gelesen werden. Um dies sicherzustellen, werden im Rahmen der Webservice-Schnittstelle folgende Maßnahmen umgesetzt.

4.1 Transportverschlüsselung bei der Netzwerkverbindung

Sämtliche Zugriffe auf die Webservice-Schnittstellen erfolgen über HTTP. Dabei kommt ausschließlich HTTPS zum Einsatz, sodass alle Daten während der Übertragung verschlüsselt sind.

4.2 Authentifizierung

Aktuell wird eine Authentifizierung mit Benutzernamen und Passwort umgesetzt. Sollte zukünftig eine signifi-kante Anzahl an Täuschungsversuchen über die Schnittstelle registriert werden, könnte zusätzlich ein zweiter Sicherheitsfaktor – die Nutzung von Client-Zertifikaten – eingeführt werden.

4.2.1 Benutzername und Passwort

Um die Zugriffe zu authentifizieren und zu autorisieren, werden die Attribute „Benutzername“ und „Passwort“ verwendet. Diese Daten werden beim Eingangskanal SOAP durch WS-Security und das UsernameTokenProfile unterstützt. Beim Eingangskanal REST kommt HTTP Basic Auth zum Einsatz, da die Daten per HTTPS verschlüs-selt übertragen werden.

4.2.2 HTTPS Client Zertifikate

Um eine Eingrenzung des Nutzerkreises zu erreichen, können perspektivisch SSL –Client-Zertifikate verwendet werden. Wird kein bzw. ein ungültiges Zertifikat bei dem Aufruf mitgeliefert, kann die Netzwerkverbindung sofort auf der Transport-Schicht unterbunden werden.

12

5 API BESCHREIBUNG

Es werden zwei unterschiedliche Arten der Schnittstelle angeboten. Einerseits ein klassischer SOAP -basierter Webservice und zudem ein modernerer REST-basierter Service. Beide Typen der Schnittstelle unterscheiden sich nicht in ihren angebotenen Operationen und den dazugehörigen Ein- bzw. Ausgabeparametern. Diese wer-den nachfolgend unabhängig von gewählten Implementierung beschrieben.

5.1 Aufrufbare Operationen

Es existieren drei aufrufbare Operationen:

Rechnung validieren (checkInvoice) Die übertragene XRechnung wird validiert. Das Validierungsergebnis wird dem Rechnungslieferanten innerhalb eines synchronen Aufrufs zur Verfügung gestellt. Die übergebene XRechnung wird NICHT in das PEPPOL-Netzwerk weitergeleitet.

Rechnung validieren und einliefern (deliverInvoice) Die übertragene XRechnung wird validiert und das Ergebnis wird innerhalb eines synchronen Aufrufs an den Rechnungslieferanten zurückgegeben. Bei einem positiven Validierungsergebnis wird die übergebene XRechnung in das PEPPOL-Netzwerk weitergeleitet und eine eindeutige Transfernummer als Teil der synchronen Rückgabe an den Lieferanten zurückgegeben.

Technischen Status abrufen (checkTechnicalStatus) Über die eindeutige Transfernummer kann ein technischer Status aus dem PEPPOL-Netzwerk zu einer übergebenen XRechnung abgefragt werden. Dieser technische Status quittiert den Empfang der XRechnung am jeweiligen PEPPOL Access Point auf Corner 3. Es ist dann davon auszugehen, dass der Access Point auf Corner 3 die XRechnung an die dort angeschlossenen Rechnungsempfänger weiter-leitet.

5.1.1 Operation Rechnung validieren (checkInvoice)

Eingabeparameter

Als zentraler Eingabeparameter dient die zu übermittelnde bzw. zu validierende XRechnung. Diese muss als XML-Dokument im UBL-Format übergeben werden. Als weitere Parameter werden der PEPPOL Participant Iden-tifier des Senders und des Receivers (die Leitweg-ID ohne Trennzeichen) erwartet. Da keine Weiterleitung in das PEPPOL-Netzwerk erfolgt, werden die übergebenen Werte der beiden PEPPOL Participant Identifier ignorier t (eine Befüllung ist allerdings erforderlich).

Die folgende Tabelle listet die Eingabeparameter auf, die für einen Aufruf der Schnittstelle mitgeliefert werden müssen.

13

Name Typ Beschreibung

XRechnung

(Invoice/Credit-

Note)

XML bzw.

Invoice

oder

CreditNote

nach UBL

2.1

der Dokumenttyp der einzureichenden oder zu prüfenden XRechnung

Es kann sich bei der Rechnung um eine Rechnung (Invoice) oder Gutschrift (Cre-

ditNote) im UBL-Format handeln.

PEPPOLSenderID

(peppolSenderID)

Zeichen-

kette

der PEPPOL Participant Identifier des Rechnungslieferanten (beispielsweise

gültig in PEPPOL: Umsatzsteuer Identifikationsnummer USt-ID)

Der übergebene Wert wird ignoriert, da keine Weiterleitung erfolgt.

Leitweg-ID bzw.

PEPPOLReceiv-

erID

(peppolReceiv-

erID)

Zeichen-

kette

der PEPPOL Participant Identifier des Rechnungsempfängers (die Leitweg-ID

ohne Trennzeichen)

Der übergebene Wert wird ignoriert, da keine Weiterleitung erfolgt.

Tabelle 2: Eingabeparameter der Operation Rechnung validieren

Ausgabeparameter

Die folgende Tabelle listet die Ausgabeparameter auf, die nach einem Aufruf der Schnittstelle zurückgeliefert werden.

Name Typ Beschreibung

Erfolgreich

(accepted) Boolean gibt an, ob die XRechnung erfolgreich validiert werden konnte

Transfernummer

(transferNumber)

Zeichen-

kette leer, da keine Weiterleitung in das PEPPOL-Netzwerk erfolgt

Fehlermeldungen

(error) Liste

eine Liste von Fehlermeldungen (Typ: error), die eine Übermittlung der XRech-

nung verhindern

leer, falls bei der Validierung keine Fehler signalisiert wurden

Warnungen

(warning) Liste

eine Liste von Warnungen (Typ: warning), die eine Übermittlung der XRechnung

nicht verhindern

leer, falls bei der Validierung keine Warnungen signalisiert wurden

Tabelle 3: Ausgabeparameter der Operation Rechnung validieren

5.1.2 Operation Rechnung validieren und einliefern (deliverInvoice)

Eingabeparameter

Als zentraler Eingabeparameter dient die zu übermittelnde bzw. zu validierende XRechnung. Diese muss als XML-Dokument im UBL-Format übergeben werden. Als weitere Parameter werden der PEPPOL Participant Iden-tifier des Senders und des Receivers (die Leitweg-ID ohne Trennzeichen) erwartet. Da eine Weiterleitung in das PEPPOL-Netzwerk erfolgt, müssen die übergebenen Werte der beiden PEPPOL Participant Identifier korrekt sein.

14

Die folgende Tabelle listet die Eingabeparameter auf, die für einen Aufruf der Schnittstelle mitgeliefert werden müssen.

Name Typ Beschreibung

XRechnung

(Invoice/Credit-

Note)

XML bzw.

Invoice

oder

CreditNote

nach UBL

2.1

der Dokumententyp der einzureichenden oder zu prüfenden XRechnung enthält

Es kann sich bei der Rechnung um eine Rechnung (Invoice) oder Gutschrift (Cre-

ditNote) im UBL-Format handeln.

PEPPOLSenderID

(peppolSenderID)

Zeichen-

kette

der PEPPOL Participant Identifier des Rechnungslieferanten (beispielsweise

gültig in PEPPOL: Umsatzsteuer Identifikationsnummer USt-ID)

Leitweg-ID bzw.

PEPPOLReceiv-

erID

(peppolReceiv-

erID)

Zeichen-

kette

der PEPPOL Participant Identifier des Rechnungsempfängers (bei öffentlichen

Auftraggebern des Bundes: Leitweg-ID ohne Trennzeichen) innerhalb der öf-

fentlichen Verwaltung

Tabelle 4: Eingabeparameter der Operation Rechnung validieren und einliefern

Ausgabeparameter

Die folgende Tabelle listet die Ausgabeparameter auf, die nach einem Aufruf der Schnittstelle zurückgeliefert werden.

Name Typ Beschreibung

Erfolgreich

(accepted) Boolean

gibt an, ob die XRechnung erfolgreich validiert und für eine Weiterleitung in

das PEPPOL-Netzwerk entgegengenommen werden konnte

Transfernummer

(transferNumber)

Zeichen-

kette

liefert eine eindeutige Nummer, mit der Aufrufe der Schnittstelle nachverfolgt

werden können, bspw. um Übertragungsprobleme genauer diagnostizieren zu

können

Fehlermeldungen

(error) Liste

eine Liste von Fehlermeldungen (Typ: error), die eine Übermittlung der XRech-

nung verhindern

leer, falls bei der Validierung keine Fehler signalisiert wurden

Warnungen

(warning) Liste

eine Liste von Warnungen (Typ: warning), die eine Übermittlung der XRechnung

nicht verhindern

leer, falls bei der Validierung keine Warnungen signalisiert wurden

Tabelle 5: Ausgabeparameter der Operation Rechnung validieren und einliefern

15

5.1.3 Technischen Status abrufen (checkTechnicalStatus)

Eingabeparameter

Die folgende Tabelle listet die Eingabeparameter auf, die für einen Aufruf der Schnittstelle mitgeliefert werden müssen.

Name Typ Beschreibung

Transfernummer

(transferNumber)

Zeichen-

kette

die bei einer erfolgreichen Einlieferung einer XRechnung erhaltene Transfer-

nummer

Tabelle 6: Eingabeparameter der Operation Technischen Status abrufen

Ausgabeparameter

Die folgende Tabelle listet die Ausgabeparameter auf, die nach einem Aufruf der Schnittstelle zurückgeliefert werden.

Name Typ Beschreibung

Status

(status)

Zeichen-

kette

der technische Status der eingelieferten Rechnung

Gültige Werte sind hier:

PENDING - Es ist noch keine technische Rückmeldung vorhanden.

TRANSFERRED - Die Rechnung wurde erfolgreich im PEPPOL-Netzwerk trans-

feriert.

ERROR - Es ist ein technischer Fehler aufgetreten. Die Rechnung konnte nicht

transferiert werden.

Fehlermeldung

(errorMessage)

Zeichen-

kette

eine (möglicherweise leere) Fehlermeldung, die eine Übermittlung der XRech-

nung verhindert

Tabelle 7: Ausgabeparameter der Operation Technischen Status abrufen

5.2 SOAP

Das Simple Object Access Protocol (SOAP) ist ein herstellerunabhängiger Standard, der ein Netzwerkprotokoll zur Ausführung entfernter Prozeduren (remote procedure calls) beschreibt. SOAP basiert auf den ebenfalls her-stellerunabhängigen Standards Extensible Markup Language (XML) zur Serialisierung von Daten und dem Hyper Text Transfer Potocol (HTTP) zur Übertragung von Daten.

Die Operationen („checkInvoice“ , „deliverInvoice“ sowie „checkTechnicalStatus“) stehen als separate SOAP-Methoden zur Verfügung und sind entsprechend im SOAP-Aufruf auszuwählen. Die XRechnung muss als Einga-beparameter im SOAP-Envelope verpackt übertragen werden.

16

5.2.1 Schnittstelle des SOAP-Webservices

Um eine möglichst hohe Interoperabilität der Schnittstelle zu gewährleisten, wurde der SOAP Webservice im Document/Literal Wrapped Style definiert. Detaillierte Angaben zur SOAP-Schnittstelle können aus der dazu-gehörigen WSDL-Datei (itzbund-peppol-c2.wsdl) entnommen werden. Hierdurch können mit entsprechen-den Werkzeugen Client-Bibliotheken automatisiert erzeugt werden.

5.2.2 XML-Datentypen des SOAP-Webservices

Informationen zu den konkreten XML-Datentypen können der zu diesem Dokument mitgelieferten XSD-Datei (itzbund-peppol-c2-datatypes.xsd) entnommen werden.

5.3 REST

Hinweis: Zusätzlich zu der SOAP-basierten Schnittstelle wird zukünftig ein REST-Service angeboten werden. Diese befindet sich aktuell noch im Aufbau. Detail-lierte Informationen (mit einer technischen Dokumentation als WADL oder Swagger) werden in einer nachfolgenden Version dieses Dokuments geliefert werden. Allgemeine Informationen werden nachfolgend skizziert.

Representational State Transfer (REST) ist eine Alternative zu SOAP, die ebenfalls auf HTTP und XML basiert. Allerdings kommen auch alternative Serialisierungsformen wie Javascript Object Notation (JSON) zum Einsatz.

Die Auswahl der Methode („checkInvoice“ , „deliverInvoice“ sowie „checkTechnicalStatus“) erfolgt durch einen Pfad in der angefragten URL. Die XRechnung muss bei den Operationen „checkInvoice“ und „deliverInvoice“ direkt im HTTP-Request-Body übertragen und der Content-Type auf „text/xml“ gesetzt werden. Die beiden PEPPOL Participant Identifier müssen dabei in der URL mitgegeben werden.

Nachfolgend ein beispielhafter Aufruf über das Werkzeug cURL:

curl -H "Content-Type: text/xml" -H "Accept: application/json" -d @meineXRechnung.xml -X POST http://example.org/peppol-ap/api/deliverinvoice/von/<peppol-sender-id>/an/<peppol-empfaenger-id>5

Alle Ausgabeparameter werden in der HTTP-Antwort übertragen. Dabei stehen verschiedene Serialisierungs-formate zur Auswahl (XML und JSON), die durch die Anfragestelle ausgewählt werden (Accept -Header in der HTTP-Anfrage).

5.3.1 Schnittstelle des REST-Services

Zukünftig wird entweder eine WADL- oder eine Swagger-Datei bereitgestellt. Hierdurch können bei entspre-chender Werkzeugunterstützung REST-Clients automatisiert erstellt werden.

17

5.3.2 Datentypen/Parameter des REST-Services

Die Eingabe- und Ausgabeparameter unterscheiden sich nicht von den bereits in Kapitel 5.1 generell beschrie-benen. Zukünftig wird entweder eine WADL- oder eine Swagger-Datei bereitgestellt.

18

6 ANLAGEN

WSDL-Datei itzbund-peppol-c2.wsdl (zusätzlich separat erhältlich)

1. <?xml version="1.0" encoding="UTF-8" standalone="no"?> 2. <definitions name="PeppolC2Service" 3. targetNamespace="http://www.itzbund.de/itzbund-peppol-c2" 4. xmlns="http://schemas.xmlsoap.org/wsdl/" 5. xmlns:tns="http://www.itzbund.de/itzbund-peppol-c2" 6. xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 7. xmlns:pc2="http://www.itzbund.de/itzbundC2-WS-Datatypes" 8. xmlns:xs="http://www.w3.org/2001/XMLSchema"> 9. <documentation> 10. Service: PeppolC2Service 11. Version: 1.0 12. Verantwortlich: 13. ITZBund 14. </documentation> 15. <types> 16. <!-- ===== Importe ===== --> 17. <xs:schema> 18. <xs:import 19. namespace="http://www.itzbund.de/itzbundC2-WS-Datatypes" 20. schemaLocation="./itzbund-peppol-c2-datatypes.xsd" /> 21. </xs:schema> 22. </types> 23. <!-- ===== Messages ===== --> 24. <message name="DeliverInvoiceRequest"> 25. <part name="parameters" element="pc2:DeliverInvoice" /> 26. </message> 27. <message name="DeliverInvoiceResponse"> 28. <part name="parameters" element="pc2:DeliverInvoiceResponse" /> 29. </message> 30. <message name="DeliverInvoiceFault"> 31. <part name="parameters" element="pc2:DeliverInvoiceFault"></part> 32. </message> 33. <message name="CheckInvoiceRequest"> 34. <part name="parameters" element="pc2:CheckInvoice"></part> 35. </message> 36. <message name="CheckInvoiceResponse"> 37. <part name="parameters" element="pc2:CheckInvoiceResponse"></part> 38. </message> 39. <message name="CheckInvoiceFault"> 40. <part name="parameters" element="pc2:CheckInvoiceFault"></part> 41. </message> 42. <message name="CheckTechnicalStatusRequest"> 43. <part name="parameters" element="pc2:CheckTechnicalStatus"></part> 44. </message> 45. <message name="CheckTechnicalStatusResponse"> 46. <part name="parameters" 47. element="pc2:CheckTechnicalStatusResponse"></part> 48. </message> 49. <message name="CheckTechnicalStatusFault"> 50. <part name="parameters" element="pc2:CheckTechnicalStatusFault"></part> 51. </message> 52. <!-- ===== PortType ===== --> 53. <portType name="InvoiceDeliveryInterface"> 54. <documentation> 55. Angeboten werden drei Operationen im Kontext der 56. Einlieferung von XRechnungen nach PEPPOL über den Webservice des 57. Access Points auf Corner2. 58. checkInvoice: Die übergebene XRechnung wird 59. validiert. Das Validierungsergebnis wird zurückgeliefert

19

60. deliverInvoice: Zusätzlich zur Validierung wird die übergebene 61. XRechnung - bei einem positiven Validierungsergebnis - in das 62. PEPPOL-Netzwerk eingeliefert und eine Transfernummer als Teil des 63. Ergebisses zurückgeliefert. 64. checkTechnicalStatus: Der technische 65. Status aus dem PEPPOL-Netzwerk wird anhand der Transfernummer 66. ermittelt und zurückgegegeben. 67. </documentation> 68. <operation name="DeliverInvoice"> 69. <input message="tns:DeliverInvoiceRequest" /> 70. <output message="tns:DeliverInvoiceResponse" /> 71. <fault name="fault" message="tns:DeliverInvoiceFault"></fault> 72. </operation> 73. <operation name="CheckInvoice"> 74. <input message="tns:CheckInvoiceRequest"></input> 75. <output message="tns:CheckInvoiceResponse"></output> 76. <fault name="fault" message="tns:CheckInvoiceFault"></fault> 77. </operation> 78. <operation name="CheckTechnicalStatus"> 79. <input message="tns:CheckTechnicalStatusRequest"></input> 80. <output message="tns:CheckTechnicalStatusResponse"></output> 81. <fault name="fault" message="tns:CheckTechnicalStatusFault"></fault> 82. </operation> 83. </portType> 84. <!-- ===== Binding ===== --> 85. <binding name="InvoiceDeliveryBinding" 86. type="tns:InvoiceDeliveryInterface"> 87. <soap:binding style="document" 88. transport="http://schemas.xmlsoap.org/soap/http" /> 89. <operation name="DeliverInvoice"> 90. <soap:operation 91. soapAction="/peppol-ap/service/InvoiceDeliveryService/DeliverIn-

voice" /> 92. <input> 93. <soap:body use="literal" /> 94. </input> 95. <output> 96. <soap:body use="literal" /> 97. </output> 98. <fault name="fault"> 99. <soap:fault use="literal" name="fault" /> 100. </fault> 101. </operation> 102. <operation name="CheckInvoice"> 103. <soap:operation 104. soapAction="/peppol-ap/service/InvoiceDeliveryService/CheckIn-

voice" /> 105. <input> 106. <soap:body use="literal" /> 107. </input> 108. <output> 109. <soap:body use="literal" /> 110. </output> 111. <fault name="fault"> 112. <soap:fault use="literal" name="fault" /> 113. </fault> 114. </operation> 115. <operation name="CheckTechnicalStatus"> 116. <soap:operation 117. soapAction="/peppol-ap/service/InvoiceDeliveryService/CheckTechni-

calStatus" /> 118. <input> 119. <soap:body use="literal" /> 120. </input> 121. <output> 122. <soap:body use="literal" />

20

123. </output> 124. <fault name="fault"> 125. <soap:fault use="literal" name="fault" /> 126. </fault> 127. </operation> 128. </binding> 129. <!-- ===== Service ===== --> 130. <service name="InvoiceDeliveryService"> 131. <port binding="tns:InvoiceDeliveryBinding" 132. name="InvoiceDeliveryService"> 133. <soap:address location="http://www.example.org/" /> 134. </port> 135. </service> 136. </definitions>

21

Schema-Datei itzbund-peppol-c2-datatypes.xsd (zusätzlich separat erhältlich)

1. <?xml version="1.0" encoding="UTF-8"?> 2. <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 3. targetNamespace="http://www.itzbund.de/itzbundC2-WS-Datatypes" 4. xmlns="http://www.itzbund.de/itzbundC2-WS-Datatypes" 5. xmlns:ublin="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" 6. xmlns:ublcn="urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2" 7. elementFormDefault="qualified"> 8. <!-- ===== Importe ===== --> 9. <xs:import namespace="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" 10. schemaLocation="./UBL/maindoc/UBL-Invoice-2.1.xsd"/> 11. <xs:import namespace="urn:oasis:names:specification:ubl:schema:xsd:CreditNote-

2" 12. schemaLocation="./UBL/maindoc/UBL-CreditNote-2.1.xsd"/> 13. <!-- ===== Element Deklarationen ===== --> 14. 15. <!-- ===== Wrapper Elemente fuer Document-literal-wrapped ===== --> 16. 17. <xs:element name="DeliverInvoice" type="invoiceDocumentType"> 18. <xs:annotation> 19. <xs:documentation> 20. Das Dokument, welches die einzureichende oder zu prü-

fende (CEN- und ggf. XRechnung-Regeln) Rechnung enthält. 21. </xs:documentation> 22. </xs:annotation> 23. </xs:element> 24. <xs:element name="DeliverInvoiceResponse" type="resultType"> 25. <xs:annotation> 26. <xs:documentation> 27. Das Ergebnisdokument beim Prüfen oder Einreichen eines Rechnungdoku-

ments. 28. </xs:documentation> 29. </xs:annotation> 30. </xs:element> 31. <xs:element name="DeliverInvoiceFault" type="technicalErrorType"> 32. <xs:annotation> 33. <xs:documentation> 34. Daten eines technischen Fehlers, der während der Nutzung des Webser-

vice aufgetreten ist. 35. </xs:documentation> 36. </xs:annotation> 37. </xs:element> 38. <xs:element name="CheckInvoice" type="invoiceDocumentType"> 39. <xs:annotation> 40. <xs:documentation> 41. Das Dokument, welches die einzureichende oder zu prü-

fende (CEN- und ggf. XRechnung-Regeln) Rechnung enthält. 42. </xs:documentation> 43. </xs:annotation> 44. </xs:element> 45. <xs:element name="CheckInvoiceResponse" type="resultType"> 46. <xs:annotation> 47. <xs:documentation> 48. Das Ergebnisdokument beim Prüfen oder Einreichen eines Rechnungdoku-

ments. 49. </xs:documentation> 50. </xs:annotation> 51. </xs:element> 52. <xs:element name="CheckInvoiceFault" type="technicalErrorType"> 53. <xs:annotation> 54. <xs:documentation> 55. Daten eines technischen Fehlers, der während der Nutzung des Webser-

vice aufgetreten ist. 56. </xs:documentation> 57. </xs:annotation>

22

58. </xs:element> 59. <xs:element name="CheckTechnicalStatus" type="technicalStatusInputType"> 60. <xs:annotation> 61. <xs:documentation> 62. Der Input um einen technischen Status zu einer eingelieferten Rech-

nung über den Transfer innerhalb des PEPPOL-Netzwerks abzufragen. 63. </xs:documentation> 64. </xs:annotation> 65. </xs:element> 66. <xs:element name="CheckTechnicalStatusResponse" type="techni-

calStatusResultType"> 67. <xs:annotation> 68. <xs:documentation> 69. Der technische Status einer eingelieferten Rechnung über den Trans-

fer innerhalb des PEPPOL-Netzwerks. 70. </xs:documentation> 71. </xs:annotation> 72. </xs:element> 73. <xs:element name="CheckTechnicalStatusFault" type="technicalErrorType"> 74. <xs:annotation> 75. <xs:documentation> 76. Daten eines technischen Fehlers, der während der Nutzung des Webser-

vice aufgetreten ist. 77. </xs:documentation> 78. </xs:annotation> 79. </xs:element> 80. 81. <!-- ===== Typ Deklarationen ===== --> 82. <xs:complexType name="issueType"> 83. <xs:annotation> 84. <xs:documentation> 85. Problemmeldung aus der Prüfung der CEN- und XRechnungs-Regeln. 86. </xs:documentation> 87. </xs:annotation> 88. <xs:sequence> 89. <xs:element name="code" type="xs:string"> 90. <xs:annotation> 91. <xs:documentation> 92. Code bzw. ID der Geschäftsregel, gegen die verstoßen wurde. 93. Der Code enspricht der ID aus Kapitel 6.4 der CEN-Spezifika-

tion FprEN 16931-1 94. bzw. der ID aus Kapitel 13 des XRechnung Standards Version 1.1 95. </xs:documentation> 96. </xs:annotation> 97. </xs:element> 98. <xs:element name="description" type="xs:string" minOccurs="0"> 99. <xs:annotation> 100. <xs:documentation> 101. Eine textuelle Beschreibung des aufgetretenen Problems. 102. </xs:documentation> 103. </xs:annotation> 104. </xs:element> 105. </xs:sequence> 106. </xs:complexType> 107. 108. <xs:complexType name="resultType"> 109. <xs:annotation> 110. <xs:documentation> 111. Ergebnis des Einreichens oder der Prüfung eines Rechnungdokuments. 112. </xs:documentation> 113. </xs:annotation> 114. <xs:sequence> 115. <xs:element name="accepted" type="xs:boolean"> 116. <xs:annotation> 117. <xs:documentation> 118. Gibt an, ob das Rechnungsdokument akzeptiert wird und

23

119. eine Weiterleitung an den Rechnungsempfänger erfolgt. 120. </xs:documentation> 121. </xs:annotation> 122. </xs:element> 123. <xs:element name="transferNumber" type="xs:string" minOccurs="0"> 124. <xs:annotation> 125. <xs:documentation> 126. Die TransferNummer der eingelieferten Rechnung, falls diese ak-

zeptiert wurde. 127. Unter dieser Nummer kann der technische Status einer eingelie-

ferten Rechnung 128. abgeholt werden. 129. </xs:documentation> 130. </xs:annotation> 131. </xs:element> 132. <xs:element name="error" type="issueType" minOccurs="0" maxOccurs="un-

bounded"> 133. <xs:annotation> 134. <xs:documentation> 135. Liste der aufgetretenen Problemen, die dazu füh-

ren, dass das Rechnungsdokument 136. nicht akzeptiert wird. 137. </xs:documentation> 138. </xs:annotation> 139. </xs:element> 140. <xs:element name="warning" type="issueType" minOccurs="0" maxOccurs="un-

bounded"> 141. <xs:annotation> 142. <xs:documentation> 143. Liste der aufgetretenen Problemen, die jedoch nicht zu einer Ab-

lehnung 144. des Rechnungdokuments führen. 145. </xs:documentation> 146. </xs:annotation> 147. </xs:element> 148. </xs:sequence> 149. </xs:complexType> 150. 151. <xs:complexType name="invoiceDocumentType"> 152. <xs:annotation> 153. <xs:documentation> 154. Der Dokumenttyp, welcher die einzureichende oder zu prüfende 155. (CEN- und ggf. XRechnung-Regeln) Rechnung enthält. 156. Es kann sich bei der Rechnung um eine Rechnung (Invoice) oder 157. Gutschrift (CreditNote) im UBL-Format handeln. 158. </xs:documentation> 159. </xs:annotation> 160. <xs:sequence> 161. <xs:element name="peppolSenderID" type="xs:string"> 162. <xs:annotation> 163. <xs:documentation> 164. Die PEPPOL Participant ID des Senders. 165. </xs:documentation> 166. </xs:annotation> 167. </xs:element> 168. <xs:element name="peppolReceiverID" type="xs:string"> 169. <xs:annotation> 170. <xs:documentation> 171. Die PEPPOL Participant ID des Empfaengers - hier die Leitweg-

ID ohne Trennzeichen. 172. </xs:documentation> 173. </xs:annotation> 174. </xs:element> 175. <xs:choice> 176. <xs:element ref="ublin:Invoice"> 177. <xs:annotation>

24

178. <xs:documentation> 179. Rechnung im UBL-Format 180. </xs:documentation> 181. </xs:annotation> 182. </xs:element> 183. <xs:element ref="ublcn:CreditNote"> 184. <xs:annotation> 185. <xs:documentation> 186. Gutschrift im UBL-Format 187. </xs:documentation> 188. </xs:annotation> 189. </xs:element> 190. </xs:choice> 191. </xs:sequence> 192. </xs:complexType> 193. 194. <xs:complexType name="technicalErrorType"> 195. <xs:annotation> 196. <xs:documentation> 197. Daten eines technischen Fehlers, der während der 198. Nutzung des Webservice aufgetreten ist. 199. </xs:documentation> 200. </xs:annotation> 201. <xs:sequence> 202. <xs:element name="code" type="xs:string"> 203. <xs:annotation> 204. <xs:documentation> 205. Fehlernummer bzw. ID des Fehlers. 206. </xs:documentation> 207. </xs:annotation> 208. </xs:element> 209. <xs:element name="details" type="xs:string"> 210. <xs:annotation> 211. <xs:documentation> 212. Beschreibung des Fehlers. 213. </xs:documentation> 214. </xs:annotation> 215. </xs:element> 216. </xs:sequence> 217. </xs:complexType> 218. 219. <xs:complexType name="technicalStatusInputType"> 220. <xs:annotation> 221. <xs:documentation> 222. Der Input um einen technischen Status zu einer eingelieferten Rech-

nung 223. über den Transfer innerhalb des PEPPOL-Netzwerks abzufragen. 224. </xs:documentation> 225. </xs:annotation> 226. <xs:sequence> 227. <xs:element name="transferNumber" type="xs:string"> 228. <xs:annotation> 229. <xs:documentation> 230. Die TransferNummer der akzeptierten Rechnung. 231. Unter dieser Nummer kann der technische Status einer eingelie-

ferten Rechnung 232. abgeholt werden. 233. </xs:documentation> 234. </xs:annotation> 235. </xs:element> 236. </xs:sequence> 237. </xs:complexType> 238. 239. <xs:complexType name="technicalStatusResultType"> 240. <xs:annotation> 241. <xs:documentation>

25

242. Der technische Status einer eingelieferten Rechnung über den Trans-fer innerhalb

243. des PEPPOL-Netzwerks. 244. </xs:documentation> 245. </xs:annotation> 246. <xs:sequence> 247. <xs:element name="status" type="xs:string"> 248. <xs:annotation> 249. <xs:documentation> 250. Der technische Status der eingelieferten Rechnung. 251. Gültige Werte sind hier: 252. PENDING - es ist noch keine technische Rueckmeldung vorhanden 253. TRANSFERRED - die Rechnung wurde erfolgreich im PEPPOL-Netz-

werk an den AccessPoint des Empfängers auf Corner3 transferiert. 254. ERROR - es ist ein technischer Fehler aufgetreten - die Rech-

nung konnte nicht transferiert werden 255. </xs:documentation> 256. </xs:annotation> 257. </xs:element> 258. <xs:element name="errorMessage" type="xs:string" minOccurs="0"> 259. <xs:annotation> 260. <xs:documentation> 261. Beschreibung des Fehlers, falls ein Fehler vorliegt. 262. </xs:documentation> 263. </xs:annotation> 264. </xs:element> 265. </xs:sequence> 266. </xs:complexType> 267. </xs:schema>