Add VerifiedAccount and VerifiedTransfer resources

CHANGELOG.md

@@ -13,6 +13,9 @@ Given a version number MAJOR.MINOR.PATCH, increment:
 
 
 ## [Unreleased]
+### Added
+- VerifiedAccount resource with create, get, cancel, query and page methods, and VerifiedAccount.Log sub-resource
+- VerifiedTransfer resource with create method, reusing transfer.Rule
 ### Fixed
 - Docstrings
 

README.md

@@ -42,6 +42,8 @@ is as easy as sending a text message to your client!
     - [UtilityPayments](#create-utility-payments): Pay Utility bills (water, light, etc.)
     - [TaxPayments](#create-tax-payment): Pay taxes
     - [DarfPayments](#create-darf-payment): Pay DARFs
+    - [VerifiedAccounts](#create-verifiedaccounts): Confirm that a bank account or Pix key belongs to a tax ID
+    - [VerifiedTransfers](#create-verifiedtransfers): Transfer to a previously verified account
     - [PaymentPreviews](#preview-payment-information-before-executing-the-payment): Preview all sorts of payments
     - [PaymentRequest](#create-payment-requests-to-be-approved-by-authorized-people-in-a-cost-center): Request a payment approval to a cost center
     - [CorporateHolders](#create-corporateholders): Manage cardholders
@@ -1878,6 +1880,119 @@ log = starkbank.darfpayment.log.get("1902837198237992")
 print(log)
 ```
 
+## Create VerifiedAccounts
+
+You can create VerifiedAccounts to confirm that a bank account or Pix key belongs to a given tax ID before sending a transfer.
+
+```python
+import starkbank
+
+accounts = starkbank.verifiedaccount.create([
+    starkbank.VerifiedAccount(
+        tax_id="012.345.678-90",
+        name="Tony Stark",
+        bank_code="341",
+        branch_code="2201",
+        number="76543-8",
+        type="checking",
+        tags=["iron", "suit"],
+    ),
+    starkbank.VerifiedAccount(
+        tax_id="012.345.678-90",
+        key_id="tony@starkbank.com",
+        tags=["iron", "suit"],
+    ),
+])
+
+for account in accounts:
+    print(account)
+```
+
+## Get a VerifiedAccount
+
+You can get a specific VerifiedAccount by its id:
+
+```python
+import starkbank
+
+account = starkbank.verifiedaccount.get("5155165527080960")
+
+print(account)
+```
+
+## Cancel a VerifiedAccount
+
+You can cancel a VerifiedAccount by its id:
+
+```python
+import starkbank
+
+account = starkbank.verifiedaccount.cancel("5155165527080960")
+
+print(account)
+```
+
+## Query VerifiedAccounts
+
+To search for VerifiedAccounts using filters, run:
+
+```python
+import starkbank
+
+accounts = starkbank.verifiedaccount.query(
+    limit=10,
+    status="active",
+    tags=["iron", "suit"],
+)
+
+for account in accounts:
+    print(account)
+```
+
+## Query VerifiedAccount logs
+
+You can search for VerifiedAccount logs by specifying filters:
+
+```python
+import starkbank
+
+logs = starkbank.verifiedaccount.log.query(limit=10)
+
+for log in logs:
+    print(log)
+```
+
+## Get a VerifiedAccount log
+
+If you want to get a specific VerifiedAccount log by its id, just run:
+
+```python
+import starkbank
+
+log = starkbank.verifiedaccount.log.get("1902837198237992")
+
+print(log)
+```
+
+## Create VerifiedTransfers
+
+You can send a transfer to a previously verified account by creating a VerifiedTransfer:
+
+```python
+import starkbank
+
+transfers = starkbank.verifiedtransfer.create([
+    starkbank.VerifiedTransfer(
+        amount=1000,
+        account_id="5155165527080960",
+        tags=["iron", "suit"],
+    ),
+])
+
+for transfer in transfers:
+    print(transfer)
+```
+
 ## Preview payment information before executing the payment
 
 You can preview multiple types of payment to confirm any information before actually paying.

starkbank/__init__.py

@@ -121,6 +121,12 @@
 from . import deposit
 from .deposit.__deposit import Deposit
 
+from . import verifiedaccount
+from .verifiedaccount.__verifiedaccount import VerifiedAccount
+
+from . import verifiedtransfer
+from .verifiedtransfer.__verifiedtransfer import VerifiedTransfer
+
 from . import split
 from .split.__split import Split
 

starkbank/verifiedaccount/__init__.py

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

starkbank/verifiedaccount/__verifiedaccount.py

@@ -0,0 +1,143 @@
+from ..utils import rest
+from starkcore.utils.resource import Resource
+from starkcore.utils.checks import check_datetime, check_date
+
+
+class VerifiedAccount(Resource):
+    """# VerifiedAccount object
+    When you initialize a VerifiedAccount, 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):
+    - tax_id [string]: receiver tax ID (CPF or CNPJ) with or without formatting. ex: "01234567890" or "20.018.183/0001-80"
+    ## Parameters (conditionally required):
+    - bank_code [string]: code of the receiver bank institution in Brazil. If an ISPB (8 digits) is informed, a Pix transfer will be created, else a TED will be issued. The bank_code parameter is required if verifying with bank details. ex: "20018183" or "341"
+    - branch_code [string]: receiver bank account branch. Use "-" in case there is a verifier digit. ex: "1357-9". The branch_code parameter is required if verifying with bank details.
+    - key_id [string]: pix key identifier. ex: "tony@starkbank.com", "012.345.678-90". The key_id parameter is required if verifying with Pix key.
+    - name [string]: receiver full name. ex: "Anthony Edward Stark". The name parameter is required if verifying with bank details.
+    - number [string]: receiver bank account number. Use "-" before the verifier digit. ex: "876543-2". The number parameter is required if verifying with bank details.
+    - type [string]: verified account type. ex: "checking", "savings", "salary" or "payment". The type parameter is required if verifying with bank details.
+    ## Parameters (optional):
+    - tags [list of strings, default []]: list of strings for reference when searching for verified accounts. ex: ["employees", "monthly"]
+    ## Attributes (return-only):
+    - id [string]: unique id returned when the VerifiedAccount is created. ex: "5656565656565656"
+    - bank_name [string]: bank name associated with the verified account. ex: "Stark Bank"
+    - status [string]: current verified account status. ex: "creating", "created", "processing", "active", "failed" or "canceled"
+    - created [datetime.datetime]: creation datetime for the verified account. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0)
+    - updated [datetime.datetime]: latest update datetime for the verified account. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0)
+    """
+
+    def __init__(self, tax_id, bank_code=None, branch_code=None, key_id=None, name=None, number=None,
+                 type=None, tags=None, id=None, bank_name=None, status=None, created=None, updated=None):
+        Resource.__init__(self, id=id)
+
+        self.tax_id = tax_id
+        self.bank_code = bank_code
+        self.branch_code = branch_code
+        self.key_id = key_id
+        self.name = name
+        self.number = number
+        self.type = type
+        self.tags = tags
+        self.bank_name = bank_name
+        self.status = status
+        self.created = check_datetime(created)
+        self.updated = check_datetime(updated)
+
+
+_resource = {"class": VerifiedAccount, "name": "VerifiedAccount"}
+
+
+def create(verified_accounts, user=None):
+    """# Create VerifiedAccounts
+    Send a list of VerifiedAccount objects for creation in the Stark Bank API
+    ## Parameters (required):
+    - verified_accounts [list of VerifiedAccount objects]: list of VerifiedAccount objects to be created in the API
+    ## Parameters (optional):
+    - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call
+    ## Return:
+    - list of VerifiedAccount objects with updated attributes
+    """
+    return rest.post_multi(resource=_resource, entities=verified_accounts, user=user)
+
+
+def get(id, user=None):
+    """# Retrieve a specific VerifiedAccount
+    Receive a single VerifiedAccount object previously created in 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:
+    - VerifiedAccount object with updated attributes
+    """
+    return rest.get_id(resource=_resource, id=id, user=user)
+
+
+def cancel(id, user=None):
+    """# Cancel a VerifiedAccount entity
+    Cancel a VerifiedAccount entity previously created in the Stark Bank API
+    ## Parameters (required):
+    - id [string]: VerifiedAccount 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:
+    - canceled VerifiedAccount object
+    """
+    return rest.delete_id(resource=_resource, id=id, user=user)
+
+
+def query(limit=None, after=None, before=None, status=None, ids=None, tags=None, user=None):
+    """# Retrieve VerifiedAccounts
+    Receive a generator of VerifiedAccount 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 or updated only after specified date. ex: datetime.date(2020, 3, 10)
+    - before [datetime.date or string, default None]: date filter for objects created or updated only before specified date. ex: datetime.date(2020, 3, 10)
+    - status [string, default None]: filter for status of retrieved objects. ex: "creating", "created", "processing", "active", "failed" or "canceled"
+    - ids [list of strings, default None]: list of ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"]
+    - tags [list of strings, default None]: tags to filter retrieved objects. ex: ["tony", "stark"]
+    - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call
+    ## Return:
+    - generator of VerifiedAccount objects with updated attributes
+    """
+    return rest.get_stream(
+        resource=_resource,
+        limit=limit,
+        after=check_date(after),
+        before=check_date(before),
+        status=status,
+        ids=ids,
+        tags=tags,
+        user=user,
+    )
+
+
+def page(cursor=None, limit=None, after=None, before=None, status=None, ids=None, tags=None, user=None):
+    """# Retrieve paged VerifiedAccounts
+    Receive a list of up to 100 VerifiedAccount 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 or updated only after specified date. ex: datetime.date(2020, 3, 10)
+    - before [datetime.date or string, default None]: date filter for objects created or updated only before specified date. ex: datetime.date(2020, 3, 10)
+    - status [string, default None]: filter for status of retrieved objects. ex: "creating", "created", "processing", "active", "failed" or "canceled"
+    - ids [list of strings, default None]: list of ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"]
+    - tags [list of strings, default None]: tags to filter retrieved objects. ex: ["tony", "stark"]
+    - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call
+    ## Return:
+    - list of VerifiedAccount objects with updated attributes
+    - cursor to retrieve the next page of VerifiedAccount objects
+    """
+    return rest.get_page(
+        resource=_resource,
+        cursor=cursor,
+        limit=limit,
+        after=check_date(after),
+        before=check_date(before),
+        status=status,
+        ids=ids,
+        tags=tags,
+        user=user,
+    )

starkbank/verifiedaccount/log/__init__.py

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

starkbank/verifiedaccount/log/__log.py

@@ -0,0 +1,94 @@
+from ...utils import rest
+from starkcore.utils.api import from_api_json
+from starkcore.utils.resource import Resource
+from starkcore.utils.checks import check_datetime, check_date
+from ..__verifiedaccount import _resource as _verified_account_resource
+
+
+class Log(Resource):
+    """# verifiedaccount.Log object
+    Every time a VerifiedAccount entity is modified, a corresponding verifiedaccount.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"
+    - account [VerifiedAccount]: VerifiedAccount entity to which the log refers to.
+    - errors [list of strings]: list of errors linked to this VerifiedAccount event.
+    - type [string]: type of the VerifiedAccount event which triggered the log creation. ex: "created" or "processing"
+    - created [datetime.datetime]: creation datetime for the log. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0)
+    """
+
+    def __init__(self, id, created, type, errors, account):
+        Resource.__init__(self, id=id)
+
+        self.created = check_datetime(created)
+        self.type = type
+        self.errors = errors
+        self.account = from_api_json(_verified_account_resource, account)
+
+
+_resource = {"class": Log, "name": "VerifiedAccountLog"}
+
+
+def get(id, user=None):
+    """# Retrieve a specific verifiedaccount.Log
+    Receive a single verifiedaccount.Log 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:
+    - verifiedaccount.Log object with updated attributes
+    """
+    return rest.get_id(resource=_resource, id=id, user=user)
+
+
+def query(limit=None, after=None, before=None, types=None, account_ids=None, user=None):
+    """# Retrieve verifiedaccount.Logs
+    Receive a generator of verifiedaccount.Log 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)
+    - types [list of strings, default None]: filter retrieved objects by types. ex: "created" or "processing"
+    - account_ids [list of strings, default None]: list of VerifiedAccount ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"]
+    - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call
+    ## Return:
+    - generator of verifiedaccount.Log objects with updated attributes
+    """
+    return rest.get_stream(
+        resource=_resource,
+        limit=limit,
+        after=check_date(after),
+        before=check_date(before),
+        types=types,
+        account_ids=account_ids,
+        user=user,
+    )
+
+
+def page(cursor=None, limit=None, after=None, before=None, types=None, account_ids=None, user=None):
+    """# Retrieve paged verifiedaccount.Logs
+    Receive a list of up to 100 verifiedaccount.Log 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)
+    - types [list of strings, default None]: filter retrieved objects by types. ex: "created" or "processing"
+    - account_ids [list of strings, default None]: list of VerifiedAccount ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"]
+    - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call
+    ## Return:
+    - list of verifiedaccount.Log objects with updated attributes
+    - cursor to retrieve the next page of verifiedaccount.Log objects
+    """
+    return rest.get_page(
+        resource=_resource,
+        cursor=cursor,
+        limit=limit,
+        after=check_date(after),
+        before=check_date(before),
+        types=types,
+        account_ids=account_ids,
+        user=user,
+    )

starkbank/verifiedtransfer/__init__.py

@@ -0,0 +1 @@
+from .__verifiedtransfer import create