Merge pull request #64 from starkbank/feature/institution

Add Institution resource to allow SPI and TED participant query

CHANGELOG.md

@@ -15,6 +15,7 @@ Given a version number MAJOR.MINOR.PATCH, increment:
 ## [Unreleased]
 ### Added
 - "payment" account type for Pix related resources
+- Institution resource to allow query of institutions recognized by the Brazilian Central Bank for Pix and TED transactions
 
 ## [2.10.1] - 2021-06-07
 ### Fixed

README.md

@@ -454,6 +454,19 @@ log = starkbank.transfer.log.get("5155165527080960")
 print(log)
 ```
 
+### Query Bacen institutions
+
+You can query institutions registered by the Brazilian Central Bank for Pix and TED transactions.
+
+```python
+import starkbank
+
+institution = starkbank.institution.query(search="stark")
+
+for institution in institutions:
+    print(institution)
+```
+
 ### Create invoices
 
 You can create dynamic QR Code invoices to charge customers or to receive money from accounts

starkbank/__init__.py

@@ -19,6 +19,9 @@
 from . import transfer
 from .transfer.__transfer import Transfer
 
+from . import institution
+from .institution.__institution import Institution
+
 from . import boletoholmes
 from .boletoholmes.__boletoholmes import BoletoHolmes
 

starkbank/dictkey/__dictkey.py

@@ -33,7 +33,6 @@ def __init__(self, id=None, type=None, name=None, tax_id=None, owner_type=None,
                  owned=None, created=None):
         Resource.__init__(self, id=id)
 
-        self.id = id
         self.type = type
         self.name = name
         self.tax_id = tax_id

starkbank/institution/__init__.py

@@ -0,0 +1 @@
+from .__institution import query

starkbank/institution/__institution.py

@@ -0,0 +1,40 @@
+from ..utils import rest
+from ..utils.resource import SubResource
+
+
+class Institution(SubResource):
+    """# Institution object
+    A Institution is used to get information on the institutions that are recognized by the Brazilian Central Bank.
+    Besides the display name and full name, they also include the STR code (used for TEDs) and the SPI Code
+    (used for Pix) for the institutions. Either of these codes may be empty if the institution is not registered on
+    that Central Bank service.
+    ## Attributes:
+    - display_name [string]: short version of the institution name that should be displayed to end users. ex: "Stark Bank"
+    - name [string]: full version of the institution name. ex: "Stark Bank S.A."
+    - spi_code [string]: SPI code used to identify the institution on Pix transactions. ex: "20018183"
+    - str_code [string]: STR code used to identify the institution on TED transactions. ex: "123"
+    """
+
+    def __init__(self, display_name, name, spi_code, str_code):
+        self.display_name = display_name
+        self.name = name
+        self.spi_code = spi_code
+        self.str_code = str_code
+
+
+_resource = {"class": Institution, "name": "Institution"}
+
+
+def query(limit=None, search=None, spi_codes=None, str_codes=None, user=None):
+    """# Retrieve Bacen Institutions
+    Receive a list of Institution objects that are recognized by the Brazilian Central bank for Pix and TED transactions
+    ## Parameters (optional):
+    - limit [integer, default None]: maximum number of objects to be retrieved. Unlimited if None. ex: 35
+    - search [string, default None]: part of the institution name to be searched. ex: "stark"
+    - spi_codes [list of strings, default None]: list of SPI (Pix) codes to be searched. ex: ["20018183"]
+    - str_codes [list of strings, default None]: list of STR (TED) codes to be searched. ex: ["260"]
+    - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call
+    ## Return:
+    - list of Institution objects with updated attributes
+    """
+    return rest.get_page(resource=_resource, search=search, spi_codes=spi_codes, str_codes=str_codes, limit=limit, user=user)[0]

tests/api/testInstitution.py

@@ -0,0 +1,26 @@
+import starkbank
+from unittest import TestCase, main
+from tests.utils.user import exampleProject
+
+
+starkbank.user = exampleProject
+
+
+class TestInstitutionQuery(TestCase):
+
+    def test_success(self):
+        institutions = starkbank.institution.query()
+        for institution in institutions[:5]:
+            self.assertIsInstance(institution.display_name, str)
+            self.assertIsInstance(institution.name, str)
+            self.assertIsInstance(institution.str_code, str)
+            self.assertIsInstance(institution.spi_code, str)
+            print(institution)
+
+        self.assertEqual(len(starkbank.institution.query(search="stark")), 1)
+        self.assertEqual(len(starkbank.institution.query(spi_codes="20018183")), 1)
+        self.assertEqual(len(starkbank.institution.query(str_codes="341")), 1)
+
+
+if __name__ == '__main__':
+    main()

tests/sdk/testInstitution.py

@@ -0,0 +1,26 @@
+import starkbank
+from unittest import TestCase, main
+from tests.utils.user import exampleProject
+
+
+starkbank.user = exampleProject
+
+
+class TestInstitutionQuery(TestCase):
+
+    def test_success(self):
+        institutions = starkbank.institution.query()
+        for institution in institutions[:5]:
+            self.assertIsInstance(institution.display_name, str)
+            self.assertIsInstance(institution.name, str)
+            self.assertIsInstance(institution.str_code, str)
+            self.assertIsInstance(institution.spi_code, str)
+            print(institution)
+
+        self.assertEqual(len(starkbank.institution.query(search="stark")), 1)
+        self.assertEqual(len(starkbank.institution.query(spi_codes="20018183")), 1)
+        self.assertEqual(len(starkbank.institution.query(str_codes="341")), 1)
+
+
+if __name__ == '__main__':
+    main()