docs: carry the business rules the API reference states

CHANGELOG.md

@@ -13,6 +13,8 @@ Given a version number MAJOR.MINOR.PATCH, increment:
 
 
 ## [Unreleased]
+### Fixed
+- Docstrings
 
 ## [2.35.0] - 2026-06-29
 ### Added

README.md

@@ -2265,8 +2265,7 @@ import starkbank
 withdrawal = starkbank.corporatewithdrawal.create(
     withdrawal=starkbank.CorporateWithdrawal(
         amount=10000,
-        external_id="123",
-        description="Sending back"
+        external_id="123"
     )
 )
 

starkbank/boleto/__boleto.py

@@ -23,11 +23,11 @@ class Boleto(Resource):
     - fine [float, default 2.0]: Boleto fine for overdue payment in %. ex: 2.5
     - interest [float, default 1.0]: Boleto monthly interest for overdue payment in %. ex: 5.2
     - overdue_limit [integer, default 59]: limit in days for payment after due date. ex: 7 (max: 59)
-    - descriptions [list of dictionaries, default None]: list of dictionaries with "text":string and (optional) "amount":int pairs
-    - discounts [list of dictionaries, default None]: list of dictionaries with "percentage":float and "date":datetime.datetime or string pairs
+    - descriptions [list of dictionaries, default None]: list of up to 15 dictionaries with "text":string and (optional) "amount":int pairs. If the "booklet" PDF layout is used, only the text of the first description is shown, filling the installment cell.
+    - discounts [list of dictionaries, default None]: list of up to 2 dictionaries with "percentage":float and "date":datetime.datetime or string pairs
     - tags [list of strings]: list of strings for tagging
-    - receiver_name [string]: receiver (Sacador Avalista) full name. ex: "Anthony Edward Stark"
-    - receiver_tax_id [string]: receiver (Sacador Avalista) tax ID (CPF or CNPJ) with or without formatting. ex: "01234567890" or "20.018.183/0001-80"
+    - receiver_name [string, default None]: receiver (Sacador Avalista) full name. If omitted, the workspace owner's name is used. Must be informed together with receiver_tax_id. ex: "Anthony Edward Stark"
+    - receiver_tax_id [string, default None]: receiver (Sacador Avalista) tax ID. If omitted, the workspace owner's tax ID is used. Must be informed together with receiver_name. ex: "01234567890" or "20.018.183/0001-80"
     ## Attributes (return-only):
     - id [string]: unique id returned when Boleto is created. ex: "5656565656565656"
     - fee [integer]: fee charged when Boleto is paid. ex: 200 (= R$ 2.00)
