​Gäller release 16.1

​​​​NEF - PIRR Anrop av webbtj​änster


1. Inledning

Detta dokument ger en beskrivning av hur webservices skall anropas i eHälsomyndighetens system Partneringångar för Receptregistret (PIRR). PIRR består av en webservice som exponerar tjänster för e-recept (human och djur).

1.1 Målgrupp

Dokumentet är avsett för externa parter som skall implementera applikationer mot PIRR.

1.2 Referenser

Nr

N​amn​

URL

1

W3C Web Services​​

www.w3.org/2002/ws

2

HTTP

www.w3.org/Protocols

3

HTTP Authentication: Basic and Digest Access Authentication

www.ietf.org/rfc/rfc2617.txt

4

The Secure Sockets Layer (SSL) Protocol Version 3.0

https://tools.ietf.org/html/rfc6101

5

S/MIME Version 3 Message Specification

www.ietf.org/rfc/rfc2633.txt

6

PKCS #7: Cryptographic Message Syntax

www.ietf.org/rfc/rfc2315.txt

7

base64Binary

http://www.w3.org/TR/xmlschema-2/#base64Binary

1.3 Termer och begrepp

Term

Betydelse

Webservice

Funktionalitet som är implementerad enligt Ref. 1.

Tjänst

Det finns fyra tjänster i PIRR. Nytt recept human och djur samt makulera recept human och djur.

Meddelande

Den information som utväxlas mellan en klient och webservice 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 eHälsomyndighetens webservice.

APERAK

Application Error and Acknowledgement Message (UN/EDIFACT)

Svarsmeddelande innehållande information om anropet till tjänsten.

2. Beskrivning av PIRR webservice

PIRR består av en webservice 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 skall S/MIME-signeras (Ref. 5). 

2.1.2 Autentisering

Varje partner tilldelas en användare samt lösenord som ska användas för autentisering enligt HTTP Basic Authentication (Ref. 3).


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

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 funktionalitet 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/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.

pirr.png ​
 

2.3.1 Exempel på ett anrop till NewPrescription:

Encoding: UTF-8

HTTP-headers: {Authorization=[Basic cGl…], SOAPAction=[""], Accept=[*]}

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 ​ <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 transport. Base64-encodad data hanteras av de flesta system).

e-recept/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 samt 3000-3999. För koderna 2000-2999 returneras ingen aperak.

För ytterligare information om svarskoder och applikationskvittenser hänvisas till dokumentet NEF – Riktlinjer kvittenshantering som kan hämtas från E-hälsomyndighetens kundyta.

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

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.

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 resp. 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

​2014-05-12

Fastställt dokument.​​

​2.0 ​2017-10-17 ​1.2 Lagt till parameter 8-10
1.3 Lagt till parameter Sambi-biljett
2.1.1 + 2.1.2 Uppdaterat krav enligt nya säkerhetslösningen
2.3 Lagt till information om Sambi. Uppdaterat bild
2.3.1 Lagt till Soap: Header i kod
2.5 Uppdaterat beskrivning i tabellrad serviceResponse.responseBody.responseDocuments.ResponseDocument contentTransferEncoding​
3.1 Uppdaterat text
​3.0  ​2017-10-31 ​Lagt tillbaka information som gäller release 16.1
​4.0 2019-11-28​ ​2.3.1 + 2.4.1 + 3.1.1 Tagit bort gulmarkerad information
​5.0 ​2022-03-01 ​Ny stavning på E-hälsomyndigheten
2.3.1 + 2.4.1 Rättat underrubrik från SOAP-headers till det korrekta HTTP-headers
​​​​​