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 token aanvragen via Stamhoofd waarmee je de API kan raadplegen. Een token is momenteel altijd verbonden met een gebruiker, dus moet je ook kiezen aan welke gebruiker je de token wilt verbinden. We raden om altijd een nieuwe gebruiker aan te maken specifiek voor de API en de doelstelling waarvoor je hem wilt gebruiken. Daardoor zal je netjes te toegang van de API kunnen afschermen door de toegangsrechten van de gekoppelde gebruiker aan te passen, bv. tot enkel het gedeelte van betalingen. De gekoppelde gebruiker verwijderen zal ook meteen de toegang van de API intrekken.
Je kan een token aanvragen via hallo@stamhoofd.nl
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 <jouwtoken>. Authenticatie is bij de meeste endpoints noodzakelijk.
Wees zuinig met je requests
Spreek de API niet aan als dat niet nodig is. Beperk het aantal requests tot een absoluut minimum. Als we hier misbruik zien kunnen we het gebruik van de API afsluiten.
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.