Add Split and SplitReceiver resources

CHANGELOG.md

@@ -13,6 +13,11 @@ Given a version number MAJOR.MINOR.PATCH, increment:
 
 
 ## [Unreleased]
+### Added
+- Split resource 
+- SplitLog resource
+- SplitReceiver resource
+- SplitReceiverLog resource
 
 ## [2.22.0] - 2023-09-18
 ### Removed 

README.md

@@ -49,6 +49,8 @@ is as easy as sending a text message to your client!
     - [CorporateBalance](#get-your-corporatebalance): View your corporate balance
     - [CorporateTransactions](#query-corporatetransactions): View the transactions that have affected your corporate balance
     - [CorporateEnums](#corporate-enums): Query enums related to the corporate purchases, such as merchant categories, countries and card purchase methods
+    - [Split](#query-a-split): Split invoices 
+    - [SplitReceiver](#query-a-split-receiver): Receiver of an invoice split 
     - [Webhooks](#create-a-webhook-subscription): Configure your webhook endpoints and subscriptions
     - [WebhookEvents](#process-webhook-events): Manage webhook events
     - [WebhookEventAttempts](#query-failed-webhook-event-delivery-attempts-information): Query failed webhook event deliveries
@@ -2167,6 +2169,114 @@ for method in methods:
     print(method)
 ```
 
+## Split
+
+Split an invoice to different receivers
+
+## Query a Split
+
+You can get a list of created splits given some filters.
+
+```python
+import starkbank
+
+splits = starkbank.split.query(limit=10)
+
+for split in splits:
+    print(split)
+```
+
+## Get a Split
+
+To get a single Split by its id, run:
+
+```python
+import starkbank
+
+split = starkbank.split.get("5155165527080960")
+
+print(split)
+```
+
+## Query split logs
+
+You can query split logs to check additional information 
+
+```python
+import starkbank
+
+logs = starkbank.split.log.query(
+    split_ids=["5155165527080960", "76551659167801921"],
+)
+
+for log in logs:
+    print(log)
+```
+
+## Get a split log
+
+You can also get a split log by specifying its id.
+
+```python
+import starkbank
+
+log = starkbank.split.log.get("5155165527080960")
+
+print(log)
+```
+
+## Query a split receiver
+
+To take a look at the receivers created to your workspace, just run the following:
+
+```python
+import starkbank
+
+receivers = starkbank.splitreceiver.query(limit=10)
+
+for receiver in receivers:
+    print(receiver)
+```
+
+## Get a split receiver
+
+To get a single Receiver by its id, run:
+
+```python
+import starkbank
+
+receiver = starkbank.splitreceiver.get("5155165527080960")
+
+print(receiver)
+```
+
+## Query a split receiver logs
+
+You can query split receiver logs to check additional information
+
+```python
+import starkbank
+
+logs = starkbank.splitreceiver.log.query(
+    receiver_ids =["5155165527080960", "76551659167801921"],
+)
+
+for log in logs:
+    print(log)
+```
+
+## Get a split receiver log
+
+You can also get a split receiver log by specifying its id.
+
+```python
+import starkbank
+
+log = starkbank.splitreceiver.log.get("5155165527080960")
+
+print(log)
+```
+
 ## Create a webhook subscription
 
 To create a webhook subscription and be notified whenever an event occurs, run:

starkbank/__init__.py

@@ -101,3 +101,9 @@
 
 from . import deposit
 from .deposit.__deposit import Deposit
+
+from . import split
+from .split.__split import Split
+
+from . import splitreceiver
+from .splitreceiver.__splitreceiver import SplitReceiver

starkbank/darfpayment/__darfpayment.py

@@ -27,7 +27,7 @@ class DarfPayment(Resource):
     - amount [int]: Total amount due calculated from other amounts. ex: 24146 (= R$ 241.46)
     - fee [integer]: fee charged when the DarfPayment is processed. ex: 0 (= R$ 0.00)
     - transaction_ids [list of strings]: ledger transaction ids linked to this DarfPayment. ex: ["19827356981273"]
-    - updated [datetime.datetime]: creation datetime for the payment. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0)
+    - updated [datetime.datetime]: update datetime for the payment. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0)
     - created [datetime.datetime]: creation datetime for the payment. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0)
     """
     def __init__(self, description, revenue_code, tax_id, competence, nominal_amount, fine_amount, interest_amount,

starkbank/invoice/__invoice.py

@@ -5,6 +5,7 @@
 from .__payment import _sub_resource as _payment_sub_resource
 from .rule.__rule import Rule
 from .rule.__rule import _sub_resource as _rule_resource
+from ..split.__split import _resource as _split_resource, Split
 
 
 class Invoice(Resource):
@@ -25,6 +26,7 @@ class Invoice(Resource):
     - interest [float, default 1.0]: Invoice monthly interest for overdue payment in %. ex: 5.2
     - discounts [list of dictionaries, default []]: list of dictionaries with "percentage":float and "due":datetime.datetime or string pairs
     - rules [list of Invoice.Rules, default []]: list of Invoice.Rule objects for modifying invoice behavior. ex: [Invoice.Rule(key="allowedTaxIds", value=[ "012.345.678-90", "45.059.493/0001-73" ])]
+    - splits [list of Split.Splits, default []]: list of Split.Splits objects to indicate payment receivers. ex: [Invoice.Split(amount=141, receiverId="5706627130851328")]
     - tags [list of strings, default []]: list of strings for tagging
     - descriptions [list of dictionaries, default []]: list of dictionaries with "key":string and (optional) "value":string pairs
     ## Attributes (return-only):
@@ -45,7 +47,7 @@ class Invoice(Resource):
 
     def __init__(self, amount, tax_id, name, due=None, expiration=None, fine=None, interest=None, discounts=None,
                  rules=None, tags=None, descriptions=None, pdf=None, link=None, nominal_amount=None, fine_amount=None,
-                 interest_amount=None, discount_amount=None, id=None, brcode=None, status=None, fee=None,
+                 interest_amount=None, discount_amount=None, id=None, brcode=None, status=None, fee=None, splits=None,
                  transaction_ids=None, created=None, updated=None):
         Resource.__init__(self, id=id)
 
@@ -62,6 +64,7 @@ def __init__(self, amount, tax_id, name, due=None, expiration=None, fine=None, i
         self.interest = interest
         self.discounts = discounts
         self.rules = _parse_rules(rules)
+        self.splits = _parse_splits(splits)
         self.tags = tags
         self.pdf = pdf
         self.link = link
@@ -89,6 +92,18 @@ def _parse_rules(rules):
     return parsed_rules
 
 
+def _parse_splits(splits):
+    if splits is None:
+        return None
+    parsed_splits = []
+    for split in splits:
+        if isinstance(split, Split):
+            parsed_splits.append(split)
+            continue
+        parsed_splits.append(from_api_json(_split_resource, split))
+    return parsed_splits
+
+
 def create(invoices, user=None):
     """# Create Invoices
     Send a list of Invoice objects for creation in the Stark Bank API

starkbank/split/__init__.py

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

starkbank/split/__split.py

@@ -0,0 +1,114 @@
+from ..utils import rest
+from starkcore.utils.resource import Resource
+from starkcore.utils.checks import check_datetime, check_date
+
+
+class Split(Resource):
+
+    """# Split object
+    When you initialize a Split, the entity will not be automatically
+    created in the Stark Bank API. The 'create' function sends the objects
+    to the Stark Bank API and returns the list of created objects.
+    ## Parameters (required):
+    - amount [int]: value to send to receivers. ex: 1000 (= R$ 10.00)
+    - receiver_id [string]: split receiver unique id. ex: "5656565656565656"
+    ## Attributes (return-only):
+    - id [string]: unique id returned when split is created. ex: "5656565656565656"
+    - source [string]: source receivable which generated this split object. ex: "5656565656565656"
+    - external_id [string]: unique id, generated by the system, to avoid duplicated splits. ex: "invoice/1234/receiver/5678"
+    - tags [list of strings, default None]: list of strings for tagging
+    - scheduled [datetime.date, datetime.datetime or string, default now]: payment scheduled date or datetime. ex: datetime.datetime(2020, 3, 10, 15, 17, 3)
+    - status [string]: current payment status. ex: "success" or "failed"
+    - created [datetime.datetime]: creation datetime for the payment. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0)
+    - updated [datetime.datetime]: update datetime for the payment. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0)
+    """
+
+    def __init__(self, amount, receiver_id, id=None, source=None, external_id=None,
+                 tags=None, scheduled=None, status=None, created=None, updated=None):
+        Resource.__init__(self, id=id)
+
+        self.amount = amount
+        self.receiver_id = receiver_id
+        self.source = source
+        self.external_id = external_id
+        self.tags = tags
+        self.scheduled = check_datetime(scheduled)
+        self.status = status
+        self.created = check_datetime(created)
+        self.updated = check_datetime(updated)
+
+
+_resource = {"class": Split, "name": "Split"}
+
+
+def get(id, user=None):
+    """# Retrieve a specific Split
+    Receive a single Split object previously created by the Stark Bank 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 starkbank.user was set before function call
+    ## Return:
+    - Split object with updated attributes
+    """
+    return rest.get_id(resource=_resource, id=id, user=user)
+
+
+def query(limit=None, after=None, before=None, tags=None, ids=None, receiver_ids=None, status=None, user=None):
+    """# Retrieve Splits
+    Receive a generator of Split objects previously created in the Stark Bank 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 only after specified date. ex: datetime.date(2020, 3, 10)
+    - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10)
+    - tags [list of strings, default None]: tags to filter retrieved objects. ex: ["tony", "stark"]
+    - ids [list of strings, default None]: list of ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"]
+    - receiver_ids [list of strings, default None]: list of receiver ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"]
+    - status [string, default None]: filter for status of retrieved objects. ex: "success"
+    - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call
+    ## Return:
+    - generator of Split objects with updated attributes
+    """
+    return rest.get_stream(
+        resource=_resource,
+        limit=limit,
+        after=check_date(after),
+        before=check_date(before),
+        tags=tags,
+        ids=ids,
+        receiver_ids=receiver_ids,
+        status=status,
+        user=user,
+    )
+
+
+def page(cursor=None, after=None, before=None, tags=None, ids=None, receiver_ids=None, status=None, limit=None, user=None):
+    """# Retrieve paged Splits
+    Receive a list of up to 100 Split objects previously created in the Stark Bank API and the cursor to the next page.
+    Use this function instead of query if you want to manually page your requests.
+    ## 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. It must be an integer between 1 and 100. ex: 50
+    - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10)
+    - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10)
+    - tags [list of strings, default None]: tags to filter retrieved objects. ex: ["tony", "stark"]
+    - ids [list of strings, default None]: list of ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"]
+    - receiver_ids [list of strings, default None]: list of receiver ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"]
+    - status [string, default None]: filter for status of retrieved objects. ex: "success"
+    - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call
+    ## Return:
+    - list of Split objects with updated attributes
+    - cursor to retrieve the next page of Split objects
+    """
+    return rest.get_page(
+        resource=_resource,
+        cursor=cursor,
+        limit=limit,
+        after=check_date(after),
+        before=check_date(before),
+        tags=tags,
+        ids=ids,
+        receiver_ids=receiver_ids,
+        status=status,
+        user=user,
+    )

starkbank/split/log/__init__.py

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