Commit 88433541 authored by Stefan Hörterer's avatar Stefan Hörterer 💬

initial public commit

parents
Dokumentation der LiMS Schnittstelle
====================================
## Allgemeine Informationen
Die LiMS Schnittstelle des DOSB Bildungsnetz ermöglicht Ihnen unter anderem Lizenzdaten aus Ihrem Bestandssystem in das LiMS zu importieren. Außedem können Sie
* neue Lizenzen anfordern,
* vorhandene Lizenzen verlängern und korrigieren,
* PDF Lizenzvordrucke laden
Alle Anfragen müssen an die URL *https://bildungsnetz.dosb.de/api/lims* gestellt werden. Bitte beachten Sie, dass es sich hier um produktive Daten handelt. Darum testen sie Ihre Implementierung am besten zunächst auf unserer Testumgebung.
In der aktuellen Version 1.0 erfolgen die Anfragen via **REST**. *SOAP*, *WSDL* und *XML-RPC* können unter Umständen nachträglich bereitgestellt werden.
## Testumgebung und API Zugriff
In der Testumgebung haben Sie Zugriff auf alle Lizenzdaten Ihrer Organisation und können diese verändern, ohne dass die produktiven Datenbestände davon betroffen sind. Wenn sie Zugriff auf die API und auf unsere Demo Umgebung (Sandbox) benötigen, kontaktieren sie uns einfach über die Supportformular des Bildungsnetzes.
## Request Header und Authentifizierung
Die LiMS Schnittstelle verwendet eine HTTP-Authentifizierung, jede Anfrage muss mit einer Kombination aus "benutzername:passwort" ausgestattet sein. Diese Kombination muss base64 encodiert sein. Sessions/Cookies werden nicht unterstützt.
Bsp.
```
Authorization: Basic RXMgaGVpw590IE51a3VsYXIh
```
Zudem können Sie angeben, ob json oder xml geladen werden soll. Für den PDF download verwenden Sie application/pdf oder einfach */*
```
Accept application/json
Accept application/xml
Accept application/pdf
```
Falls die Authentifizierung fehlschlägt, werden folgende Status Codes zurückgeliefert:
```
400 Bad Request : Benutzername/Passwort sind falsch
403 Forbidden : Ihre Benutzerdaten sind korrekt, Sie wurden jedoch nicht für den API Zugriff freigeschaltet
```
## Dienste ##
### Lizenz anfordern ###
----
Aufruf zum Erstellen oder Aktualisieren einer Lizenz.
**URL**
/request
**Method:**
`POST`
**URL Params**
Keine
**Data Params für Neue Lizenzen**
**Required:**
Alle nicht mit * markierte Felder aus der Felddefinitionsliste
**Optional:**
Alle mit * markierte Felder aus der Felddefinitionsliste
Das Feld first_issue_date kann gesetzt werden, falls es sich um Bestandsdaten handelt.
Ansonsten wird hierfür der selbe Wert wie für issue_date verwendet.
**Invalid:**
Folgende Felder können nicht gesetzt werden, wenn eine neue Lizenz erstellt werden soll
`license_number_dosb` oder `lid`
**Data Params für vorhandene Lizenzen**
**Required:**
Eine der beiden IDs muss angegeben werden
`license_number_dosb` oder `lid`
**Optional:**
Alle Felder aus der Felddefinitionsliste, bzw. nur die Felder, die geändert werden sollen.
**Invalid:**
Folgende Felder können nicht gesetzt werden, wenn eine neue Lizenz erstellt werden soll
`organisation_id`
`first_issue_date`
**Success Response:**
Bei Erfolg werden sowohl dei interne LiMS-ID (lid) als auch die DOSB-Lizenznummer (license_number_dosb) zurückgegeben
**Code:** 200 <br />
**Content:** `{ lid : 12, license_number_dosb: AB-CD-E-xxxxxxxxxx }`
**Error Response:**
**Code:** 401 UNAUTHORIZED <br />
**Content:** `[ Invalid login credentials ]`
**Code:** 403 ACCESS DENIED <br />
**Content:** `[ Permission denied for organisation %og_nid ]`
**Code:** 406 Not Acceptable <br />
**Content:** `[ Missing %fieldname ]`
**Code:** 406 Not Acceptable <br />
**Content:** `[ License number invalid or license not found ]`
**Code:** 406 Not Acceptable <br />
**Content:** `[ Training course id is not valid in this organisation ]`
**Code:** 422 UNPROCESSABLE ENTRY <br />
**Content:** `[ Invalid input for %key: %val ]`
**Notes:**
### Lizenzenvordruck laden mit DOSB Lizenznummer ###
----
Aufruf laden einer Lizenz im DinA4 Format andhand der DOSB Lizenznummer
**URL**
/download
**Method:**
`POST`
**URL Params**
`license_number_dosb`
**Data Params für vorhandene Lizenzen**
**Required:**
keine
**Optional:**
`fomat`
**Success Response:**
Bei Erfolg wird der Inhalt der PDF Zurückgegeben
**Code:** 200 <br />
**Content-Type:** application/pdf <br />
**Content:** Inhalt der pdf
**Error Response:**
**Code:** 401 UNAUTHORIZED <br />
**Content:** `[ Invalid login credentials ]`
**Code:** 403 ACCESS DENIED <br />
**Content:** `["Access denied for user %username ]`
**Notes:**
## Felddefinitionen
Diese Felder können beim Erstellen von Lizenzen ausgefüllt werden.
Bitte beachten Sie, dass die Felder vom Typ "Date" als Unixzeit, also dem POSIX-Standard entsprechend (z.B. 497274993), übergeben werden müssen.
| Feld | Beschreibung | Typ | input / min, max |
|---|---|---|---|
| firstname | Vorname | string | 1,255 |
| lastname | Nachname | string | 1,255|
| academic_title | Titel | string | 1,255 |
| birthdate | Geburtsdatum | date | -, NOW |
| gender | Geschlecht | string | w,m,u |
| street | Straße | string | 1,255 |
| postal | PLZ | string | 5 |
| city | Ort | string | 1,255 |
| mail* | E-Mail | string | 1,255 |
| phone* | Telefon | string | 1,255 |
| issue_date | Ausstellungsdatum | date | -, NOW |
| first_issue_date* | Erstausstellungsdatum | date | -, NOW |
| training_course_id | Ausbildungsgang | int | |
| issue_place | Ausstellungsort | string | 1,255 |
| valid_until | Gültig bis | date | NOW, NOW +5 |
| honor_code | Ehrencodex | int | 1,0 |
| honor_code_date | Ehrencodex Datum | date | -, NOW |
| first_aid | Erste-Hilfe-Ausbildung | int | 1,0 |
| first_aid_date | Erste-Hilfe-Ausbildung Datum | date | -, NOW |
| license_number_organisation | Lizenznummer(Verband) | string | 1,255 |
| prequalification_type* | Vorqualifikationsart | string | 1,255 |
| prequalification_number** | DOSB-Lizenznummer Vorqualifikation | string | 1,255 |
| organisation_id | Auszustellender Verband | int | 0,- |
| lid | LiMS ID | int | 0,- |
| license_number_dosb | DOSB-Lizenznummer | string | 1,255 |
| custom_1* | Zusatzfeld 1 | string | 0,1024 |
| custom_2* | Zusatzfeld 2 | string | 0,1024 |
\* Felder mit sind optional.
** Muss eine gültige DOSB-Lizenznummer sein
\ No newline at end of file
<?php
/**
* @file Einfacher CURL-PHP client zum testen der LiMS Schnittstelle
*
* Created by PhpStorm.
* User: Stefan Hörterer for Ghostthinker GmbH
* Date: 17.09.2015
* Time: 09:14
*/
$host = isset($_POST['host'])? $_POST['host'] : 'https://bildungsnetz.dosb.de/api/lims/request';
$username = isset($_POST['username'])? $_POST['username'] : "";
$password = isset($_POST['password'])? $_POST['password'] : "";
$training_course_id = 932;
//zusammenbauen der Parameter
if(isset($_POST['data'])) {
$new_license_data = array();
$d = explode("\n", $_POST['data']);
foreach($d as $e){
$ps = explode('=>', $e);
if(!empty($ps[0])) {
$new_license_data[trim($ps[0])] = trim($ps[1]);
}
}
$data = $_POST['data'];
}else {
$new_license_data = array(
'postal' => 42431,
'organisation_id' => '',
'mail' => 'test@example.com',
'training_course_id' => '',
'firstname' => 'demo',
'lastname' => 'user',
'birthdate' => strtotime("NOW - 30 years"),
'gender' => 'w',
'street' => '123 fakestreet',
'city' => 'Hamburg',
'valid_until' => strtotime("NOW + 15 years"),
'issue_date' => time(),
'issue_place' => 'Hamburg',
'honor_code' => 1,
'honor_code_date' => strtotime('NOW - 2years'),
'first_aid' => 0,
'first_aid_date' => NULL,
);
$data = "";
foreach ($new_license_data as $k => $v) {
$data .= "$k => $v \n";
}
}
if(!empty($_POST)) {
$additionalHeaders = '';
$process = curl_init($host);
//hier ist auch noch application/xml möglich
curl_setopt($process, CURLOPT_HTTPHEADER, array(
'Accept: application/json',
$additionalHeaders
));
curl_setopt($process, CURLOPT_HEADER, 1);
curl_setopt($process, CURLOPT_USERPWD, $username . ":" . $password);
curl_setopt($process, CURLOPT_TIMEOUT, 30);
curl_setopt($process, CURLOPT_POST, 1);
curl_setopt($process, CURLOPT_POSTFIELDS, $new_license_data);
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
//nur für test zwecke
curl_setopt($process, CURLOPT_SSL_VERIFYPEER, FALSE);
//request ausführen
$response = curl_exec($process);
$errors = NULL;
if (curl_errno($process)) {
$errors= 'Curl error: ' . curl_error($process);
}
$header_size = curl_getinfo($process, CURLINFO_HEADER_SIZE);
$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);//json_decode(substr($response, $header_size));
}else{
$body = $header = $errors = "no reponse sent yet";
}
?>
<style>
input[type="text"], textarea {
width: 500px;
}
label {
display: block;
}
</style>
<form method="post">
<h1>Request form</h1>
<label for="host">Host and service</label>
<input type='text' name="host" value="<?php print $host ?>"/>
<label for="username">Username</label>
<input type='text' name="username" value="<?php print $username ?>"/>
<label for="password">Password</label>
<input type='text' name="password" value="<?php print $password ?>"/>
<label for="data">Data</label>
<textarea type='text' name="data" rows="20"><?php print $data ?></textarea>
<br/>
<input type="submit" value="send request"/>
</form>
<h1>Reponse header</h1>
<pre>
<?php print $header; ?>
</pre>
<h1>Reponse body</h1>
<pre>
<?php print_r($body) ?>
</pre>
<h1>CURL Errors</h1>
<pre>
<?php print $errors ?>
</pre>
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment