De Stamhoofd API gebruiken
Je kan gratis gebruik maken van de Stamhoofd API als je zelf wat kennis hebt van API's. We geven enkel ondersteuning via email voor zaken die specifiek zijn voor Stamhoofd, voor andere zaken in verband met het werken met API's kan je op internet te rade gaan.
Toegang krijgen
Je kan een API-key opvragen via de Stamhoofd instellingen (Instellingen > Experimenten > API-keys). Met deze API-key kan je de API raadplegen.
We raden aan om altijd een nieuwe key aan te maken per toepassing die je wilt gebruiken. Daardoor kan je netjes de toegang van de API afschermen door de toegangsrechten van de gekoppelde keys aan te passen, bv. tot enkel het gedeelte van betalingen.
Basisprincipes
Structuur voor algemene endpoints: https://api.stamhoofd.app/v191/organizations/search?query=sd
Structuur voor endpoints specifiek voor één vereniging:https://634d549b-862e-4a5e-852d-3d4a9814e22d.api.stamhoofd.app/v191/webshop/d6b9ed68-3a1f-4dd5-8259-62d0d808f597
Hier zie je dat elke vereniging een andere API aanspreekt op het subdomein van api.stamhoofd.app, met als subdomein het ID van de vereniging.
Versiebeheer
De versie van de API die je aanspreekt zit in de endpoints. Bij elke wijziging aan de API gaat dit nummer omhoog. Oude versies blijven nog even ondersteund, maar we bieden momenteel geen garantie dat we oude versies voor een bepaalde tijd blijven ondersteunen. Soms is het noodzakelijk in verband met interne wijzigingen dat we een update moeten doorvoeren die niet meer compatibel is, waardoor alle oude versies niet langer ondersteund worden.
Gebruik de webinspector
Je kan alle API endpoints gebruiken, hoewel we ze nog niet allemaal gaan documenteren. Je kan altijd de webinspector gebruiken in je browser en via stamhoofd.app het netwerkverkeer bekijken om te weten hoe je bepaalde zaken kan doen. De API die de app aanspreekt is namelijk dezelfde API die je ook kan gebruiken.
Authenticatie
Hiervoor kan je de Authorization header toe met als waarde Authorization: Bearer <jouw API-key>. Authenticatie is bij de meeste endpoints noodzakelijk.
Rate limits: Wees zuinig met je requests
Spreek de API niet aan als dat niet nodig is. Beperk het aantal requests tot een absoluut minimum. Er staan limieten op het aantal aanvragen die je kan versturen:
- 5 req/s, maximaal aangehouden gedurende 5s
- 1 req/s, maximaal aangehouden gedurende 150s
- 1000 req/uur
- 2000 req/dag
Zorg er dus best voor dat je niet alle aanvragen tegelijk verstuurd, meestal is dat ook niet nodig. Heeft jouw toepassing toch hogere limieten nodig? Leg dan goed uit waarom het niet met de huidige limieten lukt, en stuur ons een e-mail.
Voorbeeld 1: openstaande betalingen opvragen
GET https://634d549b-862e-4a5e-852d-3d4a9814e22d.api.stamhoofd.app/v191/organization/payments
Antwoord:
[{
"transferSettings": {
"creditor": null,
"iban": null,
"prefix": "Bestelling wijn/gin",
"type": "Reference"
},
"provider": null,
"method": "Transfer",
"freeContribution": null,
"settlement": null,
"ibanName": null,
"iban": null,
"balanceItemPayments": [{
"balanceItem": {
"order": {
"webshopId": "7b952ab3-60c7-4d59-bb40-5b10cd9a1a51",
"status": "Created",
"updatedAt": 1684575959000,
"validAt": 1643743617000,
"createdAt": 1643743617000,
"payment": null,
"data": {
"comments": "",
"paymentMethod": "Transfer",
"reservedOrder": true,
"reservedPersons": 0,
"consumerLanguage": "nl",
"fieldAnswers": [],
"customer": {
"phone": "+32 479 42 78 66",
"email": "simon@stamhoofd.nl",
"lastName": "Backx",
"firstName": "Simon"
},
"cart": {
"items": [{
"reservedAmount": 6,
"unitPrice": 1800,
"id": "59d2f7ce-0d33-45b2-a01b-1e60367a3c66",
"fieldAnswers": [],
"amount": 6,
"options": [],
"productPrice": {
"discountAmount": 2,
"discountPrice": null,
"price": 1800,
"name": "Doos met 6",
"id": "60d5352e-b5ca-4f1a-97b9-19f924581009"
},
"product": {
"unique": false,
"allowMultiple": true,
"disableAfter": null,
"enableAfter": null,
"hidden": false,
"maxPerOrder": null,
"dateRange": null,
"location": null,
"customFields": [],
"optionMenus": [],
"prices": [{
"discountAmount": 2,
"discountPrice": null,
"price": 1500,
"name": "Doos met 9 flessen",
"id": "45eb4ced-b2c3-42a0-92fe-68cea6756189"
}, {
"discountAmount": 2,
"discountPrice": null,
"price": 1800,
"name": "Doos met 6",
"id": "60d5352e-b5ca-4f1a-97b9-19f924581009"
}],
"usedStock": 6,
"stock": null,
"askName": false,
"type": "Product",
"images": [{
"resolutions": [{
"file": {
"id": "f5d28c3b-afd9-46b9-8bb0-ca65a7622f6f",
"server": "https://stamhoofd.ams3.digitaloceanspaces.com",
"path": "production/6b9a3d33-458b-44f0-aedb-446118a73462/f5d28c3b-afd9-46b9-8bb0-ca65a7622f6f.jpg",
"size": 42614,
"name": null
},
"width": 750,
"height": 500
}, {
"file": {
"id": "db56f90f-bf1b-4ce0-b7f5-2c3431eaba4f",
"server": "https://stamhoofd.ams3.digitaloceanspaces.com",
"path": "production/6b9a3d33-458b-44f0-aedb-446118a73462/db56f90f-bf1b-4ce0-b7f5-2c3431eaba4f.jpg",
"size": 11067,
"name": null
},
"width": 250,
"height": 250
}],
"source": {
"id": "deff27ff-c515-4b08-9e69-1b3d13a74531",
"server": "https://stamhoofd.ams3.digitaloceanspaces.com",
"path": "production/6b9a3d33-458b-44f0-aedb-446118a73462/deff27ff-c515-4b08-9e69-1b3d13a74531.jpg",
"size": 1585121,
"name": null
},
"id": "6b9a3d33-458b-44f0-aedb-446118a73462"
}],
"enabled": true,
"description": "Dit is een beschrijving.",
"name": "Sauvignon",
"id": "af054b10-4dd7-49b3-a94f-e3f2a3eb8bac"
}
}]
},
"recordAnswers": [],
"address": null,
"checkoutMethod": {
"address": {
"country": "BE",
"city": "Mars",
"postalCode": "974E5A",
"number": "845E43",
"street": "Andromedanevel"
},
"type": "Takeout",
"timeSlots": {
"timeSlots": [{
"usedPersons": 0,
"maxPersons": null,
"usedOrders": 0,
"maxOrders": 10,
"endTime": 720,
"startTime": 540,
"date": 1645384860000,
"id": "976f5a4f-b43c-4d62-8e4d-a216e3bb5cf5"
}, {
"usedPersons": 0,
"maxPersons": null,
"usedOrders": 1,
"maxOrders": 10,
"endTime": 840,
"startTime": 720,
"date": 1645384920000,
"id": "a87f0fed-093e-4ece-a83a-11fba8354444"
}]
},
"description": "",
"name": "Testlocatie",
"id": "b826fc1c-d4d2-450d-8e35-5bcdc078981d"
},
"timeSlot": {
"usedPersons": 0,
"maxPersons": null,
"usedOrders": 1,
"maxOrders": 10,
"endTime": 840,
"startTime": 720,
"date": 1645384920000,
"id": "a87f0fed-093e-4ece-a83a-11fba8354444"
}
},
"number": 1,
"id": "4a656a99-6898-4302-8ac4-72bd5cc31613"
},
"member": null,
"registration": null,
"status": "Pending",
"createdAt": 1643743617000,
"pricePaid": 0,
"price": 10800,
"description": "Bestelling #1 - Eindejaarsverkoop wijn/gin",
"id": "e52f43fd-b275-464b-bece-9e8885909c3c"
},
"price": 10800,
"id": "cdc6c338-ef22-4a93-81a2-3026f6941051"
}],
"updatedAt": 1684575959000,
"createdAt": 1643743617000,
"paidAt": null,
"transferDescription": "+++710/1720/60345+++",
"price": 10800,
"status": "Created",
"id": "9274bb7a-f738-4560-a833-c7b553f15717"
}, {
"transferSettings": {
"creditor": "De Ruimtevaarders",
"iban": null,
"prefix": "Bestelling wijn/gin",
"type": "Reference"
},
"provider": null,
"method": "Transfer",
"freeContribution": null,
"settlement": null,
"ibanName": null,
"iban": null,
"balanceItemPayments": [{
"balanceItem": {
"order": {
"webshopId": "7b952ab3-60c7-4d59-bb40-5b10cd9a1a51",
"status": "Created",
"updatedAt": 1684575959000,
"validAt": 1670769743000,
"createdAt": 1670769743000,
"payment": null,
"data": {
"comments": "",
"paymentMethod": "Transfer",
"reservedOrder": true,
"reservedPersons": 0,
"consumerLanguage": "nl",
"fieldAnswers": [],
"customer": {
"phone": "+32 479 42 78 66",
"email": "simon@stamhoofd.nl",
"lastName": "Backx",
"firstName": "Simon"
},
"cart": {
"items": [{
"reservedAmount": 5,
"unitPrice": 1800,
"id": "fc84574f-8944-4b89-8dd5-43b49a836542",
"fieldAnswers": [],
"amount": 5,
"options": [],
"productPrice": {
"discountAmount": 2,
"discountPrice": null,
"price": 1800,
"name": "Doos met 6",
"id": "60d5352e-b5ca-4f1a-97b9-19f924581009"
},
"product": {
"unique": false,
"allowMultiple": true,
"disableAfter": null,
"enableAfter": null,
"hidden": false,
"maxPerOrder": null,
"dateRange": null,
"location": null,
"customFields": [],
"optionMenus": [],
"prices": [{
"discountAmount": 2,
"discountPrice": null,
"price": 1500,
"name": "Doos met 9 flessen",
"id": "45eb4ced-b2c3-42a0-92fe-68cea6756189"
}, {
"discountAmount": 2,
"discountPrice": null,
"price": 1800,
"name": "Doos met 6",
"id": "60d5352e-b5ca-4f1a-97b9-19f924581009"
}],
"usedStock": 11,
"stock": null,
"askName": false,
"type": "Product",
"images": [{
"resolutions": [{
"file": {
"id": "f5d28c3b-afd9-46b9-8bb0-ca65a7622f6f",
"server": "https://stamhoofd.ams3.digitaloceanspaces.com",
"path": "production/6b9a3d33-458b-44f0-aedb-446118a73462/f5d28c3b-afd9-46b9-8bb0-ca65a7622f6f.jpg",
"size": 42614,
"name": null
},
"width": 750,
"height": 500
}, {
"file": {
"id": "db56f90f-bf1b-4ce0-b7f5-2c3431eaba4f",
"server": "https://stamhoofd.ams3.digitaloceanspaces.com",
"path": "production/6b9a3d33-458b-44f0-aedb-446118a73462/db56f90f-bf1b-4ce0-b7f5-2c3431eaba4f.jpg",
"size": 11067,
"name": null
},
"width": 250,
"height": 250
}],
"source": {
"id": "deff27ff-c515-4b08-9e69-1b3d13a74531",
"server": "https://stamhoofd.ams3.digitaloceanspaces.com",
"path": "production/6b9a3d33-458b-44f0-aedb-446118a73462/deff27ff-c515-4b08-9e69-1b3d13a74531.jpg",
"size": 1585121,
"name": null
},
"id": "6b9a3d33-458b-44f0-aedb-446118a73462"
}],
"enabled": true,
"description": "Dit is een beschrijving.",
"name": "Sauvignon",
"id": "af054b10-4dd7-49b3-a94f-e3f2a3eb8bac"
}
}]
},
"recordAnswers": [],
"address": null,
"checkoutMethod": {
"address": {
"country": "BE",
"city": "Mars",
"postalCode": "974E5A",
"number": "845E43",
"street": "Andromedanevel"
},
"type": "Takeout",
"timeSlots": {
"timeSlots": [{
"usedPersons": 0,
"maxPersons": null,
"usedOrders": 1,
"maxOrders": 10,
"endTime": 720,
"startTime": 540,
"date": 1645384860000,
"id": "976f5a4f-b43c-4d62-8e4d-a216e3bb5cf5"
}, {
"usedPersons": 0,
"maxPersons": null,
"usedOrders": 1,
"maxOrders": 10,
"endTime": 840,
"startTime": 720,
"date": 1645384920000,
"id": "a87f0fed-093e-4ece-a83a-11fba8354444"
}]
},
"description": "",
"name": "Testlocatie",
"id": "b826fc1c-d4d2-450d-8e35-5bcdc078981d"
},
"timeSlot": {
"usedPersons": 0,
"maxPersons": null,
"usedOrders": 1,
"maxOrders": 10,
"endTime": 720,
"startTime": 540,
"date": 1645384860000,
"id": "976f5a4f-b43c-4d62-8e4d-a216e3bb5cf5"
}
},
"number": 2,
"id": "6db480da-da97-44d0-8c04-0802e03ca6f4"
},
"member": null,
"registration": null,
"status": "Pending",
"createdAt": 1670769743000,
"pricePaid": 0,
"price": 9000,
"description": "Bestelling #2 - Eindejaarsverkoop wijn/gin",
"id": "a3e701a7-6fc9-4a10-89d7-2fdaf1959d99"
},
"price": 9000,
"id": "b3e72044-2747-44d2-9f40-8f2e8da16b2d"
}],
"updatedAt": 1684575959000,
"createdAt": 1670769743000,
"paidAt": null,
"transferDescription": "Bestelling wijn/gin 2",
"price": 9000,
"status": "Created",
"id": "cb14a51e-a3d8-4193-84ae-4fc47aea9944"
}]Er is momenteel geen paginatie voorzien voor deze endpoint. Oude betalingen worden automatisch weggelaten uit het antwoord van de request.
Voorbeeld 2: betalingen als (niet)betaald markeren
PATCH https://634d549b-862e-4a5e-852d-3d4a9814e22d.api.stamhoofd.app/v191/organization/payments
{
"_isPatch": true,
"changes": [
{
"patch": {
"status": "Succeeded",
"id": "cb14a51e-a3d8-4193-84ae-4fc47aea9944",
"_isPatch": true
}
}
]
}Als je meerdere betalingen tegelijk wilt wijzigen:
{
"_isPatch": true,
"changes": [
{
"patch": {
"status": "Created",
"id": "cb14a51e-a3d8-4193-84ae-4fc47aea9944",
"_isPatch": true
}
},
{
"patch": {
"status": "Created",
"id": "9274bb7a-f738-4560-a833-c7b553f15717",
"_isPatch": true
}
}
]
}Als antwoord op deze request krijg je een lijst van de betalingen die je hebt gewijzigd en hun nieuwe eigenschappen.