API documentation
This project also integrates with embedded keypad and mobile scanner app, which are part of the store and allows customers to order a product directly at store as they are taking their chosen product. The keypad is simple Arduino-like device, which communicates with our website via this API. Mobile scanner is Quasar Capacitor app for Android and iOS with either physical scanner or just camera.
Due to the fact, that APIs are used by simple embedded device, which runs compiled static code, we don't use OAuth or other token based access system. It is simply HTTPS and pre-shared API secret key, which is sent in header with each request. All APIs in small-business-fridge are currently protected in this manner as there are no public functions.
By default, each request has to contain header called 'sbf-API-secret' and value of the secret key, which is supplied in config.js file.
If the secret key is wrong or not sent at all, API returns Status code: 400 Bad Request and JSON object with error and link to this documentation.
Custom Header example
sbf-API-secret: vErYs3cR3tK3yPr3fEr4bLyR4nD0mH4sh
Find user's display name via keypad Id.
GET /api/customerName
Very straightforward function. Supply customer's keypadId (Number). If supplied keypadId is found in the database, API returns JSON with string containing customer's display name. If supplied keypadId does not exist in the database, API returns Status code: 404 Not Found and JSON with string "NOT_FOUND". If supplied keypadId is not a natural number, API returns Status code: 400 Bad Request and JSON object with error and link to this documentation.
| Name | Type | Description |
|---|---|---|
customer |
number |
Required. The query contains number which represents customer's keypadId. |
Suppose you want to find display name for customer with keypadId 3.
curl -H "sbf-API-secret: secret_key" https://example.com/api/customerName?customer=3
Status: 200 OK
"John Smith"Order a specified product with specified customer via keypad Id.
POST /api/keypadOrder
Supply customer's keypadId (Number) and product's keypadId (Number). If customer is found, then function continues to search for product. If product is found, function continues to search for product's delivery, which has amount_left greater than zero. If all those prerequisites are met, then order is made just like when user orders via website. Additionally the parameter keypadOrder is set to true in the order document to distinguish orders made via website and via API. API returns Status code: 200 OK and object containing user object, product name and price.
If user is not found, API returns Status code: 404 Not Found and JSON with string "USER_NOT_FOUND".
If product is not found, API returns Status code: 404 Not Found and JSON with string "PRODUCT_NOT_FOUND".
If there are no deliveries with amount_left greater than zero, API returns Status code: 404 Not Found and JSON with string "STOCK_NOT_FOUND".
| Name | Type | Description |
|---|---|---|
customer |
number |
Required. The query contains number which represents customer's keypadId. |
product |
number |
Required. The query contains number which represents product's keypadId. |
Suppose you are customer with keypadId 2 and want to order product with keyPadId 4.
curl -H "sbf-API-secret: secret_key" -H "Content-Type: application/json" -X POST -d '{"customer":1,"product":3}' https://example.com/api/keypadOrder
Status: 200 OK
{
'user': {
'admin': false,
'supplier': false,
'showAllProducts': false,
'sendMailOnEshopPurchase': true,
'_id': '0274653d64113221e1456438',
'oid': '12cf4401-c897-4165-8259-dc345112db5a',
'displayName': 'Smith John',
'email': 'j.smith@example.com',
'keypadId': 1,
'__v':0,
'IBAN': 'CZ1234567890123456789012345'
},
'product': {
'name': 'Monster Rossi',
'price': 3
}
}