De API-koppeling van PolderSoft Ledenadministratie maakt het mogelijk om gegevens naadloos te synchroniseren tussen de PolderSoft-ledenadministratiesoftware en externe systemen.
Hieronder wordt beschreven hoe de koppeling functioneert en welke stappen nodig zijn om ermee te werken.
Hoe werkt de API-koppeling?
Authenticatie:
De API maakt gebruik van token-based authenticatie. Dit betekent dat je een unieke API-sleutel (API-key) nodig hebt die je moet opvragen via je PolderSoft-account.
Bij elke API-aanroep moet je de API-sleutel meesturen in de header van het verzoek (
Authorization: Bearer <api-key>).
Eindpunten (Endpoints):
De API biedt verschillende eindpunten om specifieke acties uit te voeren, zoals:
Ledenbeheer: Toevoegen, bewerken, of verwijderen van leden.
Contributie: Ophalen of wijzigen van contributiegegevens.
Betalingen: Registreren en verwerken van betalingen.
Rapportage: Genereren en downloaden van rapportages.
Elk eindpunt heeft een specifieke URL, bijvoorbeeld:
POST https://leden.poldersoft.nl/AwareIM/REST/<klant>/InsertPersoon
Verzoekstructuur (Requests):
Alle verzoeken worden ingediend via HTTP-methoden, zoals:
GET: Voor het ophalen van gegevens (bijv. lidinformatie).
POST: Voor het aanmaken van nieuwe gegevens (bijv. nieuw lid registreren).
PUT: Voor het bijwerken van bestaande gegevens (bijv. lidinformatie updaten).
DELETE: Voor het verwijderen van gegevens.
De verzoeken moeten een JSON-formaat hebben voor invoer en uitvoer.
Reactie (Responses):
Na elke API-aanroep ontvang je een antwoord in JSON-formaat.
Voorbeelden van responses :
{
"status": "success",
"message": "Lid succesvol toegevoegd",
"data": {
"id": 123,
"naam": "Jan Jansen",
"email": "jan.jansen@example.com"
}
}
{
"status": "error",
"message": "Onvoldoende rechten",
"code": 403
}
InsertPersoon : Toevoegen van een lid
https://leden.poldersoft.nl/AwareIM/REST/<Klant>/InsertPersoon
Headers
POST /AwareIM/REST/<Klant>/InsertPersoon HTTP/1.1
Host: leden.poldersoft.nl
Authorization: Bearer eyJhbG…
Content-Type: application/json
body :
{
"Token": "eyJhbG…",
"Naam": "Steensma",
"Voornaam": "Jordy",
"Straat": "Hazepad",
"Bedrag": "25",
"HuisNr": "4",
"Postcode": "3456AB",
"Plaats": "Alhier",
"Gemeente": "Laarbeek",
"Provincie": "Noord-Brabant",
"DatumGeb": "11-11-2002",
"TelNr": "0618335621",
"EmailAddress": "jordysteensma@gmail.com",
"Nummer1": "123456",
"Voorletters": "J",
"Aanhef": "Dhr.",
"Betaalwijze": "ideal"
}
Het resultaat is bv :
{
"LidNr": 900016,
"Wachtwoord": "j4cn9PY3",
"HTTP": "200",
"LoginNaam": "test56@gmail.com"
}GetPersoon : Lezen / ophalen van 1 lid
Een lid kan gezocht worden door op lidnr te zoeken.
GET https://leden.poldersoft.nl/AwareIM/REST/<klant>/GetPersoon
Headers
POST /AwareIM/REST/<klant>/GetPersoon HTTP/1.1
Host: leden.poldersoft.nl
Authorization: Bearer eyJhbG…
Content-Type: application/jsonBody
{
"Token": "eyJhbG……….",
"LidNr": "2200016"
}Het is ook mogelijk om te zoeken op zowel lidnr als emailadres :
{
"Token": "eyJhbG……….",
"LidNr": "2200016",
"EmailAddress": "jordysteensma@gmail.com"
}Het resultaat is bv :
{
"LidNr": 220016,
"Naam": "Lammers",
"Voornaam": "Rob",
"Voorletters": "R.G",
"Straat": "Boogsingel",
"HuisNr": "12",
"Postcode": "1234 AB",
"Plaats": "Zoetermeer",
"Gemeente": "Zoetermeer",
"Provincie": "Zuid-Holland",
"Land": "Nederland",
"EmailAddress": "rob.lammers@test.nl",
"BankRekNr": "NL46INGB0123456789",
"Geslacht": "Man",
"TelNr": "06123454234",
"Bedrag": 12.00,
"Persoonsvorm": "Natuurlijk",
"DatumGeb": "23-08-1975",
"Vlag1": "No",
"Vlag2": "No",
"Vlag3": "No",
"Vlag4": "No",
"Vlag5": "No",
"Vlag6": "No",
"Vlag7": "No",
"Vlag8": "No",
"Vlag9": "No",
"Vlag10": "No",
"Vlag11": "No",
"Vlag12": "No",
"Vlag13": "No",
"Vlag14": "No",
"Vlag15": "No",
"Vlag16": "No",
"MailingList": "No",
"SoortLid": "Lid",
"VrijVeld1": "Factuur",
"VrijVeld2": "nl",
}
Als het lidnr (+ eventueel emailadres) niet gevonden kan worden dan volgt:
{
"Message": "LidNr niet gevonden",
"LidNr": 2613
}Opmerkingen
HTTP-Method: Hoewel het endpoint
GetPersoonwordt genoemd, gebruikt het hier een POST-verzoek (meestal vanwege het versturen van een body).Token: Zorg ervoor dat je het juiste token gebruikt om toegang te krijgen.
Foutmeldingen: Bij fouten kun je een JSON-object ontvangen
CheckEmail : Controleer of ingelogged kan worden met het emailadres
Hier een voorbeeld van hoe je een e-mailadres kunt controleren met behulp van het endpoint
https://leden.poldersoft.nl/AwareIM/REST/<klant>/CheckEmailHeaders
POST /AwareIM/REST/<klant>/CheckEmail HTTP/1.1
Host: leden.poldersoft.nl
Authorization: Bearer eyJhbG……..
Content-Type: application/json
Body
{
"Token": "eyJhbG……..",
"EmailAddress": "johandewit@testgmail.com"
}
Response email niet gevonden
{
"Message": "Email niet gevonden",
"EmailAddress": "johandewit@testgmail.com"
}
Response email wel gevonden
{
"Message": "Email gevonden",
"EmailAddress": "johandewit@testgmail.com",
"LidNr": 123456
}
UpdatePersoon : Wijzigen van een lid
Hier is een voorbeeld van hoe je een lid kunt wijzigen via het UpdatePersoon-endpoint van de API
https://leden.poldersoft.nl/AwareIM/REST/<klant>/UpdatePersoon
URL
https://leden.poldersoft.nl/AwareIM/REST/<klant>/UpdatePersoon
Headers
POST /AwareIM/REST/<klant>/UpdatePersoon HTTP/1.1
Host: leden.poldersoft.nl
Authorization: Bearer eyJhbG
Content-Type: application/json
Body
{
"Token": "eyJhbG",
"LidNr": "38559",
"Naam": "Hofman",
"Vlag4": "Yes"
}
Voorbeeld Response
Succesvolle Wijziging
{
"Message": "Lid succesvol bijgewerkt",
"LidNr": "38559",
"Naam": "Hofman",
"Vlag4": "Yes",
"HTTP": 200
}
Foutmeldingen
Lidnummer Niet Gevonden
{
"error": "Not Found",
"message": "Lidnummer 38559 niet gevonden.",
"HTTP": 404
}
Authenticatie
Het instellen van de Base URL en Token die in ieder API-request moeten worden opgenomen voor authenticatie.
Hoe Authenticatie Werkt
Base URL:
Dit is de hoofd-URL waar alle API-eindpunten van de applicatie beschikbaar zijn. In dit geval
Token:
Het token wordt gebruikt voor authenticatie en moet in elke aanvraag in de body worden opgenomen.
Dit token kan handmatig worden ingevuld in de applicatie, zoals in het tekstveld op de afbeelding.