Python库 | starkbank-2.5.0.tar.gz

# Stark Bank Python SDK Welcome to the Stark Bank Python SDK! This tool is made for Python developers who want to easily integrate with our API. This SDK version is compatible with the Stark Bank API v2. If you have no idea what Stark Bank is, check out our [website](https://www.starkbank.com/) and discover a world where receiving or making payments is as easy as sending a text message to your client! ## Supported Python Versions This library supports the following Python versions: * Python 2.7 * Python 3.4+ ## Stark Bank API documentation Feel free to take a look at our [API docs](https://www.starkbank.com/docs/api). ## Versioning This project adheres to the following versioning pattern: Given a version number MAJOR.MINOR.PATCH, increment: - MAJOR version when the **API** version is incremented. This may include backwards incompatible changes; - MINOR version when **breaking changes** are introduced OR **new functionalities** are added in a backwards compatible manner; - PATCH version when backwards compatible bug **fixes** are implemented. ## Setup ### 1. Install our SDK 1.1 To install the package with pip, run: ```sh pip install starkbank ``` 1.2 To install from source, clone the repo and run: ```sh python setup.py install ``` ### 2. Create your Private and Public Keys We use ECDSA. That means you need to generate a secp256k1 private key to sign your requests to our API, and register your public key with us so we can validate those requests. You can use one of following methods: 2.1. Check out the options in our [tutorial](https://starkbank.com/faq/how-to-create-ecdsa-keys). 2.2. Use our SDK: ```python import starkbank privateKey, publicKey = starkbank.key.create() # or, to also save .pem files in a specific path privateKey, publicKey = starkbank.key.create("file/keys/") ``` **NOTE**: When you are creating new credentials, it is recommended that you create the keys inside the infrastructure that will use it, in order to avoid risky internet transmissions of your **private-key**. Then you can export the **public-key** alone to the computer where it will be used in the new Project creation. ### 3. Register your user credentials You can interact directly with our API using two types of users: Projects and Organizations. - **Projects** are workspace-specific users, that is, they are bound to the workspaces they are created in. One workspace can have multiple Projects. - **Organizations** are general users that control your entire organization. They can control all your Workspaces and even create new ones. The Organization is bound to your company's tax ID only. Since this user is unique in your entire organization, only one credential can be linked to it. 3.1 To create a Project in Sandbox: 3.1.1. Log into [Starkbank Sandbox](https://web.sandbox.starkbank.com) 3.1.2. Go to Menu > Projects 3.1.3. Create a Project: Give it a name and upload the public key you created in section 2. 3.1.4. After creating the Project, get its Project ID 3.1.5. Use the Project ID and private key to create the object below: ```python import starkbank # Get your private key from an environment variable or an encrypted database. # This is only an example of a private key content. You should use your own key. private_key_content = """ -----BEGIN EC PARAMETERS----- BgUrgQQACg== -----END EC PARAMETERS----- -----BEGIN EC PRIVATE KEY----- MHQCAQEEIMCwW74H6egQkTiz87WDvLNm7fK/cA+ctA2vg/bbHx3woAcGBSuBBAAK oUQDQgAE0iaeEHEgr3oTbCfh8U2L+r7zoaeOX964xaAnND5jATGpD/tHec6Oe9U1 IF16ZoTVt1FzZ8WkYQ3XomRD4HS13A== -----END EC PRIVATE KEY----- """ project = starkbank.Project( environment="sandbox", id="5656565656565656", private_key=private_key_content ) ``` 3.2 To register your Organization's public key, a legal representative of your organization must send an e-mail with the desired public key to [email protected]. This flow will soon be integrated with our website, where you'll be able to do the entire process quicker and independently. Here is an example on how to handle your Organization in the SDK: ```python import starkbank # Get your private key from an environment variable or an encrypted database. # This is only an example of a private key content. You should use your own key. private_key_content = """ -----BEGIN EC PARAMETERS----- BgUrgQQACg== -----END EC PARAMETERS----- -----BEGIN EC PRIVATE KEY----- MHQCAQEEIMCwW74H6egQkTiz87WDvLNm7fK/cA+ctA2vg/bbHx3woAcGBSuBBAAK oUQDQgAE0iaeEHEgr3oTbCfh8U2L+r7zoaeOX964xaAnND5jATGpD/tHec6Oe9U1 IF16ZoTVt1FzZ8WkYQ3XomRD4HS13A== -----END EC PRIVATE KEY----- """ organization = starkbank.Organization( environment="sandbox", id="5656565656565656", private_key=private_key_content, workspace_id=None, # You only need to set the workspace_id when you are operating a specific workspace_id ) # To dynamically use your organization credentials in a specific workspace_id, # you can use the Organization.replace() function: starkbank.balance.get(user=starkbank.Organization.replace(organization, "4848484848484848")) ``` NOTE 1: Never hard-code your private key. Get it from an environment variable or an encrypted database. NOTE 2: We support `'sandbox'` and `'production'` as environments. NOTE 3: The credentials you registered in `sandbox` do not exist in `production` and vice versa. ### 4. Setting up the user There are three kinds of users that can access our API: **Organization**, **Project** and **Member**. - `Project` and `Organization` are designed for integrations and are the ones meant for our SDKs. - `Member` is the one you use when you log into our webpage with your e-mail. There are two ways to inform the user to the SDK: 4.1 Passing the user as argument in all functions: ```python import starkbank balance = starkbank.balance.get(user=project) # or organization ``` 4.2 Set it as a default user in the SDK: ```python import starkbank starkbank.user = project # or organization balance = starkbank.balance.get() ``` Just select the way of passing the user that is more convenient to you. On all following examples we will assume a default user has been set. ### 5. Setting up the error language The error language can also be set in the same way as the default user: ```python import starkbank starkbank.language = "en-US" ``` Language options are "en-US" for english and "pt-BR" for brazilian portuguese. English is default. ## Testing in Sandbox Your initial balance is zero. For many operations in Stark Bank, you'll need funds in your account, which can be added to your balance by creating an Invoice or a Boleto. In the Sandbox environment, most of the created Invoices and Boletos will be automatically paid, so there's nothing else you need to do to add funds to your account. Just create a few Invoices and wait around a bit. In Production, you (or one of your clients) will need to actually pay this Invoice or Boleto for the value to be credited to your account. ## Usage Here are a few examples on how to use the SDK. If you have any doubts, use the built-in `help()` function to get more info on the desired functionality (for example: `help(starkbank.boleto.create)`) ### Create transactions To send money between Stark Bank accounts, you can create transactions: ```python import starkbank transactions = starkbank.transaction.create([ starkbank.Transaction( amount=100, # (R$ 1.00) receiver_id="1029378109327810", description="Transaction to dear provider", external_id="12345", # so we can block anything you send twice by mistake tags=["provider"] ), starkbank.Transaction( amount=234, # (R$ 2.34) receiver_id="2093029347820947", description="Transaction to the other provider", external_id="12346", # so we can block anything you send twice by mistake tags=["provider"] ), ]) for transaction in transactions: print(transaction) ``` **Note**: Instead of using Tran