NAV
shell php

Introduction

Welcome to the Pharmed Solutions eHealth-API. The API allows you to send invoices to the relevant insurances, fetch responses and retrieve all information needed.

We have language bindings in shell (cURL) and php . You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right. If you are interested in another programming language, please let us know.

For any comments or improvements please contact us via our website.

Formats

The API will only accept the JSON format. To guarantee type-safety, all requests are validated server-sided against its type.

Responses are delivered in JSON as well. To check the models detail, please refer to the relevant chapters.

Authentication

To authenticate, use this code:

# When using cURL package, you do not have to set a header manually

$curl = curl_init();

curl_setopt($curl,CURLOPT_HTTPAUTHH, CURLAUTH_BASIC);
curl_setopt($curl,CURLOPT_USERPWD, 'johndoe:password_to_test');

curl_setopt($curl,CURLOPT_URL, "example_url");

$result = curl_exec($curl);

curl_close($curl);


    

  import kittn

      api = kittn.authorize('meowmeowmeow')
  

# With shell, you can directly provide your credentials
curl "api_endpoint_here"
-u "johndoe:password_to_test"
    

# Or simply pass the correct header with each request
curl "api_endpoint_here"
-H "Authorization:Basic am9obmRvZTpwYXNzd29yZF90b190ZXN0"

Make sure to replace johndoe:password_to_test with your retrieved credentials.

The API uses Basic Authentication to allow access to the API. You can request an API key by contacting us via email. API keys are valid only for a certain period of time.

The API expects the credentials (username and password) to be included in every request. Most languages will provide helpers to do so. This can be achieved by handing over <username>:<password> as Base64-encoded string to the authorization header:

Authorization: Basic PHVzZXJuYW1lPjo8cGFzc3dvcmQ+

Versioning

Request a specific version:

# Request version 1.0 or 2.1

$curl = curl_init();

curl_setopt($curl,CURLOPT_HTTPAUTHH, CURLAUTH_BASIC);
curl_setopt($curl,CURLOPT_USERPWD, 'johndoe:password_to_test');

curl_setopt($curl,CURLOPT_URL, https://ehealth.pharmedsolutions.ch/api/v1.0/query);
curl_setopt($curl,CURLOPT_URL, https://ehealth.pharmedsolutions.ch/api/v2.1/query);

$result = curl_exec($curl);

curl_close($curl);


    


# Request version 1.0
curl https://ehealth.pharmedsolutions.ch/api/v1.0/query
-u "johndoe:password_to_test"

# Request version 2.1
curl https://ehealth.pharmedsolutions.ch/api/v2.1/query
-u "johndoe:password_to_test"

The API is versioned to account for future enhancements. The specification of the version allows to keep backward compatibility.

The first url-parameter specifies the desired version. An invalid version parameter will be interpreted as the most actual version.

The current stable version is v1.0.

HTTP Request

GET https://ehealth.pharmedsolutions.ch/api/<version>/query

Query Parameters

Parameter Type Description Required
version string Specifies the desired API version.

Basic Types

Document

Representation of document

Properties

Property Type Description Optional
base64 string Base-64 encoded document
name string name of document, must contain a dot (".")
mimeType string MIME-type of document

Employee

Representation of insurance employee

Properties

Property Type Description Optional
firstName string
lastName string
salutation string
phone string
fax string
email string

Insurance

Representation of insurance

Properties

Property Type Description Optional
id int resource ID of the insurance
bag_id int BAG number
name string official name
nameMediData string
insuranceEAN string
recipientEAN string
street string
zip string
city string
law string laws allowed to reimburse
phone string phone number

Physician

Representation of physician

Properties

Property Type Description Optional
id int resource ID of the physician
firstName int
lastName string
salutation string
title string
street string
zip string
city string
phone string
fax string
zsr string
ean string
specialty string specialized area of physician

ResponseMessage

Representation of response message

Properties

Property Type Description Optional
code string see XSD-definition for more detail
message string message as string

ResponseStatus

Representation of response status

Properties

Property Type Description Optional
typ string accepted, rejected or pending
statusIn string status of intermediate (MediData), see XSD for enumeration
statusOut string status of insurance, see XSD for enumeration
typDescription string localized description
statusInDescription string localized description
statusOutDescription string localized description

Users

Register new user

To register a new user, send the following JSON:

{
    "name": "Meierhans",
    "email": "pmeierhans@gmx.ch",
    "ean": "7601999999999,
    "zsr": "Z123456"
}

Request:


$data = array("name" => "Meierhans", "email" => "pmeierhans@gmx.ch", "ean" => "7601999999999", "zsr" => "Z123456");
$data_string = json_encode($data);

$curl = curl_init(https://ehealth.pharmedsolutions.ch/api/v1.0/users/register);

# Request & Content-Header
curl_setopt($curl,CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl,CURLOPT_POSTFIELDS, $data_string);
curl_setopt($curl,CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

# Authentication
curl_setopt($curl,CURLOPT_HTTPAUTHH, CURLAUTH_BASIC);
curl_setopt($curl,CURLOPT_USERPWD, 'johndoe:password_to_test');

$result = curl_exec($curl);

curl_close($curl);


    
  import kittn

      api = kittn.authorize('meowmeowmeow')
  

# Windows user may escape the JSON like "{\"field1\":\"value1\",....}"
curl https://ehealth.pharmedsolutions.ch/api/v1.0/users/register
-u "johndoe:password_to_test"
-H "Content-Type: application/json"
-X POST
-d '{"name":"Meierhans","email":"pmeierhans@gmx.ch","ean":"7601999999999","zsr":"Z123456"}'
-k

The returend JSON has the following structure:

{
 "id": 10
}

This endpoint registers a new user to enable the sending of invoices.

HTTP Request

POST https://ehealth.pharmedsolutions.ch/api/v1.0/users/register

Query Parameters

Parameter Type Description Required
name string name of the user (family name or practice name)
email string valid email address of the user
ean string EAN number of the user (pattern: ^([0-9]{13})$)
zsr string ZSR number of the user (pattern: ^([A-Z]{1})([0-9]{6})$)

Response 200

Parameter Type Description Optional
id int resource ID of the newly registered user

Error 4xx

Status Error Description
400 email.taken email already in use - please specifiy another one
400 invalid.ZSR.format invalid ZSR format supplied
400 invalid.EAN.format invalid EAN format supplied

Data

Get all cantons

Request:



$curl = curl_init(https://ehealth.pharmedsolutions.ch/api/v1.0/cantons/list?language=de);

# Authentication
curl_setopt($curl,CURLOPT_HTTPAUTHH, CURLAUTH_BASIC);
curl_setopt($curl,CURLOPT_USERPWD, 'johndoe:password_to_test');

$result = curl_exec($curl);

curl_close($curl);





curl https://ehealth.pharmedsolutions.ch/api/v1.0/cantons/list?language=fr
-u "johndoe:password_to_test"

The returend JSON has the following structure:

[
  {
    "canton": "SO",
    "name": "Solothurn"
  },
  {...}
]

This endpoint allows to get all cantons

HTTP Request

GET https://ehealth.pharmedsolutions.ch/api/v1.0/cantons/list

Query Parameters

Parameter Type Description Required
language string de (default) or fr

Response 200

Parameter Type Description Optional
canton string official abbreviation (e.g. VD, ZH)
name string localized name of the canton

Get all insurances

Request:



$curl = curl_init(https://ehealth.pharmedsolutions.ch/api/v1.0/insurances/list);

# Authentication
curl_setopt($curl,CURLOPT_HTTPAUTHH, CURLAUTH_BASIC);
curl_setopt($curl,CURLOPT_USERPWD, 'johndoe:password_to_test');

$result = curl_exec($curl);

curl_close($curl);





curl https://ehealth.pharmedsolutions.ch/api/v1.0/insurances/list
-u "johndoe:password_to_test"

The returend JSON has the following structure:

[
  {
    "id": 1,
    "bag_id": "8",
    "name": "CSS Unfallversicherung AG",
    "nameMediData": "CSS Unfallversicherung AG",
    "insuranceEAN": "7601003006780",
    "recipientEAN": "7601003000078",
    "street": "Tribschenstrasse 21 Postfach 2568",
    "zip": "6002",
    "city": "Luzern",
    "law": "uvg",
    "phone": "058 277 11 11"
  },
  {...}
]

This endpoint allows to get all insurances

HTTP Request

GET https://ehealth.pharmedsolutions.ch/api/v1.0/insurances/list

Response 200

Parameter Type Description Optional
id int resource ID of the insurance
bag_id int BAG number
name string official name
nameMediData string
insuranceEAN string
recipientEAN string
street string
zip string
city string
law string laws allowed to reimburse
phone string phone number

Get all laws

Request:



$curl = curl_init(https://ehealth.pharmedsolutions.ch/api/v1.0/laws/list);

# Authentication
curl_setopt($curl,CURLOPT_HTTPAUTHH, CURLAUTH_BASIC);
curl_setopt($curl,CURLOPT_USERPWD, 'johndoe:password_to_test');

$result = curl_exec($curl);

curl_close($curl);





curl https://ehealth.pharmedsolutions.ch/api/v1.0/laws/list
-u "johndoe:password_to_test"

The returend JSON has the following structure:

[
  {
    "name": "uvg",
    "description": "UVG"
  },
  {...}
]

This endpoint allows to get all laws

HTTP Request

GET https://ehealth.pharmedsolutions.ch/api/v1.0/laws/list

Query Parameters

Parameter Type Description Required
language string de (default) or fr

Response 200

Parameter Type Description Optional
name string abbreviation (kvg,vvg,uvg,ivg,mvg,org)
description string localized name of the law

Get tariffs

Request:



$curl = curl_init(https://ehealth.pharmedsolutions.ch/api/v1.0/tariffs/list);

# Authentication
curl_setopt($curl,CURLOPT_HTTPAUTHH, CURLAUTH_BASIC);
curl_setopt($curl,CURLOPT_USERPWD, 'johndoe:password_to_test');

$result = curl_exec($curl);

curl_close($curl);





curl https://ehealth.pharmedsolutions.ch/api/v1.0/tariffs/list
-u "johndoe:password_to_test"

The returend JSON has the following structure:

[
  {
    "id": 15,
    "code": 311,
    "recordType": "record_paramed",
    "vatRate": 0.025,
    "description": "Physiotherapie-Tarif (physioswiss)"
  },
  {...}
]

This endpoint allows to get all tariffs

HTTP Request

GET https://ehealth.pharmedsolutions.ch/api/v1.0/treatment-causes/list

Query Parameters

Parameter Type Description Required
language string de (default) or fr
all boolean retrieve all tariffs available (default = false)

Response 200

Parameter Type Description Optional
id int resource ID of the tariff
code string public ID of the tariff
recordType string values: record_migel, record_paramed, record_tarmed,record_drg,record_lab,record_drug,record_other
vatRate double applicable VAT rate of the tariff (0.0%, 2.5% or 8%)
description string localized description

Get tariff-codes (Tariffziffern)

Request:



$curl = curl_init(https://ehealth.pharmedsolutions.ch/api/v1.0/tariff-codes/list?tariff=311);

# Authentication
curl_setopt($curl,CURLOPT_HTTPAUTHH, CURLAUTH_BASIC);
curl_setopt($curl,CURLOPT_USERPWD, 'johndoe:password_to_test');

$result = curl_exec($curl);

curl_close($curl);





curl https://ehealth.pharmedsolutions.ch/api/v1.0/tariff-codes/list?tariff=311&language=fr
-u "johndoe:password_to_test"

The returend JSON has the following structure:

[
  {
    "id": 544,
    "tariffType": "7301",
    "taxPoints": 48.0,
    "description": "Sitzungspauschale fuer allgemeine Physiotherapie"
  },
  {...}
]

This endpoint allows to get all codes (Tariffziffern) per tariff

HTTP Request

GET https://ehealth.pharmedsolutions.ch/api/v1.0/tariff-codes/list

Query Parameters

Parameter Type Description Required
language string de (default) or fr
tariff string Public ID of tariff for which to get the tariff-codes

Response 200

Parameter Type Description Optional
id int resource ID of the tariff-code
tariffType string public ID of the tariff
taxPoints double number of tax points associated with the code
description string localized description

Get all treatment causes

Request:



$curl = curl_init(https://ehealth.pharmedsolutions.ch/api/v1.0/treatment-causes/list);

# Authentication
curl_setopt($curl,CURLOPT_HTTPAUTHH, CURLAUTH_BASIC);
curl_setopt($curl,CURLOPT_USERPWD, 'johndoe:password_to_test');

$result = curl_exec($curl);

curl_close($curl);





curl https://ehealth.pharmedsolutions.ch/api/v1.0/treatment-causes/list
-u "johndoe:password_to_test"

The returend JSON has the following structure:

[
  {
    "name": "maternity",
    "description": "Schwangerschaft"
  },
  {...}
]

This endpoint allows to get all treatment causes

HTTP Request

GET https://ehealth.pharmedsolutions.ch/api/v1.0/treatment-causes/list

Query Parameters

Parameter Type Description Required
language string de (default) or fr

Response 200

Parameter Type Description Optional
name string official name
description string localized description

Invoices

Send an invoice

JSON:


  {
    "id": 143,
    "attributes": "{...}",
    "patient": "{...}",
    "therapist": "{...}",
    "referrer": "{...}",
    "insurance": "{...}",
    "services": "[...]",
    "diagnoses": "[...]",
    "documents": "[...]",
    "reminder": "{...}",
    "biller": "{...}"
  }

Request:


$data = array("field1" => "value1", "field2" => "value2", "..." => "...",...);
$data_string = json_encode($data);

$curl = curl_init(https://ehealth.pharmedsolutions.ch/api/v1.0/invoice/send);

# Request & Content-Header
curl_setopt($curl,CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl,CURLOPT_POSTFIELDS, $data_string);
curl_setopt($curl,CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

# Authentication
curl_setopt($curl,CURLOPT_HTTPAUTHH, CURLAUTH_BASIC);
curl_setopt($curl,CURLOPT_USERPWD, 'johndoe:password_to_test');

$result = curl_exec($curl);

curl_close($curl);


    
# Windows user may escape the JSON like "{\"field1\":\"value1\",....}"
curl https://ehealth.pharmedsolutions.ch/api/v1.0/invoices/send
-u "johndoe:password_to_test"
-H "Content-Type: application/json"
-X POST
-d '{...}'
-k

The returend JSON has the following structure:

{"id": 143}

This endpoint allows to send an invoice

HTTP Request

POST https://ehealth.pharmedsolutions.ch/api/v1.0/invoices/send

Query Parameters

Parameter Type Description Required
id int resource ID of the invoice
attributes Attributes attributes of the invoice
patient Patient patient treated
therapist Therapist sending therapist or practice
referrer Physician physician that referred the patient
insurance Insurance receiving insurance
services Service[] to be billed medical services
diagnoses Diagnosis[] diagnoses of the patient (not mandatory!)
documents Document[] Base64 encoded prescriptions of referrer
reminder Reminder indicates whether the invoice is a reminder
biller Therapist institutation receiving the money (if not specified, money goes to therapist)

Response 200

Parameter Type Description Optional
id int resource ID of the sent invoice

Error 4xx

Status Error Description
400 error.error.required Some vales are missing, refer to DETAIL for more information
400 no.services.provided At minimum 1 service must be present
400 no.documents.provided At minimum 1 document must be present
400 invalid.service.date The invoice date is before the last service date
400 no.vatNumber.provided VAT number is missing (only if billing with VAT)
400 invalid.insurance.law The specified insurances does not reimburse the specified law
400 no.ahvNumber.provided Missing social security number (AHV). Only required for ivg,mvg.
400 invalid.reminder.date The reminder date is before the invoice date.
400 error.maxLength The string is too long.
400 error.minLength The string is too short.
400 invalid.caseNumber The case number do not match (IVG case format: ([0-9]{14}|[0-9]{10}|[0-9]{9}|[0-9]{6}) )
400 unknown.treatmentCause Treatment cause not from enumeration.
400 unknown.law Law not from enumeration (uvg,vvg,uvg,ivg,mvg,org)
400 invalid.caseDate The case date is after the first service date.
400 missing.caseNumber The case number is missing (uvg,ivg,mvg)
400 missing.caseDate The case date is missing (uvg,ivg,mvg)
400 invalid.doc.name The documents name is invalid.
400 invalid.base64 The documents base64 encoding is invalid.
400 error.max The number is too large.
400 error.min The number is too small.
400 invalid.tariff.recordType The record type is not from the enumeration
400 invalid.tariff.id The tariff id is invalid.
400 invalid.tariff.code The tariff code is invalid.
400 wrong.taxPoints The tariff-codes tax points are not correct.
400 invalid.vatRate The tariff-codes vat rate is not correct.
400 unknown.insurance The insurance is unkown (and cannot be billed)
400 invalid.ahvNumber.format Correct pattern: ^(756)([0-9]{10})$
400 invalid.insuranceNumber.format Invalid insurance number of the patient. Pattern: ^[0-9]{20}$
400 invalid.diagnosis.code Only if ICD-10 diagnoses specified.
400 invalid.referrer.id Unkown referrer (also works via zsr number).
400 invalid.adminInfo The therapists address, ean, or zsr is not correct.
400 no.referrer.provided The referrer is missing.
400 no.insurance.provided The insurance is missing.

Physicians/Referrer

Get physician by ZSR number

Request:



$curl = curl_init(https://ehealth.pharmedsolutions.ch/api/v1.0/physicians/N246212/get);

# Authentication
curl_setopt($curl,CURLOPT_HTTPAUTHH, CURLAUTH_BASIC);
curl_setopt($curl,CURLOPT_USERPWD, 'johndoe:password_to_test');

$result = curl_exec($curl);

curl_close($curl);





curl https://ehealth.pharmedsolutions.ch/api/v1.0/physicians/N246212/get
-u "johndoe:password_to_test"

The returend JSON has the following structure:


{
    "id": 143,
    "firstName": "Robert",
    "lastName": "Huwyler",
    "salutation": "Herr",
    "title": "Dr. med.",
    "street": " Realpstrasse 83",
    "zip": "4054",
    "city": "Basel",
    "phone": "+41 61 302 24 52",
    "fax": "+41 61 302 24 51",
    "zsr": "N 2462.12",
    "ean": "7601000127808",
    "specialty": "Allgemeinmedizin FMH"
}

This endpoint allows to get a physician by ZSR number

HTTP Request

GET https://ehealth.pharmedsolutions.ch/api/v1.0/physician/<zsr>/get

Query Parameters

Parameter Type Description Required
zsr string ZSR number of the physician, pattern: ^([A-Z]{1})([0-9]{6})$

Response 200

Parameter Type Description Optional
physician int resource ID of the physician
firstName int
lastName string
salutation string
title string
street string
zip string
city string
phone string
fax string
zsr string
ean string
specialty string specialized area of physician

Error 4xx

Status Error Description
404 not.found No physician associated with this zsr

Responses

Get a response

Request:



$curl = curl_init(https://ehealth.pharmedsolutions.ch/api/v1.0/responses/123/get);

# Authentication
curl_setopt($curl,CURLOPT_HTTPAUTHH, CURLAUTH_BASIC);
curl_setopt($curl,CURLOPT_USERPWD, 'johndoe:password_to_test');

$result = curl_exec($curl);

curl_close($curl);





curl https://ehealth.pharmedsolutions.ch/api/v1.0/responses/123/get?language=fr
-u "johndoe:password_to_test"

The returend JSON has the following structure:


  {
    "stati": "{...}",
    "explanation": "The patient is not insured at CSS",
    "messages": "[...]",
    "insurance": "{...}",
    "employee": "{...}"
  }

This endpoint allows to get a response

HTTP Request

GET https://ehealth.pharmedsolutions.ch/api/v1.0/responses/<invoice_id>/get

Query Parameters

Parameter Type Description Required
invoice_id int resource ID of the corresponding invoice
language string language for descriptions (default = de)

Response 200

Parameter Type Description Optional
stati ResponseStatus Detailed status of the invoice.
explanation string Explanation in case of rejection
messages ResponseMessage[] List of messages
insurance Insurance Details sending insurance
employee Employee Contact details responsible employee

Error 4xx

Status Error Description
404 not.found No resonse associated with this invoice_id

Errors

Errors are associated with a code and return the following JSON:

{"ERROR":"error.message","DETAIL":"affected.field","message":"Message in German or French"}

Error Code Meaning
400 Bad Request – Some data was not correct
401 Unauthorized – Your credentials are wrong
403 Forbidden – This is action is not allowed with the requesting account
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access a resource with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The resource requested has been removed from our servers
429 Too Many Requests – You hit the request limit
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.
shell php