Denna sida ger en beskrivning av hur webbtjänster 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 djur.

1. Termer och begrepp

2. Beskrivning av PIRR webservice

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 djur. I svaret returneras, förutom applikationskvittens (APERAK), en struktur som innehåller svarskoder vilka beskriver hur anropet gick.

2.1. Säkerhet

E-hälsomyndighetens säkerhetslösning

2.1.1. S/MIME-signering

Elektroniska meddelanden som skickas till E-hälsomyndigheten ska S/MIME-signeras.

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. Intyget placeras i SOAP-headern enligt nedan. Se sidan Anropsinformation WebService (SOAP).

2.1.2.1. Särskild hantering för PIRR/NEF avseende giltighetstid på SAML-intyg

Grundprincipen är att tjänsteanropen ska ske inom SAML-intygets giltighetstid, det vill säga 60 minuter.
I nuläget sker ett flertal tjänsteanrop av olika anledningar dagligen som då skulle ske utanför SAML-intygets giltighetstid.
För att inte få en stor påverkan har myndigheten beslutat att acceptera och ta emot tjänsteranrop med SAML-intyg där giltigheten har förfallit.
Myndigheten kommer acceptera SAML-intyg upp till och med 24 timmar utifrån starttidpunkten för intygets giltighetstid.

Denna funktionalitet finns även för OAuth2-åtkomstintyg.

2.2. Adresser till partneringångar

Adresser för produktion och interntest fås från ehm, både för Internet och Sjunet

2.3. Indata

Eventuellt Saml-intyg som styrker anroparens identitet placeras i soap:header-elementet. Intyget  behöver styrka att anropare är veterinär enligt Kravspecifikation Behörighetsstyrning 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 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 (PrescriptionAnimal.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.

Figur 1. Exempel på ett anrop

Encoding: UTF-8

SOAP 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.1. Indata detaljerat (Namnen härrör från XML-schema i WSDL)

2.3.1.1. ServiceRequestWrapper

2.3.1.2. ServiceRequest

2.3.1.3. RequestHeader

2.3.1.4. RequestBody

2.3.1.5. SecurityDescriptor

2.3.1.6. Checksum

2.3.1.7. ServiceDescriptor

2.3.1.8. ArrayOfRequestDocument

2.3.1.9. RequestDocument

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 (AperakAnimal.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.

Encoding: UTF-8

SOAP 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.1. Utdata detaljerat

2.4.1.1. ServiceResponseWrapper

2.4.1.2. ServiceResponse

2.4.1.3. ResponseHeader

2.4.1.4. ResultDescriptor

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 Riktlinjer kvittenshantering.

2.4.1.5. ResponseBody

2.4.1.6. ArrayOfResponseDocument

2.4.1.7. ResponseDocument

2.5. Elementvärden vid utdata

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.

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. Vidare måste CA-certifikatet finnas installerat hos E-hälsomyndigheten. Detta för att verifiering av inskickat certifikat ska kunna utföras.

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

​

3.1.1.2. Part 1-header

      Content-Type: application/xml
      Content-Transfer-Encoding: binary
      ​charset: utf-8

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

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

<?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>

4. Referenser till andra styrande dokument

Versionshistorik