REST API: POST /users

Lees eerst de basisinformatie over de REST API.

Nieuwe lener toevoegen

Het toegangspunt POST /users laat je toe om een nieuwe lenersaccount aan te maken.

URL parameters

Je kunt volgende velden meesturen met een API call:

• naam (verplicht)
• voornaam (verplicht)
• email: primair e-mailadres (moet uniek zijn)
• email_melding: secundair e-mailadres voor meldingen (moet niet uniek zijn)
• pass: wachtwoord (hetzij meegegeven als parameter, hetzij willekeurig toegekend door het systeeem)
• taal: nl, fr of en
• sp1: specifiek veld n°1 (bv. alternatieve lenersbarcode)
• sp2: specifiek veld n°2
• externe_id: unieke ID waarmee een synchronisatie mogelijk is met andere systemen
• groep: lenersgroep(en), omsloten en gescheiden door |
• notitie: onzichtbare opmerking
• welkomstmail: indien 1, dan wordt de welkomste-mail verstuurd met daarin de login en het wachtwoord van de lener

Alle doorgestuurde velden moeten geparametriseerd worden met http_build_query() zoals in het voorbeeld onderaan.

Opmerkingen bij bepaalde velden

Bij de beide e-mailadressen is er een test op typfouten en wordt er gekeken of het e-maildomein bestaat. Er wordt ook gekeken of het primaire e-mailadres uniek is. Wanneer er een probleem is, wordt foutcode 406 geantwoord.

Je kunt zelf een initieel wachtwoord sturen. Indien het e-mailadres is ingevuld, maar er wordt géén wachtwoord gestuurd, dan zal Colibris automatisch een initieel wachtwoord genereren, ook al kies je er niet voor om een welkomstmail (met daarin het wachtwoord) te versturen naar de lener.

Indien het veld ’taal’ leeg is, wordt de standaardtaal uit de instellingen van Colibris ingevuld.

JSON resultaat

• code: HTTP response code (bv. 200 voor een correct resultaat)
• response: alle gegevens van de lener ter bevestiging

API Voorbeeldcode in PHP

<?php
$curl = curl_init();

$parameters = array(
  'naam' => 'Claus',
  'voornaam' => 'Hugo',
  'email' => 'hugo@claus.be',
  'pass' => 'abc123',
  'welkomstmail' => 1,
);

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://api.colibris.be/users?". http_build_query($parameters),
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => array(
	'X-Api-User: API_USER',
	'X-Api-Login: API_LOGIN',
	'X-Api-Key: API_KEY',
	'Content-Type: application/json'
    ),
));

$data = curl_exec($curl);
$http_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$err = curl_error($curl);
curl_close($curl);

if ($err) {
    echo "Error #:" . $err;
} else {
    print_r($data);
}
?>

API Voorbeeldantwoord

{
    "code": "200",
    "response": [
        {
            "id": "000002",
            "naam": "Claus",
            "voornaam": "Hugo",
            "email": "hugo@claus.be",
            "email_melding": "",
            "pass": "",
            "taal": "",
            "sp1": "",
            "sp2": "",
            "externe_id": "",
            "groep": "",
            "notitie": ""
        }
    ]
}

Het wachtwoord zal steeds leeg zijn in het antwoord. Dit wordt nooit opnieuw getoond.

Meer informatie over de verschillende velden vind je in het artikel over het importeren van leners.