@@ -79,7 +79,7 @@ def __init__(self, amount, name, tax_id, street_line_1, street_line_2, district,
 
 def create(boletos, user=None):
     """# Create Boletos
-    Send a list of Boleto objects for creation in the Stark Bank API
+    Send a list of Boleto objects for creation in the Stark Bank API. You can create up to 100 Boletos per call. If a Boleto is paid after its due date with fine, interest or a discount applied, its amount attribute is updated to reflect the amount actually paid.
     ## Parameters (required):
     - boletos [list of Boleto objects]: list of Boleto objects to be created in the API
     ## Parameters (optional):
@@ -105,7 +105,7 @@ def get(id, user=None):
 
 def pdf(id, layout=None, hidden_fields=None, user=None):
     """# Retrieve a specific Boleto pdf file
-    Receive a single Boleto pdf file generated in the Stark Bank API by its id.
+    Receive a single Boleto pdf file generated in the Stark Bank API by its id. This route is public and needs no authentication, but repeated requests for invalid ids will get your IP blocked from this route.
     ## Parameters (required):
     - id [string]: object unique id. ex: "5656565656565656"
     ## Parameters (optional):
@@ -176,7 +176,7 @@ def page(cursor=None, limit=None, status=None, tags=None, ids=None, after=None,
 
 def delete(id, user=None):
     """# Delete a Boleto entity
-    Delete a Boleto entity previously created in the Stark Bank API
+    Delete a Boleto entity previously created in the Stark Bank API. A cancellation request is sent to CIP; once canceled, the Boleto can no longer be paid. This action cannot be undone.
     ## Parameters (required):
     - id [string]: Boleto unique id. ex: "5656565656565656"
     ## Parameters (optional):

starkbank/boletopayment/__boletopayment.py

@@ -17,7 +17,7 @@ class BoletoPayment(Resource):
     ## Parameters (optional):
     - amount [int, default None]: amount to be paid. If none is informed, the current boleto value will be used. ex: 23456 (= R$ 234.56)
     - scheduled [datetime.date or string, default today]: payment scheduled date. ex: datetime.date(2020, 3, 10)
-    - tags [list of strings]: list of strings for tagging
+    - tags [list of strings, default None]: list of strings for tagging. All tags will be converted to lowercase.
     ## Attributes (return-only):
     - id [string]: unique id returned when payment is created. ex: "5656565656565656"
     - status [string]: current payment status. ex: "success" or "failed"
@@ -74,7 +74,7 @@ def get(id, user=None):
 def pdf(id, user=None):
     """# Retrieve a specific BoletoPayment pdf file
     Receive a single BoletoPayment pdf file generated in the Stark Bank API by its id.
-    Only valid for boleto payments with "success" status.
+    Only valid for boleto payments with "success", "processing" or "created" status.
     ## Parameters (required):
     - id [string]: object unique id. ex: "5656565656565656"
     ## Parameters (optional):
@@ -143,7 +143,7 @@ def page(cursor=None, limit=None, after=None, before=None, tags=None, ids=None,
 
 def delete(id, user=None):
     """# Delete a BoletoPayment entity
-    Delete a BoletoPayment entity previously created in the Stark Bank API
+    Cancel a BoletoPayment entity previously created in the Stark Bank API. This only cancels payments that have not yet started processing; payments already processed can still be deleted, but the payment itself is not reversed.
     ## Parameters (required):
     - id [string]: BoletoPayment unique id. ex: "5656565656565656"
     ## Parameters (optional):

starkbank/brcodepayment/__brcodepayment.py

@@ -20,7 +20,7 @@ class BrcodePayment(Resource):
     - amount [int, default None]: If the BRCode does not provide an amount, this parameter is mandatory, else it is optional. ex: 23456 (= R$ 234.56)
     ## Parameters (optional):
     - scheduled [datetime.date, datetime.datetime or string, default now]: payment scheduled date or datetime. ex: datetime.datetime(2020, 3, 10, 15, 17, 3)
-    - tags [list of strings, default []]: list of strings for tagging
+    - tags [list of strings, default []]: list of strings for tagging. All tags will be converted to lowercase.
     - rules [list of BrcodePayment.Rule, default []]: list of BrcodePayment.Rule objects for modifying payment behavior. ex: [Rule(key="resendingLimit", value=5)]
     ## Attributes (return-only):
     - id [string]: unique id returned when payment is created. ex: "5656565656565656"
@@ -70,7 +70,7 @@ def _parse_rules(rules):
 
 def create(payments, user=None):
     """# Create BrcodePayments
-    Send a list of BrcodePayment objects for creation in the Stark Bank API
+    Send a list of BrcodePayment objects for creation in the Stark Bank API. Because processing is asynchronous, the amount attribute of a freshly created BrcodePayment will initially be zero.
     ## Parameters (required):
     - payments [list of BrcodePayment objects]: list of BrcodePayment objects to be created in the API
     ## Parameters (optional):
@@ -96,7 +96,7 @@ def get(id, user=None):
 
 def pdf(id, user=None):
     """# Retrieve a specific BrcodePayment pdf file
-    Receive a single BrcodePayment pdf receipt file generated in the Stark Bank API by its id.
+    Receive a single BrcodePayment pdf receipt file generated in the Stark Bank API by its id. Only valid for brcode payments with "success", "processing" or "created" status.
     ## Parameters (required):
     - id [string]: object unique id. ex: "5656565656565656"
     ## Parameters (optional):

starkbank/darfpayment/__darfpayment.py

@@ -20,7 +20,7 @@ class DarfPayment(Resource):
     ## Parameters (optional):
     - reference_number [string]: number assigned to the region of the tax. ex: "08.1.17.00-4"
     - scheduled [datetime.date or string, default today]: payment scheduled date. ex: datetime.date(2021, 5, 10)
-    - tags [list of strings]: list of strings for tagging
+    - tags [list of strings, default None]: list of strings for tagging. All tags will be converted to lowercase.
     ## Attributes (return-only):
     - id [string]: unique id returned when payment is created. ex: "5656565656565656"
     - status [string]: current payment status. ex: "success" or "failed"
@@ -86,7 +86,7 @@ def get(id, user=None):
 def pdf(id, user=None):
     """# Retrieve a specific DarfPayment pdf file
     Receive a single DarfPayment pdf file generated in the Stark Bank API by passing its id.
-    Only valid for darf payments with "success" status.
+    Only valid for darf payments with "success", "processing" or "created" status.
     ## Parameters (required):
     - id [string]: object unique id. ex: "5656565656565656"
     ## Parameters (optional):
@@ -155,7 +155,7 @@ def page(cursor=None, limit=None, after=None, before=None, tags=None, ids=None,
 
 def delete(id, user=None):
     """# Delete a DarfPayment entity
-    Delete a DarfPayment entity previously created in the Stark Bank API
+    Delete a DarfPayment entity previously created in the Stark Bank API. This only cancels payments that have not yet started processing; payments already processed can still be deleted, but are not reversed.
     ## Parameters (required):
     - id [string]: DarfPayment unique id. ex: "5656565656565656"
     ## Parameters (optional):

starkbank/deposit/__deposit.py

@@ -126,8 +126,8 @@ def update(id, amount=None, user=None):
     Update the Deposit by passing its id to be partially or fully reversed.
     ## Parameters (required):
     - id [string]: Deposit id. ex: "5656565656565656"
+    - amount [integer]: the new amount of the Deposit, in cents. Required -- pass 0 to fully reverse the Deposit.
     ## Parameters (optional):
-    - amount [string, default None]: The new amount of the Deposit. If the amount = 0 the Deposit will be fully reversed
     - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call
     ## Return:
     - target Deposit with updated attributes

starkbank/dictkey/__dictkey.py

@@ -7,7 +7,7 @@
 class DictKey(Resource):
 
     """# DictKey object
-    DictKey represents a PIX key registered in Bacen's DICT system.
+    DictKey represents a PIX key registered in Bacen's DICT system. An EVP (random) DictKey is automatically created for every new Workspace, since an active DICT key is required for the Invoice service to work.
     ## Parameters (optional):
     - id [string]: DictKey object unique id. ex: "tony@starkbank.com", "722.461.430-04", "20.018.183/0001-80", "+5511988887777", "b6295ee1-f054-47d1-9e90-ee57b74f60d9"
     ## Attributes (return-only):
@@ -44,7 +44,7 @@ def __init__(self, id=None, type=None, name=None, tax_id=None, owner_type=None,
 
 def get(id, user=None):
     """# Retrieve a specific DictKey
-    Receive a single DictKey object by its id
+    Receive a single DictKey object by its id. This includes keys you do not own, and can be used to check a key before creating a Transfer to it. Avoid looking up keys without following up with a transfer: Bacen blocks accounts that make too many standalone lookups in a short time, and invalid-key lookups count toward the block too. The returned encrypted branch_code/account_number can be passed straight into a Transfer without decrypting them.
     ## Parameters (required):
     - id [string]: DictKey object unique id and PIX key itself. ex: "tony@starkbank.com", "722.461.430-04", "20.018.183/0001-80", "+5511988887777", "b6295ee1-f054-47d1-9e90-ee57b74f60d9"
     ## Parameters (optional):

starkbank/dynamicbrcode/__dynamicbrcode.py

@@ -8,7 +8,18 @@
 
 class DynamicBrcode(Resource):
     """# DynamicBrcode object
-    Check out our API Documentation at https://starkbank.com/docs/api#dynamic-brcode
+    When you initialize a DynamicBrcode, the entity will not be automatically sent to the Stark Bank API. The 'create' function sends the objects to the Stark Bank API and returns the list of created objects. When a Dynamic Brcode is paid, a Deposit is created with a tag containing "dynamic-brcode/{uuid}" for conciliation.
+    ## Parameters (required):
+    - amount [integer]: amount in cents to be received. ex: 100 (= R$ 1.00)
+    ## Parameters (optional):
+    - expiration [integer or datetime.timedelta, default 3600 (1 hour)]: time interval in seconds counted from creation until the brcode expires. After expiration, the brcode cannot be paid anymore.
+    - display_description [string, default None]: description shown in the payer's bank interface. ex: "Payment for service #1234"
+    - rules [list of DynamicBrcode.Rule, default []]: list of DynamicBrcode.Rule objects for modifying brcode behavior.
+    - tags [list of strings, default []]: list of strings for tagging. All tags will be converted to lowercase.
+    ## Attributes (return-only):
+    - id / uuid [string]: unique ids returned when the DynamicBrcode is created.
+    - picture_url [string]: public QR Code image URL.
+    - updated / created [datetime.datetime]: update/creation datetimes.
     """
 
     def __init__(self, amount, expiration=None, tags=None, display_description=None, rules=None, id=None, uuid=None,

starkbank/event/__event.py

@@ -122,7 +122,7 @@ def page(cursor=None, limit=None, after=None, before=None, is_delivered=None, us
 
 def delete(id, user=None):
     """# Delete a webhook Event entity
-    Delete a of notification Event entity previously created in the Stark Bank API by its ID
+    Delete a notification Event entity previously created in the Stark Bank API by its ID. This action cannot be undone.
     ## Parameters (required):
     - id [string]: Event unique id. ex: "5656565656565656"
     ## Parameters (optional):
@@ -138,7 +138,7 @@ def update(id, is_delivered, user=None):
     Update notification Event by passing id.
     If is_delivered is True, the event will no longer be returned on queries with is_delivered=False.
     ## Parameters (required):
-    - id [list of strings]: Event unique ids. ex: "5656565656565656"
+    - id [string]: Event unique id. ex: "5656565656565656"
     - is_delivered [bool]: If True and event hasn't been delivered already, event will be set as delivered. ex: True
     ## Parameters (optional):
     - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call

starkbank/invoice/__invoice.py

@@ -16,19 +16,19 @@ class Invoice(Resource):
     To create scheduled Invoices, which will display the discount, interest, etc. on the final users banking interface,
     use dates instead of datetimes on the "due" and "discounts" fields.
     ## Parameters (required):
-    - amount [integer]: Invoice value in cents. Minimum = 0 (any value will be accepted). ex: 1234 (= R$ 12.34)
+    - amount [integer]: Invoice value in cents. Minimum = 0 (any value will be accepted). ex: 1234 (= R$ 12.34). If amount = 0, the Invoice will accept any amount paid by the customer; otherwise, only the exact amount will be accepted. When paid, this attribute is updated with the amount actually paid.
     - tax_id [string]: payer tax ID (CPF or CNPJ) with or without formatting. ex: "01234567890" or "20.018.183/0001-80"
     - name [string]: payer name. ex: "Iron Bank S.A."
     ## Parameters (optional):
     - due [datetime.datetime or datetime.date or string, default now + 2 days]: Invoice due date in UTC ISO format. ex: "2020-10-28T17:59:26.249976+00:00" for immediate invoices and "2020-10-28" for scheduled invoices
-    - expiration [integer or datetime.timedelta, default 5097600 (59 days)]: time interval in seconds between due date and expiration date. ex 123456789
+    - expiration [integer or datetime.timedelta, default 5097600 (59 days)]: time interval in seconds between due date and expiration date. After the expiration, the Invoice can no longer be paid. ex 123456789
     - fine [float, default 2.0]: Invoice fine for overdue payment in %. ex: 2.5
     - 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
+    - discounts [list of dictionaries, default []]: list of up to 5 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
+    - tags [list of strings, default []]: list of strings for tagging. All tags will be converted to lowercase.
+    - descriptions [list of dictionaries, default []]: list of up to 15 dictionaries with "key":string and (optional) "value":string pairs
     ## Attributes (return-only):
     - pdf [string]: public Invoice PDF URL. ex: "https://invoice.starkbank.com/pdf/d454fa4e524441c1b0c1a729457ed9d8"
     - link [string]: public Invoice webpage URL. ex: "https://my-workspace.sandbox.starkbank.com/invoicelink/d454fa4e524441c1b0c1a729457ed9d8"
@@ -106,7 +106,7 @@ def _parse_splits(splits):
 
 def create(invoices, user=None):
     """# Create Invoices
-    Send a list of Invoice objects for creation in the Stark Bank API
+    Send a list of Invoice objects for creation in the Stark Bank API. You can create up to 100 Invoices per call.
     ## Parameters (required):
     - invoices [list of Invoice objects]: list of Invoice objects to be created in the API
     ## Parameters (optional):
@@ -188,12 +188,12 @@ def page(cursor=None, limit=None, status=None, tags=None, ids=None, after=None,
 
 def update(id, status=None, amount=None, due=None, expiration=None, user=None):
     """# Update Invoice entity
-    Update an Invoice by passing id, if it hasn't been paid yet.
+    Update an Invoice by passing its id. If the invoice hasn't been paid yet, you can adjust parameters such as the amount, due date and expiration; if it has already been paid, you may only decrease the amount, which triggers a payment reversal.
     ## Parameters (required):
     - id [string]: Invoice id. ex: '5656565656565656'
     ## Parameters (optional):
     - status [string]: You may cancel the invoice by passing 'canceled' in the status
-    - amount [string]: Nominal amount charged by the invoice. ex: 100 (R$1.00)
+    - amount [string, default None]: new amount to be charged. If the Invoice has already been paid, this is the final amount after reversal. ex: 100 (R$1.00)
     - due [datetime.datetime or string, default now + 2 days]: Invoice due date in UTC ISO format. ex: "2020-10-28T17:59:26.249976+00:00"
     - expiration [integer or datetime.timedelta, default None]: time interval in seconds between the due date and the expiration date. ex 123456789
     - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user was set before function call