REST API: POST /users/{id}

Lees eerst de basisinformatie over de REST API.

Bestaande lener updaten

Het toegangspunt POST /users/{id} laat je toe om de gegevens van een bestaande lener te updaten.

URL parameters

• id: Colibris ID van de lener, of het e-mailadres van de lener

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 (expliciet doorgestuurd of anders willekeurig toegekend door het systeem)
• 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 (nogmaals) verstuurd met daarin de login en het wachtwoord van de lener. Als er geen wachtwoord werd meegestuurd, dan zal het systeem een willekeurig wachtwoord toekennen.

Wanneer een bepaalde parameter wordt doorgestuurd met een lege waarde, dan wordt dit veld ook leeggemaakt in de databank. Stuur dus geen onnodige parameters door, enkel de parameters die je effectief wil overschrijven.

Alle doorgestuurde velden moeten geparametriseerd worden met http_build_query() zoals in het voorbeeld onderaan. Enkel de aanwezige velden worden up-to-date gebracht.

Bij het e-mailadres is er een test op typfouten en wordt er gekeken of het e-maildomein bestaat. Indien het e-mailadres ingevuld is, maar geen wachtwoord, dan zal Colibris automatisch een initieel wachtwoord genereren.

JSON resultaat

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

API Voorbeeldcode in PHP

<?php
$curl = curl_init();

$parameters = array(
  'sp1' => 'Klas 3A',
  'pass' => 'abc123',
  'welkomstmail' => 1,
);

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://api.colibris.be/users/000042". 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);
}
?>

Bovenstaande code zal voor de lener met ID 000042 het specifiek veld n°1 overschrijven. Daarnaast zal er een nieuw wachtwoord worden ingesteld (abc123) en wordt de welkomste-mail opnieuw verzonden.

API Voorbeeldantwoord

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

Het wachtwoord zal steeds leeg zijn. Dit wordt nooit weergegeven in het API antwoord.

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