Skip to content

SOAP Webservice

This documentation covers usage of the SOAP webservices, mainly used for docbox 3 Hospital and Notfalldienstpanung ( NFD)

Environments

The following table serves as an endpoint URL reference:

System Test Environment Production Environment
SOAP Endpoint soap.test.docbox.swiss soap.docbox.swiss

Authentication

The authentication happens in two steps. A basic auth, which identifies the client/integration and user credentials inside the SOAP calls, which identify the docbox user (e.g. doctor).

Basic Auth

Basic auth credentials are unique by integration (not by provider company), so if your company provides multiple docbox integrations or the same integration for multiple software products, e.g. PIS/KIS, different credential pairs are needed for each integration / product. Basic auth credentials are issued by Visionary AG support. To request credentials (access to APIs), please fill and submit the following form (currently only in German):

get.docbox.swiss/api-key-beantragen

The basic auth credentials are the same for test and production environment and do not regularly expire. In case of a security incident, or any other related reason, Visionary can reset or revoke basic auth credentials. We will notify the affected provider about revocation on the provided email address and phone number.

You can test your basic-auth credentials using the following HTTP call:

curl -v \
  -u '{{basic_user}}:{{basic_password}}' \
  https://soap.test.docbox.swiss/ping

If the response contains Ok, the basic auth credentials work.

For testing SOAP calls, please refer to you implementations own documentation on how to configure basic auth. See SOAP UI Documentation as a reference.

Monitoring

If you have a technical monitoring solution in place, you can use it to check uptime of the SOAP interfaces. To do so, please use the "ping" URL as endpoint configuration:

Environment URL
Test https://soap.test.docbox.swiss/ping
Production https://soap.docbox.swiss/ping

Additionally, you need to provide the Basic-Auth user and password. Depending on your monitoring solution, there is either a specific integration for Basic-Auth credentials, or an option to supply an Authorization header, together with the request.

Caution: As the endpoints are rate-limited, set your check-frequency no shorter than every 5 minutes!

User Credentials

The second authentication mechanism is contained inside the SOAP request. it must contain a security header like the following:

<?xml version="1.0" encoding="utf-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Header>
    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <wsse:UsernameToken>
        <wsse:Username>{{login_id}}</wsse:Username>
        <wsse:Password>{{password}}</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </S:Header>
  <soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <!-- payload -->
  </soapenv:Body>
</S:Envelope>

The user credentials must be set like the following:

  • login_id: The docbox login id of the current user. This is a string similar to: 123456A
  • password: The user logins password.

Note: While older implementations required the password to be hashed using SHA1, plaintext is now also supported. As strong transport-layer security is enforced, there is no need to hash passwords client-side.

HIN Authentication

HIN authentication on API level (for SOAP interfaces) will be discontinued. Please use the Basic Auth mechanism described above.

Upgrading from certificate-based Legacy Endpoints

Many integrators will update from the legacy SOAP authentication mechanism, which was based on an X509 client certificate or secret. Please execute the following steps to upgrade to the new Basic-Auth SOAP endpoints:

1. Request Basic Auth Credentials

If not already done, request a new basic auth credentials pair for each of your products using the form at get.docbox.swiss/api-key-beantragen. See chapter Basic Auth for details.

2. Remove Legacy Authentication Mechanism

Depending on the existing implementation, you either supply the certificate as authentication mechanism, or you prefix the users login-id with the certificate serial.

In case that you use X509 client auth, you can just remove it.

In case you prefixed the username in the SOAP call with the certificate serial (a long string in front of the users docbox loginId), remove that prefix, so just the login id is submitted, like in the example above:

Old:

<wsse:UsernameToken>
  <wsse:Username>{{clientSerial}}{{login_id}}</wsse:Username>
  <wsse:Password>{{password}}</wsse:Password>
</wsse:UsernameToken>

New:

<wsse:UsernameToken>
  <wsse:Username>{{login_id}}</wsse:Username>
  <wsse:Password>{{password}}</wsse:Password>
</wsse:UsernameToken>

3. Add Basic Authentication

Where and how to configure basic auth heavily depends on your client implementation or framework. Most clients should have an out-of-the-box solution for basic auth. Please refer to your client / implementation documentation.

THe following external documentation shows the configuration for SOAP UI CLient.

4. Change the endpoint URL

The last step is to change the base url of the call to the new endpoint, like the following:

Endpoint URL
Old https://[ihe|www.][test.]docbox.ch/cgi-bin/WebObjects/docboxservice.woa/ws/CDACHServicesV2
New https://soap.[test.].docbox.swiss/CDACHServicesV2

