Hotspot voucher api interface

README.md

@@ -81,6 +81,17 @@ USERNAME            IP ADDRESS      STATUS
 
 Make sure you have your [Settings](#Settings) file configured correctly for these to work.
 
+### [vouchers.py](vouchers.py)
+
+A simple script to fetch the next ten unused vouchers, optionally limited to certain voucher groups:
+
+```
+$ python vouchers.py kids
+kids: 112768, 426812, 004408, 551961, 090222, 023504, 657011, 125990, 591588, 650649
+```
+
+If no arguments are provided, then all voucher groups are iterated. Else, only voucher groups that have any of the provided argument strings in their names are listed.
+
 ## Settings
 
 You can store your controller settings in a configuration file to avoid hard-coding them in your scripts.

omada/omada.py

@@ -590,3 +590,25 @@ def getWirelessGroups(self, site=None):
 	##
 	def getWirelessNetworks(self, group, site=None):
 		return self.__get( f'/sites/{self.__findKey(site)}/setting/wlans/{group}/ssids' )
+
+	##
+	## Returns the list of voucher groups for the given site.
+	##
+	def getVoucherGroups(self, site=None):
+		return self.__geterator( f'/hotspot/sites/{self.__findKey(site)}/voucherGroups' )
+
+	##
+	## Returns the details for the given voucher group and site.
+	##
+	def getVoucherGroupDetails(self, id, site=None):
+		return self.__get( f'/hotspot/sites/{self.__findKey(site)}/voucherGroups/{id}' )
+
+	##
+	## Returns unused vouchers for the given voucher group and site, up to an
+	## optional maximum number
+	##
+	def getUnusedVouchers(self, id, maxnr=None, site=None):
+		res = self.__get( f'/hotspot/sites/{self.__findKey(site)}/voucherGroups/{id}/printUnused' )
+		data = res.get('data', [])
+		return data if maxnr is None else data[:maxnr]
+

vouchers.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+
+import sys
+from omada import Omada
+
+def main():
+
+    omada = Omada(verbose=True)
+    omada.login()
+
+    try:
+        for vg in omada.getVoucherGroups():
+            if len(sys.argv) > 1 and not any(arg in vg['name'] for arg in sys.argv[1:]):
+                # if arguments are provided, limit the voucher groups searched
+                # to those whose names match one of the command line
+                # arguments. I.e. if there are arguments and none ("not any")
+                # match, then skip this group:
+                continue
+            unused = omada.getUnusedVouchers(vg['id'], maxnr=10)
+            if not unused:
+                # no vouchers left in this group, skip it
+                continue
+            codes = [v['code'] for v in unused]
+            print(f"{vg['name']}: {', '.join(codes)}")
+
+    finally:
+        omada.logout()
+
+if __name__ == '__main__':
+    import warnings
+    with warnings.catch_warnings(action="ignore"):
+        main()