NEF - PIRR Anrop av webbtjänster
1. Inledning
Detta dokument ger en beskrivning av hur webbservices ska anropas i E-hälsomyndighetens system Partneringångar för Receptregistret (PIRR). PIRR består av en webbservice som exponerar tjänster för e-recept (human och djur).
1.1 Målgrupp
Dokumentet är avsett för externa parter som ska implementera applikationer mot PIRR.
1.2 Referenser
1.3 Termer och begrepp
Term |
Betydelse |
Webbservice |
Funktionalitet som är implementerad enligt Ref. 1. |
Tjänst |
Det finns fyra tjänster i PIRR. Nytt recept human och Nytt recept djur samt Makulera recept human och Makulera recept djur. |
Meddelande |
Den information som utväxlas mellan en klient och webbservice i PIRR. Sker med hjälp av SOAP. (Ref. 1 och 2). |
Indata |
Meddelande som skickas till tjänsten. |
Utdata |
Meddelande som returneras från tjänsten. |
Partner |
Användare av E-hälsomyndighetens webbservice. |
APERAK |
Application Error and Acknowledgement Message (UN/EDIFACT)
Svarsmeddelande innehållande information om anropet till tjänsten, en så kallad applikationskvittens. |
Saml-intyg |
Intyg enligt SAML2-standard som styrker identiteten av den som anropar tjänsten. Utfärdat av en IdP som är godkänd av Sambi-federationen eller annan av E-hälsomyndigheten godkänd operatör. |
2. Beskrivning av PIRR webbservice
PIRR består av en webbservice med en operation (callService) som är generell. Via den generella ingången erhålls åtkomst till funktionalitet för att skapa och makulera e-recept för human och djur. I svaret returneras, förutom applikationskvittens (APERAK), en struktur som innehåller svarskoder vilka beskriver hur anropet gick.
2.1 Säkerhet
Alla anrop sker över HTTPS (Ref. 4). Servercertifikat signerat av utfärdarorganisationen Thawte används. Klientcertifikat används inte.
2.1.1 S/MIME-signering
Elektroniska meddelanden som skickas till E-hälsomyndigheten ska S/MIME-signeras (Ref. 5).
2.1.2 Åtkomstintyg utfärdat av IdP godkända av Sambi- federationen eller annan av E-hälsomyndigheten godkänd operatör
För att styrka identiteten vid anrop av tjänsten så ska anroparen tillhandahålla ett Saml-intyg utfärdat av en IdP som är godkänd av Sambi-federationen eller annan av E-hälsomyndigheten godkänd aktör (Ref. 8, 10). Intyget placeras i SOAP-headern enligt nedan. Se sidan Anropsinformation17.1
2.2 Adresser till partneringångar
2.2.1 Produktion
Internet |
Enligt instruktion från E-hälsomyndigheten |
Sjunet |
Enligt instruktion från E-hälsomyndigheten |
2.2.2 Externtest
Internet |
Enligt instruktion från E-hälsomyndigheten |
Sjunet |
Enligt instruktion från E-hälsomyndigheten |
XML-scheman och WSDL erhålls från E-hälsomyndighetens kundytor.
2.3 Indata
Eventuellt Saml-intyg som styrker anroparens identitet placeras i soap:header-elementet. Intyget behöver styrka att anropare är förskrivare enligt Kravspecifikation Behörighetsstyrning (Ref. 9) för humanrecepttjänsterna respektive veterinär för djurrecepttjänsterna.
Meddelandet som skickas till callService placeras i soap:body-elementet och består av ett header- och ett body-element. I headerelementet finns bland annat information som visar vilken tjänst man önskar använda sig av (nytt e-recept eller makulering). E-recept eller makuleringsbegäran skickas med som ett signerat S/MIME-dokument och ska vara base64-encodat.
E-recept eller makuleringsbegäran definieras i respektive tjänsts XML-schema (Prescription.xsd, PrescriptionAnimal.xsd, PrescriptionCancellation.xsd och PrescriptionCancellationAnimal.xsd samt de generella Common.xsd, Types.xsd och Header.xsd). Samtliga scheman kan erhållas från E-hälsomyndighetens kundytor.
2.3.1 Exempel på ett anrop till NewPrescription:
Encoding: UTF-8
HTTP-headers: {SOAPAction=[""], Accept=[*]}
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<!-- Saml-intyg -->
<wsse:Security ...>
...
</wsse:Security>
</soap:Header>
<soap:Body>
<ns2:callService xmlns="java:se.receptpartner.pirr.service"
xmlns:ns2="http://pirr.receptpartner.se/pi-wsgeneric-1.3/wsgeneric?WSDL">
<serviceRequest>
<requestHeader>
<securityDescriptor>
<certificate></certificate>
<credentials></credentials>
<principal></principal>
</securityDescriptor>
<serviceDescriptor>
<checksum>
<type></type>
<value>0</value>
</checksum>
<conversationId>WS1394608518935</conversationId>
<name>NewPrescription</name>
<priority>0</priority>
</serviceDescriptor>
</requestHeader>
<requestBody>
<requestDocuments>
<RequestDocument>
<contentLength>17392</contentLength>
<contentTransferEncoding>binary</contentTransferEncoding>
<contentType>multipart/signed</contentType>
<data>UTI5dWRHVnVkQ...</data>
</RequestDocument>
</requestDocuments>
</requestBody>
</serviceRequest>
</ns2:callService>
</soap:Body>
</soap:Envelope>
2.3.2 Indata detaljerat (Namnen härrör från XML-schema i WSDL)
2.3.2.1 ServiceRequestWrapper
Namn |
Typ |
Kardinalitet |
serviceRequest |
ServiceRequest |
1..1 |
2.3.2.2 ServiceRequest
Namn |
Typ |
Kardinalitet |
requestHeader |
RequestHeader |
1..1 |
requestBody |
RequestBody |
1..1 |
2.3.2.3 RequestHeader
Namn |
Typ |
Kardinalitet |
securityDescriptor |
SequrityDescriptor |
1..1 |
serviceDescriptor |
ServiceDescriptor |
1..1 |
2.3.2.4 RequestBody
Namn |
Typ |
Kardinalitet |
requestDocuments |
ArrayOfRequestDocument |
1..1 |
2.3.2.5 SecurityDescriptor
Namn |
Typ |
Kardinalitet |
Beskrivning |
certificate |
String |
1..1 |
Reserverat för framtida användning. |
credentials |
String |
1..1 |
Reserverat för framtida användning. |
principal |
String |
1..1 |
Reserverat för framtida användning. |
2.3.2.6 Checksum
Namn |
Typ |
Kardinalitet |
Beskrivning |
type |
String |
1..1 |
Reserverat för framtida användning. |
value |
long |
1..1 |
Reserverat för framtida användning. |
2.3.2.7 ServiceDescriptor
Namn |
Typ |
Kardinalitet |
Beskrivning |
checksum |
Checksum |
1..1 |
Reserverat för framtida användning. |
conversationId |
String |
1..1 |
Anropets identitet. Skickas tillbaka i svaret. Genereras om inget anges. |
name |
String |
1..1 |
NewPrescription – Nytt recept
MakuleraReceptService – Makulera recept
NewPrescriptionAnimal – Nytt recept djur
CancelPrescriptionAnimal – Makulera recept djur |
priority |
int |
1..1 |
Reserverat för framtida användning. |
2.3.2.8 ArrayOfRequestDocument
Namn |
Typ |
Kardinalitet |
Beskrivning |
RequestDocument |
RequestDocument |
0..unbounded |
PIRR stödjer för närvarande bara en och endast en förekomst av RequestDocument. |
2.3.2.9 RequestDocument
Namn |
Typ |
Kardinalitet |
Beskrivning |
contentLength |
int |
1..1 |
Längden i bytes på innehållet i data-elementet. |
contentTransferEncoding |
String |
1..1 |
binary. |
contentType |
String |
1..1 |
multipart/signed. |
data |
base64Binary
(Ref. 7) |
1..1 |
Recept/Makulering förpackat i ett signerat S/MIME-meddelande som base64-encodas (Base64-encoding används för att minska risken för att data förvanskas under överföring. Base64-encodad data hanteras av de flesta system).
E-recept eller makuleringsbegäran enligt Prescription.xsd eller
PrescriptionAnimal.xsd eller
PrescriptionCancellation.xsd eller
PrescriptionCancellationAnimal.xsd |
2.4 Utdata
Svarsmeddelandet som skickas från PIRR i soap:body består att ett header- och ett body-element. I headerelementet finns information som möjliggör att avgöra hur anropet gick. Beroende på status för anropet levereras en applikationskvittens (APERAK) i serviceResponse.responseBody.responseDocuments.ResponseDocument.data. Innehållet i data-elementet signeras inte men är base64-encodat. Applikationskvittensen finns definierad i respektive tjänsts XML-schema (Aperak.xsd, AperakAnimal.xsd, AperakCancellation.xsd och AperalCancellationAnimal.xsd samt de generella Common.xsd, Types.xsd och Header.xsd). Samtliga scheman kan erhållas från E-hälsomyndighetens kundytor.
2.4.1 Exempel på ett svar från NewPrescription:
Encoding: UTF-8
HTTP-headers: {content-type=[text/xml;charset=UTF-8], Date=[Wed, 02 Apr 2014 08:25:39 GMT], Content-Length=[3542]}
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:callServiceResponsexmlns="java:se.receptpartner.pirr.service"
xmlns:ns2="http://pirr.receptpartner.se/pi-wsgeneric-1.3/wsgeneric?WSDL">
<serviceResponse>
<responseHeader>
<resultDescriptor>
<code>0</code>
<message>Accepterat</message>
</resultDescriptor>
<serviceDescriptor>
<checksumxmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
<conversationId>WS1394608518935</conversationId>
<name>NewPrescription</name>
<priority xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
</serviceDescriptor>
</responseHeader>
<responseBody>
<responseDocuments>
<ResponseDocument>
<contentLength>1391</contentLength>
<contentTransferEncoding>binary</contentTransferEncoding>
<contentType>application/xml</contentType>
<data>UEQ5NGJXd2dkbVZ5YzJsdmJqMG...</data>
</ResponseDocument>
</responseDocuments>
</responseBody>
</serviceResponse>
</ns2:callServiceResponse>
</soap:Body>
</soap:Envelope>
2.4.2 Utdata detaljerat
2.4.2.1 ServiceResponseWrapper
Namn |
Typ |
Kardinalitet |
serviceResponse |
ServiceResponse |
1..1 |
2.4.2.2 ServiceResponse
Namn |
Typ |
Kardinalitet |
responseHeader |
ResponseHeader |
1..1 |
responseBody |
ResponseBody |
1..1 |
2.4.2.3 ReponseHeader
Namn |
Typ |
Kardinalitet |
resultDescriptor |
ResultDescriptor |
1..1 |
serviceDescriptor |
ServiceDescriptor |
1..1 |
2.4.2.4 ResultDescriptor
Namn |
Typ |
Kardinalitet |
Beskrivning |
code |
String |
1..1 |
0 – Accepterat
1 – Accepterat med varning
2 – Ej accepterat
1000-1999 – Tekniskt fel
2000-2999 – Säkerhetsfel
3000-3999 – Fel på indata |
message |
String |
1..1 |
Information om resultatet. |
För koderna 0, 1 och 2 returneras en applikationskvittens (aperak) i serviceResponse.responseBody.responseDocuments.ResponseDocument.data. Beroende på typ av fel kan aperak returneras för koderna 1000-1999, 2000-2999 samt 3000-3999.
För ytterligare information om svarskoder och applikationskvittenser hänvisas till NEF – Riktlinjer kvittenshantering.
2.4.2.5 ResponseBody
Namn |
Typ |
Kardinalitet |
responseDocuments |
ArrayOfResponseDocument |
1..1 |
2.4.2.6 ArrayOfResponseDocument
Namn |
Typ |
Kardinalitet |
Beskrivning |
ResponseDocument |
ResponseDocument |
0..unbounded |
PIRR stödjer för närvarande bara en och endast en förekomst av ResponseDocument. |
2.4.2.7 ResponseDocument
Namn |
Typ |
Kardinalitet |
Beskrivning |
contentLength |
int |
1..1 |
Längden i bytes på innehållet i data-elementet. |
contentTransferEncoding |
String |
1..1 |
binary. |
contentType |
String |
1..1 |
application/xml |
data |
base64Binary
(Ref. 7) |
1..1 |
APERAK enligt
Aperak.xsd eller
AperakAnimal.xsd eller
AperakCancellation.xsd eller
AperalCancellationAnimal.xsd |
2.5 Elementvärden vid utdata
Element |
Värde |
serviceResponse.responseHeader.serviceDescriptor.name |
NewPrescription – Nytt e-recept human
MakuleraReceptService – Makulera e-recept human
NewPrescriptionAnimal – Nytt e-recept djur
CancelPrescriptionAnimal – Makulera e-recept djur |
serviceResponse.responseBody.responseDocuments.ResponseDocument.data |
Aperak enligt
Aperak.xsd eller
AperakAnimal.xsd eller
AperakCancellation.xsd eller
AperalCancellationAnimal.xsd |
serviceResponse.responseBody.responseDocuments.ResponseDocument.contentLength |
Längden i bytes av data. |
serviceResponse.responseBody.responseDocuments.ResponseDocument contentTransferEncoding |
base64 eller binary |
serviceResponse.responseBody.responseDocuments.ResponseDocument.contentType |
application/xml |
serviceResponse.responseHeader.serviceDescriptor.conversationId |
Anropets identitet. Sätts till värdet av motsvarande element i requestet. |
3. Innehåll i data-elementet
3.1 Indata
I dataelementet levereras e-recept/makuleringsbegäran. Formatet på dokumentet ska följa S/MIME version 3-standarden (Ref. 5).
Dokumentet ska signeras och levereras i multipart/signed-format. Certifikatet tillsammans med kedjan upp till CA-certifikatet ska finnas i PKCS-7-delen av dokumentet (Ref. 6). Vidare måste CA-certifikatet finnas installerat hos E-hälsomyndigheten. Detta för att verifiering av inskickat certifikat ska kunna utföras.
Bilden nedan visar strukturen på meddelandet.
![Beskrivning: pirr 2.png]()
S/MIME-header
Content-Type: multipart/signed; protocol="application/pkcs7-signature"; micalg=sha1;
boundary="----=_Part_1_655641627.1394783459289"
OBS. Ovanstående värde på boundary är bara ett exempel.
Part 1-header
Content-Type: application/xml
Content-Transfer-Encoding: binary
charset: utf-8
Part 2-header
Content-Type: application/pkcs7-signature; name=smime.p7s; smime-type=signed-data
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smime.p7s"
Content-Description: S/MIME Cryptographic Signature
3.1.1 Exempel
Content-Type: multipart/signed; protocol="application/pkcs7-signature"; micalg=sha1;
boundary="----=_Part_1_655641627.1394783459289"
------=_Part_1_655641627.1394783459289
Content-Type: application/xml
Content-Transfer-Encoding: binary
charset: utf-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Interchange xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://pirr.receptpartner.se/prescription-1.3/Prescription.xsd">
<MessageRoutingAddress>
...
</MessageRoutingAddress>
<NewPrescriptionMessage>
...
</NewPrescriptionMessage>
</Interchange>
------=_Part_1_655641627.1394783459289
Content-Type: application/pkcs7-signature; name=smime.p7s; smime-type=signed-data
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smime.p7s"
Content-Description: S/MIME Cryptographic Signature
MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAQAAoIAwggPVM
vaADAgECAgEMMA0GCSqGSIb3DQEBBQUAMFQxCzAJBgNVBAYTAlNFMQ4wDAYDVQQIDAVzdGhs
...
AAAAAA=
------=_Part_1_655641627.1394783459289—
3.2 Utdata
I dataelementet kan en applikationskvittens returneras. Innehållet i applikationskvittensen definieras av respektive tjänsts schema. Ingen signering görs på applikationskvittensen (kvittensen returneras inte i S/MIME-format).
3.2.1 Exempel
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Interchange>
<MessageRoutingAddress>
...
</MessageRoutingAddress>
<ApplicationAcknowledgeMessage>
...
<MessageStatus>0</MessageStatus>
<StatusInformation>
<StatusCode>00000</StatusCode>
<Description>0 Receptsamlingen har tagits emot utan upptäckta fel</Description>
</StatusInformation>
</ApplicationAcknowledgeMessage>
</Interchange>
Versionshistorik
Utgåva |
Datum |
Kommentar |
1.0 |
2017-10-13 |
Fastställt dokument. |
| 2.0 |
|
2.3 Lagt till bild 2.3 |
| 2.1 |
2018-12-06 |
Förtydligande kring kravet på S/MIME och signering. |
| 3.0 |
2019-02-26 |
Ändrat samtliga Sambi-referenser till Saml-referenser
1.2 Uppdaterat ref.10 till Saml, lagt till ref.11 Inera-federationen
1.3 Uppdaterat Sambi-intyg till Saml-intyg
2.1.3 Lagt till Inera-federationen, och ref.11
2.3.1 Uppdaterat Soapheader från Sambi-intyg till Saml-intyg
|
| 4.0 |
2020-07-01 |
Redaktionella ändringar, ny stavning E-hälsomyndigheten
2.3.1 + 2.4.1 + 3.1.1 Tagit bort gulmarkerade avsnitt
1.2, 1.3, 2.1.2 Omformulerat kring anslutning av godkända operatörer |
| 5.0 |
2022-03-01 |
2.3.1 + 2.4 Rättat underrubrik från SOAP-headers till det korrekta HTTP-headers |