NOTE: You can identify affected URLs by searching for docboxservice.woa (production) respectively. All URLs containing those segments need to be changed to the new soap\[.test\].docbox.swiss base URL. URLs containing e.g. docbox.woa, docboxapi.woa, etc. don't need to be changed.

The endpoint URLs are configured as ports in the SOAP definitions of the respecting endpoints. Also, the endpoint URLs are different, depending on the service you use. Please check the following chapters to find the correct endpoint URL(s):

5. URL Signatures

If you use the SSO URL signing mechanism with Clinical Documents' addReferral functionality, you also need to change the URL signature slightly. See chapter URL Signing & SSO for details.

Webservices

Hospital & Clinical Document Endpoint (CDACHServices)

Note: This webservice is in maintenance-only mode and being replaced by CDACHServicesV2. Please consider using the new webservice, as new features and fixed won't be rolled out to legacy services.

The CDACHServices endpoint is used for hospital communication, i.e. document exchange.

The WSDL definition can be found at: soap.[test].docbox.swiss/wsdl/CDACHServices.wsdl

Endpoint URLs as referenced in WSDL:

Environment URL
Test https://soap.test.docbox.swiss/CDACHServices
Production https://soap.docbox.swiss/CDACHServices

URL Signing & SSO

To generate the URL to a referral document, the legacy SSO URL signing mechanism used the client certificate to generate an SSO signature. On the new Basic Auth endpoints, the signing mechanism uses the Basic Auth username instead of the certificate serial, but otherwise stays the same.

With new Basic Auth credentials, the URL signature algorithm changed to the following:

HmacSHA1(
  docboxId + ":" + timestamp + ":" + SHA1(docboxPassword), 
  basicUser // basic auth username instead of certificate serial
)
SSO URL has the following form 
https://www.test.docbox.ch/cgi-bin/WebObjects/docbox.woa/wa/default?loginId=LOGIN_ID&ts=TIMESTAMP&sig=GENERATED_SIGNATURE
Following sample (written in Java) calculates the "sig" value 
// Hashing process to connect to Docbox
public byte[] sig(String loginId, String loginPassword, long ts, String basicUser) {
    try {
        // Concatenate elements
        String message = loginId + ":" + String.valueOf(ts) + ":" + toHex(sha1(loginPassword));

        // Get a Max generator instance
        Mac mac = Mac.getInstance("HmacSHA1");
        mac.init(new SecretKeySpec(toHex(sha1(basicUser)).getBytes("UTF-8"), "HmacSHA1"));

        // Get the Mac and encode it in Base64
        return Base64.encode(mac.doFinal(message.getBytes("UTF-8")));
    } catch (final Exception e) {
        // Error
    }
}

// Helper method to obtain SHA1 hash
static byte[] sha1(String text) {
    try {
        MessageDigest md = MessageDigest.getInstance("SHA");
        md.update(text.getBytes("UTF-8"));
        return md.digest();
    } catch (final Exception e) {
        // Error
    }
}

// Helper method to convert bytes to Hexadecimal form
static String toHex(final byte[] v) {
    char[] hex = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F' };
    String out = "";

    for (final byte element : v) {
        out = out + hex[(element >> 4) & 0xF] + hex[element & 0xF];
    }

    return out;
}

Hospital & Clinical Document Endpoint - Version 2 (CDACHServicesV2)

The CDACHServicesV2 endpoint is used for hospital communication, i.e. document exchange.

The WSDL definition can be found at: soap.[test].docbox.swiss/wsdl/CDACHServicesV2.wsdl

Endpoint URLs as referenced in WSDL:

Environment URL
Test https://soap.test.docbox.swiss/CDACHServicesV2
Production https://soap.docbox.swiss/CDACHServicesV2

Emergency Service Shifts (EmergencyService)

The EmergencyService endpoint is used for emergency shift planning ("NFD", "Notfalldienstplanung").

The WSDL definition can be found at: soap.[test].docbox.swiss/wsdl/EmergencyService.wsdl

Endpoint URLs as referenced in WSDL:

Environment URL
Test https://soap.test.docbox.swiss/EmergencyService
Production https://soap.docbox.swiss/EmergencyService

Appointment Service (ScheduledAppointments)

The ScheduledAppointments endpoint is used to get appointments from docbox services like NFD and ABP.

The WSDL definition can be found at: soap.[test].docbox.swiss/wsdl/ScheduledAppointments.wsdl

Endpoint URLs as referenced in WSDL:

Environment URL
Test https://soap.test.docbox.swiss/ScheduledAppointments
Production https://soap.docbox.swiss/ScheduledAppointments