Add expand to PixKey resource

CHANGELOG.md

@@ -14,6 +14,9 @@ Given a version number MAJOR.MINOR.PATCH, increment:
 
 ## [Unreleased]
 
+### Added
+- expand optional parameter to PixKey and BRCodePreview resources
+
 ### Added
 - IssuingBillingTransaction resource
 - IssuingBillingInvoice resource

README.md

@@ -1785,7 +1785,8 @@ for key in keys:
 
 Information on a Pix key may be retrieved by its id and the tax ID of the consulting agent.
 An endToEndId must be informed so you can link any resulting purchases to this query,
-avoiding sweep blocks by the Central Bank.
+avoiding sweep blocks by the Central Bank. It is also possible to add the expand parameter 
+in order to retrieve statistics related to the key and/or its owner.
 
 ```python
 import starkinfra
@@ -1794,6 +1795,7 @@ key = starkinfra.pixkey.get(
     "5155165527080960",
     payer_id="012.345.678-90",
     end_to_end_id=starkinfra.endtoendid.create("20018183"),
+    expand=[], #Options are "keyStatistics", "ownerStatistics"
 )
 
 print(key)
@@ -2539,7 +2541,8 @@ previews = starkinfra.brcodepreview.create([
     ),
     starkinfra.BrcodePreview(
         id="00020126430014br.gov.bcb.pix0121aryastark@hotmail.com5204000053039865406100.005802BR5910Arya Stark6014Rio de Janeiro6216051262678188104863042BA4",
-        payer_id="012.345.678-90"
+        payer_id="012.345.678-90",
+        expand=[],
     ),
 ])
 

starkinfra/brcodepreview/__brcodepreview.py

@@ -13,6 +13,7 @@ class BrcodePreview(Resource):
     - id [string]: BR Code from a Pix payment. This is also de information directly encoded in a QR Code. ex: "00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff817b5a8520400005303986540510.005802BR5908T'Challa6009Sao Paulo62090505123456304B14A"
     - payer_id [string]: tax id (CPF/CNPJ) of the individual or business requesting the PixKey information. This id is used by the Central Bank to limit request rates. ex: "20.018.183/0001-80"
     ## Parameters (optional):
+    - expand [list of strings]: list of strings to retrieve fraud statistics related to the pixKey and its owner. Options: "keyStatistics", "ownerStatistics"
     - end_to_end_id [string]: central bank's unique transaction ID. ex: "E79457883202101262140HHX553UPqeq"
     ## Attributes (return-only):
     - account_number [string]: Payment receiver account number. ex: "1234567"
@@ -35,12 +36,15 @@ class BrcodePreview(Resource):
     - scheduled [datetime.datetime]: date of payment execution. ex: datetime(2020, 3, 10)
     - status [string]: Payment status. ex: "active", "paid", "canceled" or "unknown"
     - tax_id [string]: Payment receiver tax ID. ex: "012.345.678-90"
+    - keyStatistics [list of PixKey.Statistics, default []]: statistics associated with the key itself. ex: [PixKey.Statistics(after="2023-11-06T18:57:08.325090+00:00", source="pix-key")]
+    - ownerStatistics [list of PixKey.OwnerStatistics, default []]: statistics associated with legal or juridical person that owns the key. ex: [PixKey.OwnerStatistics(after="2023-11-06T18:57:08.325090+00:00", source="pix-key")]
     """
 
     def __init__(self, id, payer_id, account_number=None, account_type=None, amount=None, amount_type=None, bank_code=None,
                  branch_code=None, cash_amount=None, cashier_bank_code=None, cashier_type=None, discount_amount=None,
                  fine_amount=None, interest_amount=None, key_id=None, name=None, nominal_amount=None, end_to_end_id=None,
-                 reconciliation_id=None, reduction_amount=None, scheduled=None, status=None, tax_id=None, description=None):
+                 reconciliation_id=None, reduction_amount=None, scheduled=None, status=None, tax_id=None, description=None,
+                 expand=None, key_statistics=None, owner_statistics=None):
         Resource.__init__(self, id=id)
 
         self.payer_id = payer_id
@@ -66,6 +70,9 @@ def __init__(self, id, payer_id, account_number=None, account_type=None, amount=
         self.status = status
         self.tax_id = tax_id
         self.description = description
+        self.expand = expand
+        self.key_statistics = key_statistics
+        self.owner_statistics = owner_statistics
 
 
 _resource = {"class": BrcodePreview, "name": "BrcodePreview"}

starkinfra/pixkey/__pixkey.py

@@ -28,10 +28,13 @@ class PixKey(Resource):
     - bank_name [string]: name of the bank that holds the account linked to the PixKey. ex: "StarkBank"
     - type [string]: type of the PixKey. Options: "cpf", "cnpj", "phone", "email" and "evp"
     - created [datetime.datetime]: creation datetime for the PixKey. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0)
+    - statistics [list of PixKey.Statistics, default []]: statistics associated with the key itself. ex: [PixKey.Statistics(after="2023-11-06T18:57:08.325090+00:00", source="pix-key")]
+    - ownerStatistics [list of PixKey.OwnerStatistics, default []]: statistics associated with legal or juridical person that owns the key. ex: [PixKey.OwnerStatistics(after="2023-11-06T18:57:08.325090+00:00", source="pix-key")]
     """
 
     def __init__(self, account_created, account_number, account_type, branch_code, name, tax_id, id=None, tags=None,
-                 owned=None, owner_type=None, status=None, bank_code=None, bank_name=None, type=None, created=None):
+                 owned=None, owner_type=None, status=None, bank_code=None, bank_name=None, type=None, created=None,
+                 statistics=None, owner_statistics=None):
         Resource.__init__(self, id=id)
 
         self.account_created = check_datetime(account_created)
@@ -48,6 +51,8 @@ def __init__(self, account_created, account_number, account_type, branch_code, n
         self.bank_name = bank_name
         self.type = type
         self.created = check_datetime(created)
+        self.statistics = statistics
+        self.owner_statistics = owner_statistics
 
 
 _resource = {"class": PixKey, "name": "PixKey"}
@@ -66,7 +71,7 @@ def create(key, user=None):
     return rest.post_single(resource=_resource, entity=key, user=user)
 
 
-def get(id, payer_id, end_to_end_id=None, user=None):
+def get(id, payer_id, end_to_end_id=None, user=None, expand=None):
     """# Retrieve a PixKey object
     Retrieve the PixKey object linked to your Workspace in the Stark Infra API by its id.
     ## Parameters (required):
@@ -79,7 +84,7 @@ def get(id, payer_id, end_to_end_id=None, user=None):
     - PixKey object that corresponds to the given id.
     """
 
-    return rest.get_id(id=id, payer_id=payer_id, end_to_end_id=end_to_end_id, resource=_resource, user=user)
+    return rest.get_id(id=id, payer_id=payer_id, end_to_end_id=end_to_end_id, resource=_resource, user=user, expand=expand)
 
 
 def query(limit=None, after=None, before=None, status=None, tags=None, ids=None, type=None, user=None):

tests/sdk/testBrcodePreview.py

@@ -10,31 +10,27 @@ class TestBrcodePreview(TestCase):
 
     def test_success(self):
         static_brcodes = list(starkinfra.staticbrcode.query(limit=2))
-
         dynamic_brcodes = list(starkinfra.dynamicbrcode.query(limit=2))
-
         brcodes = static_brcodes + dynamic_brcodes
 
         previews = starkinfra.brcodepreview.create([
             starkinfra.BrcodePreview(
                 id=brcodes[0].id,
-                payer_id="012.345.678-90"
+                payer_id="012.345.678-90",
             ),
             starkinfra.BrcodePreview(
-                id=brcodes[1].id,
-                payer_id="012.345.678-90"
+                id=brcodes[0].id,
+                payer_id="012.345.678-90",
+                expand=["keyStatistics", "filter_this_out"],
             ),
             starkinfra.BrcodePreview(
-                id=brcodes[2].id,
-                payer_id="012.345.678-90"
+                id=brcodes[0].id,
+                payer_id="012.345.678-90",
+                expand=["keyStatistics", "ownerStatistics"],
             ),
-            starkinfra.BrcodePreview(
-                id=brcodes[3].id,
-                payer_id="012.345.678-90"
-            )
         ])
 
-        self.assertTrue(len(previews) == 4)
+        self.assertTrue(len(previews) == 3)
 
         index = 0
         for preview in previews:

tests/sdk/testPixKey.py

@@ -65,6 +65,18 @@ def test_success(self):
         self.assertIsNotNone(pix_key.id)
         self.assertEqual(pix_key.id, pix_key_id)
         print(pix_key)
+
+    def test_success_with_expand(self):
+        pix_keys = starkinfra.pixkey.query()
+        pix_key_id = next(pix_keys).id
+        pix_key = starkinfra.pixkey.get(
+            id=pix_key_id,
+            payer_id=TaxIdGenerator.taxId(),
+            expand=["statistics", "ownerStatistics"],
+        )
+        self.assertIn("statistics", str(pix_key))
+        self.assertIn("owner_statistics", str(pix_key))
+        print(pix_key)
 
     def test_success_ids(self):
         pix_keys = starkinfra.pixkey.query(limit=5)