README.md 6.58 KB
Newer Older
Stefan Hörterer's avatar
Stefan Hörterer committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
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

Johannes Metscher's avatar
Johannes Metscher committed
18
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. Zum ausprobieren der Schnittstelle können Sie dieses Testformular unter *https://lims_connect.ghostthinker.de* nutzen.
Stefan Hörterer's avatar
Stefan Hörterer committed
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170


## 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:** 
171 172 173 174
 
## Sequenz Diagramm
 
![alt text](doc/sequence_diagram.jpg "Sequenz Diagramm")
Stefan Hörterer's avatar
Stefan Hörterer committed
175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213

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