Einleitung
REST API Endpoint:
- Development: https://api-dev.condent.app
- Production: https://api.condent.app
Authentifizierung
Die folgenden HTTP-Header müssen für die Authentifizierung verwendet werden:
X-CONDENT-API-KEY: API Schlüssel, welcher vom Zahnarzt erstellt und in Ihrer Software gespeichert wirdX-CONDENT-TIMESTAMP: UTC Zeitstempel in MillisekundenX-CONDENT-SIGN: Eine aus den Request-Parametern abgeleitete Signatur
Änderungen: 18.05.26 - Sign V2
X-CONDENT-SIGN generieren (Sign V2)
Um eine Signatur zu generieren, benötigen sie einen SecretKeywelchen Sie von uns erhalten (support@condent.ch).
Die Signatur setzt sich wie folgt zusammen:
signString erstellen (siehe unten)- Diesen
signString mit HMAC SHA256 und demSecretKeysignieren - Diese Signatur zu base64 encoden
Sign String Aufbau (Sign V2)
Der sign String wird wie folgt aufgebaut (alle Teile durch \n getrennt):
apiKey
method (uppercase)
scheme (lowercase)
host (lowercase)
path (lowercase)
querystring (original case)
timestamp
body
Details:
apiKey: Der API-Schlüssel (identisch mitX-CONDENT-API-KEY)method: HTTP-Methode in Grossbuchstaben (GET, POST, PUT, PATCH, DELETE)scheme: Protokoll in Kleinbuchstaben (https, http)host: Domain in Kleinbuchstaben (api.condent.app)path: Pfad in Kleinbuchstaben (/v1/order, /v2/billing/event)querystring: Query-Parameter in Original-Schreibweise inkl.?(?limit=50 oder leer bei keinen Parametern)timestamp: Der Unix-Timestamp in Millisekunden (identisch mitX-CONDENT-TIMESTAMP)body: Request Body als String (leer bei GET-Requests, Dateiname bei File-Uploads)
Scheme, host und path müssen in Kleinbuchstaben sein! Method ist in Grossbuchstaben. Querystring bleibt in Original-Schreibweise.
Auch leere Strings (z.B. bei fehlendem querystring oder body) müssen im sign String enthalten sein.
Beispiele für Sign String (Sign V2)
POST Request mit JSON Body:
POST https://api.condent.app/v1/Order
API Key: YOUR_API_KEY
Body: {"patient":{"firstName":"Max","lastName":"Muster"}}
Timestamp: 1735034400000
sign:
YOUR_API_KEY
POST
https
api.condent.app
/v1/order
1735034400000
{"patient":{"firstName":"Max","lastName":"Muster"}}
GET Request ohne Body:
GET https://api.condent.app/v2/Billing/Event?limit=50
API Key: YOUR_API_KEY
Timestamp: 1735034400000
sign:
YOUR_API_KEY
GET
https
api.condent.app
/v2/billing/event
?limit=50
1735034400000
(Beachten Sie die leere Zeile am Ende für den leeren Body)
GET Request mit Cursor:
GET https://api.condent.app/v2/Billing/Event?cursor=abc123%3D%3D&limit=50
API Key: YOUR_API_KEY
Timestamp: 1735034400000
sign:
YOUR_API_KEY
GET
https
api.condent.app
/v2/billing/event
?cursor=abc123%3D%3D&limit=50
1735034400000
PUT Request mit File Upload:
PUT https://api.condent.app/v1/Order/abc123/Upload
API Key: YOUR_API_KEY
Filename: scan.stl
Timestamp: 1735034400000
sign:
YOUR_API_KEY
PUT
https
api.condent.app
/v1/order/abc123/upload
1735034400000
scan.stl
Weitere Beispiele finden sie unter examples.
Wichtig ist, dass timestampnicht weniger oder mehr als 15 Sekunden Unterschied zur Serverzeit von Condent hat. Falls Ihre Software z.B. eine auf dem Windows installierte Software ist, müssen Sie berücksichtigen, dass der Benutzer die Uhrzeit auf dem Computer (fälschlicherweise) ändern kann. Sie können die aktuelle Serverzeit von Condent abfragen.
X-CONDENT-SIGN generieren (Sign V1 - Legacy)
Diese Methode wird nicht mehr empfohlen. Bitte verwenden Sie Sign V2 für alle neuen Implementierungen.
Sign V1 verwendet eine einfachere Signatur-Methode:
- Prehash aus
timestamp+apiKey+bodyerstellen - Diesen Prehash mit HMAC SHA256 und dem
SecretKeysignieren - Diese Signatur zu base64 encoden
timestamp entspricht dem Header X-CONDENT-TIMESTAMP
apiKey entspricht dem Header X-CONDENT-API-KEY
body entspricht dem Request Body z.B. "{ patient: { firstName: 'XXXXX' } }"
Änderungen: 27.02.26
Änderungen am Adressmodell
Aufgrund regulatorischer Anpassungen in der Schweiz wird das Adressmodell auf eine strukturierte Form umgestellt.
Änderungen
patient.address.address1
Wird als deprecated markiert.
Bitte stattdessen die neuen strukturierten Felder verwenden:patient.address.streetNamepatient.address.buildingNumber
patient.address.address2
Wird als obsolet markiert und in einer zukünftigen API-Version entfernt.
Dieses Feld sollte nicht mehr verwendet werden.
Grund
Diese Anpassung erfolgt im Kontext einer regulatorischen Änderung der Swiss Payment Standards.
Für Zahlungsüberweisungen sowie die Generierung von QR-Rechnungen wird künftig eine strukturierte Empfängeradresse benötigt.
Patient mit oder ohne Auftragsdaten an Condent schicken
Eine vollständige Dokumentation der API finden Sie hier: https://api-dev.condent.app/swagger/index.html
HTTP Request
POST /v1/order
Request-Parameter
| Parameter | Pflicht | Typ | Kommentar |
|---|---|---|---|
| title | Nein | string | Der Titel des Auftrags |
| costUnitType | Nein | string | Kostenträger des Auftrags |
| insurances | Nein | string array | Versicherungen des Patienten |
| color | Nein | string | Farbe, z.B. für Krone oder Schiene |
| description | Nein | string | Beschreibung des Auftrags |
| scanSentVia | Nein | string | Scan versendet via. Mögliche Werte: DSCore, ThreeShape, ITero, Shining3D, Medit, StraumannAxs, Other |
| trackingNumber | Nein | string | Trackingnummer (z.B. Post) des Auftrags |
| patient | Ja | object | Patientendaten |
| patient.reference | Ja | string | Eindeutige Patientennummer Ihrer Praxissoftware |
| patient.salutation | Nein | string | Anrede des Patienten. Mögliche Werte siehe unten. |
| patient.firstName | Ja | string | Vorname des Patienten |
| patient.lastName | Ja | string | Nachname des Patienten |
| patient.birthday | Nein | date | Geburtstag des Patienten in UTC (z.B. 1991-01-01T00:00:00Z) |
| patient.email | Nein | string | E-Mail-Adresse des Patienten |
| patient.phoneNumber | Nein | string | Telefonnummer des Patienten. Format: +(CountryCode)(NationalNumber) (z.B. +41761234455) |
| patient.address | Nein | object | Adresse des Patienten |
| patient.address.address1 | Nein | string | ⚠️ Deprecated – bitte streetName + buildingNumber verwenden |
| patient.address.address2 | Nein | string | ❌ Obsolet – wird entfernt |
| patient.address.streetName | Nein | string | Strassenname |
| patient.address.buildingNumber | Nein | string | Hausnummer |
| patient.address.zipCode | Nein | string | PLZ |
| patient.address.city | Nein | string | Ort |
| patient.address.countryCode | Nein | string | Land in Alpha-2 code. Condent unterstützt nicht alle Länder. Falls ein Land gesendet wird, welches wir nicht führen, kann der Patient/Auftrag trotzdem erfasst werden. |
| appointments | Nein | array | Termine |
| appointments.date | Nein | date | Datum und Zeit des Termins in UTC (z.B. 2023-02-22T11:43:00Z) |
| appointments.description | Nein | string | Beschreibung des Termins |
| attachments | Nein | array | Beilagen |
| attachments.upperJaw | Nein | bool | OK |
| attachments.lowerJaw | Nein | bool | UK |
| attachments.description | Nein | string | Beschreibung der Beilage |
Mögliche Werte für patient.salutation
| Wert | Beschreibung |
|---|---|
mr | Herr |
ms | Frau |
mrmeddent | Herr med. dent. |
msmeddent | Frau med. dent. |
dresmeddent | Dres. med. dent. |
mrdrmeddent | Herr Dr. med. dent. |
msdrmeddent | Frau Dr. med. dent. |
mrdrdrmeddent | Herr Dr. Dr. med. dent. |
msdrdrmeddent | Frau Dr. Dr. med. dent. |
mrprofdrmeddent | Herr Prof. Dr. med. dent. |
msprofdrmeddent | Frau Prof. Dr. med. dent. |
mrprofdrdrmeddent | Herr Prof. Dr. Dr. med. dent. |
msprofdrdrmeddent | Frau Prof. Dr. Dr. med. dent. |
Response-Parameter
| Parameter | Typ | Kommentar |
|---|---|---|
| url | string | URL für die Erfassung des Auftrags auf Condent |
| uploadToken | string | Token um Dateien zu hochzuladen |
| warnings | string array | Die Warnungen sind für die Entwickler:innen gedacht. Diese Warnungen weisen z.B. darauf hin, dass die gesendete Telefonnummer im falschen Format ist (z.B. wurde 076 123 44 55 statt +41761234455 gesendet). Der Patient resp. Auftrag kann trotz Warnungen erfasst werden. |
Request Beispiel
POST /v1/order HTTP/1.1
Host: api-dev.condent.app
X-CONDENT-SIGN: XXXXX
X-CONDENT-API-KEY: XXXXX
X-CONDENT-TIMESTAMP: 1672211928338
Content-Type: application/json
{
patient: {
reference: 'XXXXX'
firstName: 'XXXXX'
lastName: 'XXXXX'
}
}
X-CONDENT-SIGN wird aus dem geschickten JSON generiert.
Response Beispiel
{
url: 'https://my-dev.condent.app/xyz',
uploadToken: 'xyz'
warnings: []
}
Dateien hochladen
Sie müssen zuerst eine Order erstellen, um Dateien hochzuladen. Den UploadToken erhalten Sie im Response der Order.
Aktuell gelten folgende Beschränkungen:
- Grösse bis zu maximal 100 MB
- Jegliche Dateiformate werden akzeptiert (JPG, PNG, ZIP, PDF, STL, 3OX, ZIP, …)
(Sofern möglich, werden wir Dateien wie z.B. Bilder komprimieren.)
Dateien müssen einzeln geschickt werden, dies um Timeouts zu verhindern (wenn z.B. sehr viele, sehr grosse Dateien geschickt werden). Wir empfehlen, dass die Requests parallel geschickt werden (ein Beispiel in C# finden Sie hier).
Wenn es sehr viele Dateien sind, kann auch ein ZIP-File geschickt werden.
Grundsätzlich kann der Auftrag auf Condent erfasst werden, auch wenn einzelne Dateien durch einen Fehler nicht übermittelt werden konnten. Der Zahnarzt hat die Möglichkeit, die Dateien auch manuell auf Condent hochzuladen oder zu löschen.
HTTP Request
PUT /v1/order/{UploadToken}/upload
Request Body
Sie müssen die Datei als multipart/form-data schicken.
Request Beispiel
PUT /v1/order/XXXXX/upload HTTP/1.1
Host: api-dev.condent.app
X-CONDENT-SIGN: XXXXX
X-CONDENT-API-KEY: XXXXX
X-CONDENT-TIMESTAMP: 1672211928338
Content-Type: multipart/form-data; boundary=------------------------d74496d66958873e
--------------------------d74496d66958873e
Content-Disposition: form-data; name="file.jpg"; filename="file.jpg"
Content-Type: image/jpeg
Sign V2: Der sign String für X-CONDENT-SIGN wird wie folgt erstellt:
apiKey
PUT
https
api-dev.condent.app
/v1/order/xxxxx/upload
timestamp
file.jpg
(Der Dateiname “file.jpg” ist der Body-Parameter für die Signatur)
Response Beispiel
HTTP/1.1 200 OK
Serverzeit
Eine Authentifizierung ist nicht notwendig.
HTTP Request
GET /v1/time
Request Parameter
Keine
Response Parameter
| Parameter | Typ | Kommentar |
|---|---|---|
| seconds | long | Condent Zeitstempel in Sekunden |
| milliseconds | long | Condent Zeitstempel in Millisekunden |
Request Beispiel
curl https://api-dev.condent.app/v1/time
Response Beispiel
{
seconds: 1677067413,
milliseconds: 1677067413774
}