Add PixKeyHolmes and PixInternalTransactionReport resources, includin…

CHANGELOG.md

@@ -13,6 +13,10 @@ Given a version number MAJOR.MINOR.PATCH, increment:
 
 
 ## [Unreleased]
+### Added
+- PixKeyHolmes resource
+- PixInternalTransactionReport resource
+- log subresource to PixFraud
 
 ## [0.25.0] - 2026-04-08
 ### Added

README.md

@@ -48,6 +48,7 @@ This SDK version is compatible with the Stark Infra API v2.
         - [PixBalance](#get-your-pixbalance): View your account balance
         - [PixStatement](#create-a-pixstatement): Request your account statement
         - [PixKey](#create-a-pixkey): Create a Pix Key
+        - [PixKeyHolmes](#create-pixkeyholmes): Investigate the registration of a Pix Key in the DICT
         - [PixClaim](#create-a-pixclaim): Claim a Pix Key
         - [PixDirector](#create-a-pixdirector): Create a Pix Director
         - [PixInfraction](#create-pixinfractions): Create Pix Infraction reports
@@ -59,6 +60,7 @@ This SDK version is compatible with the Stark Infra API v2.
         - [DynamicBrcode](#create-dynamicbrcodes): Create dynamic Pix BR codes
         - [BrcodePreview](#create-brcodepreviews): Read data from BR Codes before paying them
         - [PixDispute](#create-pixdisputes): Create Pix Disputes
+        - [PixInternalTransactionReport](#create-pixinternaltransactionreports): Report internal transactions to the Central Bank
     - [Lending](#lending)
         - [CreditNote](#create-creditnotes): Create credit notes
         - [CreditPreview](#create-creditpreviews): Create credit previews
@@ -1866,6 +1868,46 @@ log = starkinfra.pixkey.log.get("5155165527080960")
 print(log)
 ```
 
+### Create PixKeyHolmes
+
+To investigate whether a Pix Key is registered in the Central Bank's DICT,
+open up a PixKeyHolmes for it:
+
+```python
+import starkinfra
+
+holmes = starkinfra.pixkeyholmes.create([
+    starkinfra.PixKeyHolmes(
+        key_id="+5511989898989"
+    ),
+    starkinfra.PixKeyHolmes(
+        key_id="[email protected]",
+        tags=["sherlock"]
+    )
+])
+
+for sherlock in holmes:
+    print(sherlock)
+```
+
+### Query PixKeyHolmes
+
+You can query multiple PixKeyHolmes according to filters.
+
+```python
+import starkinfra
+from datetime import date
+
+holmes = starkinfra.pixkeyholmes.query(
+    after=date(2022, 6, 1),
+    before=date(2022, 10, 30),
+    status="solved"
+)
+
+for sherlock in holmes:
+    print(sherlock)
+```
+
 ### Create a PixClaim
 
 You can create a Pix claim to request the transfer of a Pix key from another bank to one of your accounts:
@@ -2182,6 +2224,36 @@ fraud = starkinfra.pixfraud.cancel("5155165527080960")
 print(fraud)
 ```
 
+### Query PixFraud logs
+
+You can query PixFraud logs to better understand their life cycles.
+
+```python
+import starkinfra
+from datetime import date
+
+logs = starkinfra.pixfraud.log.query(
+    limit=50,
+    after=date(2022, 1, 1),
+    before=date(2022, 1, 20),
+)
+
+for log in logs:
+    print(log)
+```
+
+### Get a PixFraud log
+
+You can also get a specific log by its id.
+
+```python
+import starkinfra
+
+log = starkinfra.pixfraud.log.get("5155165527080960")
+
+print(log)
+```
+
 ### Get a PixUser
 
 You can get a specific fraud statistics of a user with his taxId.
@@ -2649,6 +2721,101 @@ log = starkinfra.pixdispute.log.get("5155165527080960")
 print(log)
 ```
 
+### Create PixInternalTransactionReports
+
+Transactions that happen internally, outside of the SPI, must be reported to the
+Central Bank so they are reflected in your statements. You can do so by creating
+PixInternalTransactionReports:
+
+```python
+import starkinfra
+from datetime import datetime
+
+reports = starkinfra.pixinternaltransactionreport.create([
+    starkinfra.PixInternalTransactionReport(
+        amount=10000,
+        created=datetime(2024, 1, 1, 12, 0, 0),
+        end_to_end_id="E12345678202401011234567890123456",
+        method="manual",
+        reference_type="request",
+        sender_account_number="12345",
+        sender_branch_code="0001",
+        sender_account_type="checking",
+        sender_bank_code="12345678",
+        sender_tax_id="123.456.789-01",
+        receiver_account_number="67890",
+        receiver_branch_code="0001",
+        receiver_account_type="savings",
+        receiver_bank_code="87654321",
+        receiver_tax_id="987.654.321-00",
+        receiver_key_id="[email protected]"
+    )
+])
+
+for report in reports:
+    print(report)
+```
+
+### Query PixInternalTransactionReports
+
+You can query multiple PixInternalTransactionReports according to filters.
+
+```python
+import starkinfra
+from datetime import date
+
+reports = starkinfra.pixinternaltransactionreport.query(
+    after=date(2024, 1, 1),
+    before=date(2024, 1, 30),
+    status="success"
+)
+
+for report in reports:
+    print(report)
+```
+
+### Get a PixInternalTransactionReport
+
+After its creation, information on a PixInternalTransactionReport may be retrieved by its id.
+
+```python
+import starkinfra
+
+report = starkinfra.pixinternaltransactionreport.get("5656565656565656")
+
+print(report)
+```
+
+### Query PixInternalTransactionReport logs
+
+You can query PixInternalTransactionReport logs to better understand their life cycles.
+
+```python
+import starkinfra
+from datetime import date
+
+logs = starkinfra.pixinternaltransactionreport.log.query(
+    limit=50,
+    after=date(2024, 1, 1),
+    before=date(2024, 1, 20),
+)
+
+for log in logs:
+    print(log)
+```
+
+### Get a PixInternalTransactionReport log
+
+You can also get a specific log by its id.
+
+```python
+import starkinfra
+
+log = starkinfra.pixinternaltransactionreport.log.get("5155165527080960")
+
+print(log)
+```
+
 ## Lending
 If you want to establish a lending operation, you can use Stark Infra to
 create a CCB contract. This will enable your business to lend money without

run-tests.sh

@@ -41,6 +41,10 @@ commands=(
         "{ python -m unittest tests.sdk.testPixReversal; }"
         "{ python -m unittest tests.sdk.testPixReversalLog; }"
         "{ python -m unittest tests.sdk.testPixStatement; }"
+        "{ python -m unittest tests.sdk.testPixKeyHolmes; }"
+        "{ python -m unittest tests.sdk.testPixInternalTransactionReport; }"
+        "{ python -m unittest tests.sdk.testPixInternalTransactionReportLog; }"
+        "{ python -m unittest tests.sdk.testPixFraudLog; }"
     )
 
 clen=`expr "${#commands[@]}" - 1` # get length of commands - 1

starkinfra/__init__.py

@@ -51,6 +51,12 @@
 from . import pixuser
 from .pixuser.__pixuser import PixUser
 
+from . import pixkeyholmes
+from .pixkeyholmes.__pixkeyholmes import PixKeyHolmes
+
+from . import pixinternaltransactionreport
+from .pixinternaltransactionreport.__pixinternaltransactionreport import PixInternalTransactionReport
+
 from . import issuingbalance
 from .issuingbalance.__issuingbalance import IssuingBalance
 

starkinfra/pixfraud/__init__.py

@@ -1 +1,3 @@
 from .__pixfraud import create, get, query, page, cancel
+from .log.__log import Log
+from . import log

starkinfra/pixfraud/log/__init__.py

@@ -0,0 +1 @@
+from .__log import query, page, get

starkinfra/pixfraud/log/__log.py

@@ -0,0 +1,97 @@
+from starkcore.utils.checks import check_datetime, check_date
+from ..__pixfraud import _resource as _pixfraud_resource
+from starkcore.utils.resource import Resource
+from starkcore.utils.api import from_api_json
+from ...utils import rest
+
+
+class Log(Resource):
+    """# pixfraud.Log object
+    Every time a PixFraud entity is modified, a corresponding PixFraud.Log
+    is generated for the entity. This log is never generated by the user.
+    ## Attributes (return-only):
+    - id [string]: unique id returned when the log is created. ex: "5656565656565656"
+    - fraud [PixFraud]: PixFraud entity to which the log refers to.
+    - type [string]: type of the PixFraud event which triggered the log creation. ex: "created", "failed", "registered", "canceled"
+    - errors [list of strings]: list of errors linked to this PixFraud event
+    - created [datetime.datetime]: creation datetime for the log. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0)
+    """
+    def __init__(self, id, fraud, type, errors, created):
+        Resource.__init__(self, id=id)
+
+        self.fraud = from_api_json(_pixfraud_resource, fraud)
+        self.type = type
+        self.errors = errors
+        self.created = check_datetime(created)
+
+
+_resource = {"class": Log, "name": "PixFraudLog"}
+
+
+def get(id, user=None):
+    """# Retrieve a specific PixFraud.Log
+    Receive a single PixFraud.Log object previously created by the Stark Infra API by its id
+    ## Parameters (required):
+    - id [string]: object unique id. ex: "5656565656565656"
+    ## Parameters (optional):
+    - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkinfra.user was set before function call.
+    ## Return:
+    - PixFraud.Log object with updated attributes
+    """
+    return rest.get_id(resource=_resource, id=id, user=user)
+
+
+def query(ids=None, limit=None, after=None, before=None, types=None, fraud_ids=None, user=None):
+    """# Retrieve PixFraud.Logs
+    Receive a generator of PixFraud.Log objects previously created in the Stark Infra API
+    ## Parameters (optional):
+    - limit [integer, default None]: maximum number of objects to be retrieved. Unlimited if None. ex: 35
+    - after [datetime.date or string, default None]: date filter for objects created after specified date. ex: datetime.date(2020, 3, 10)
+    - before [datetime.date or string, default None]: date filter for objects created before a specified date. ex: datetime.date(2020, 3, 10)
+    - types [list of strings, default None]: filter retrieved objects by types. ex: ["created", "failed", "registered", "canceled"]
+    - fraud_ids [list of strings, default None]: list of PixFraud IDs to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"]
+    - ids [list of strings, default None]: Log ids to filter PixFraud Logs. ex: ["5656565656565656"]
+    - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkinfra.user was set before function call
+    ## Return:
+    - generator of PixFraud.Log objects with updated attributes
+    """
+    return rest.get_stream(
+        resource=_resource,
+        ids=ids,
+        limit=limit,
+        after=check_date(after),
+        before=check_date(before),
+        types=types,
+        fraud_ids=fraud_ids,
+        user=user,
+    )
+
+
+def page(cursor=None, ids=None, limit=None, after=None, before=None, types=None, fraud_ids=None, user=None):
+    """# Retrieve paged PixFraud.Logs
+    Receive a list of up to 100 PixFraud.Log objects previously created in the Stark Infra API and the cursor to the next page.
+    Use this function instead of query if you want to manually page your frauds.
+    ## Parameters (optional):
+    - cursor [string, default None]: cursor returned on the previous page function call
+    - limit [integer, default 100]: maximum number of objects to be retrieved. Max = 100. ex: 35
+    - after [datetime.date or string, default None]: date filter for objects created after a specified date. ex: datetime.date(2020, 3, 10)
+    - before [datetime.date or string, default None]: date filter for objects created before a specified date. ex: datetime.date(2020, 3, 10)
+    - types [list of strings, default None]: filter retrieved objects by types. ex: ["created", "failed", "registered", "canceled"]
+    - fraud_ids [list of strings, default None]: list of PixFraud ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"]
+    - ids [list of strings, default None]: Log ids to filter PixFraud Logs. ex: ["5656565656565656"]
+    - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkinfra.user was set before function call
+    ## Return:
+    - list of PixFraud.Log objects with updated attributes
+    - cursor to retrieve the next page of PixFraud.Log objects
+    """
+    return rest.get_page(
+        resource=_resource,
+        cursor=cursor,
+        ids=ids,
+        limit=limit,
+        after=check_date(after),
+        before=check_date(before),
+        types=types,
+        fraud_ids=fraud_ids,
+        user=user,
+    )

starkinfra/pixinternaltransactionreport/__init__.py

@@ -0,0 +1,3 @@
+from . import log
+from .log.__log import Log
+from .__pixinternaltransactionreport import create, get, query, page