Hoe kan ik de API instellen voor mijn gebruikers?

Wat vind je in dit artikel?

• Samenvatting: De basisstappen om de API-functionaliteit toegankelijk te maken.

• Voorwaarden en doelgroep: Wie de API kan activeren en instellen.

• API instellen en activeren: Hoe de (sub)beheerder de functie aanzet voor de vestiging en gebruikers.

• API-sleutel genereren: De stap voor de individuele gebruiker om een persoonlijke sleutel te verkrijgen.

• Authenticatie en aanroepen: Technische instructies voor het opvragen van tokens en data.

Samenvatting

Het instellen van de API verloopt via de (sub)beheerder, die de functie per vestiging en per gebruiker activeert. Vervolgens genereert de gebruiker een API-sleutel om via een beveiligd token toegang te krijgen tot de verschillende 12Build-functies.

Voorwaarden en doelgroep

Dit artikel is geschreven voor (sub)beheerders die de API willen uitrollen en voor IT-teams die de koppeling technisch realiseren. Zorg dat je organisatie beschikt over een abonnement dat API-toegang ondersteunt (Enterprise).

API instellen en activeren

Voordat een gebruiker aan de slag kan, moet de beheerder de juiste rechten toekennen.

1. Vestigingsinstellingen: Een (sub)beheerder dient allereerst de API-mogelijkheid voor de betreffende vestiging aan te zetten. 
   

2. Gebruikersactivatie: Activeer daarna de API-functionaliteit specifiek per gebruiker die hier gebruik van gaat maken. 
   

API-sleutel genereren

Zodra de functie is geactiveerd door de beheerder, kan de gebruiker zelf zijn unieke sleutel aanmaken.

1. Ga naar Mijn account.

2. Navigeer naar het tabblad API.

3. Klik op de knop om een nieuwe API key te genereren. 
   

Authenticatie en aanroepen

De gegenereerde sleutel wordt gebruikt om een tijdelijk toegangstoken op te vragen.

1. Token opvragen: Stuur een POST-request met je gebruikersnaam en API-sleutel naar het token-endpoint.

2. Geldigheid: Het verkregen token is precies één uur geldig.

3. Autorisatie: Stuur bij elke volgende functie-aanroep het token mee in de header als: X-Auth-Token: [jouw_token].

4. Content-Type: Gebruik bij JSON-requests altijd de header Content-Type: application/json.

Technische parameters

• Template-parameters: Verwerk deze als GET-parameters in de URL.

• Query-parameters: Stuur deze mee als POST-parameters.

Postman

Om snel van start te kunnen met de API zie hier het Postman bestand.

Veelgestelde vragen (FAQ)

Vraag: Hoe lang is mijn API-sleutel geldig? Antwoord: De API-sleutel zelf blijft geldig totdat je deze handmatig intrekt of vervangt. Echter, het token dat je ermee opvraagt voor acties is slechts 60 minuten geldig.

Vraag: Waar vind ik de technische documentatie van alle API-functies? Antwoord: De volledige lijst met parameters, functies en responses is beschikbaar via de specifieke documentatiepagina van 12Build. Je kunt ook het Postman-bestand gebruiken om direct te testen.

Probleemoplossing

• Symptoom -> Ik krijg een foutmelding bij het aanroepen van een functie.

  • Oorzaak -> Het token is waarschijnlijk verlopen of de header X-Auth-Token ontbreekt.

  • Oplossing -> Vraag een nieuw token aan met je API-sleutel en controleer of dit token correct wordt meegestuurd in de header.

• Symptoom -> De API-data wordt niet herkend.

  • Oorzaak -> De Content-Type header is niet ingesteld op application/json.

  • Oplossing -> Voeg de juiste Content-Type header toe aan je request, anders wordt er uitgegaan van multipart/form-data.