plutto 0.1.0

The official Python client for Plutto API

Plutto Python Client

This library will help you easily integrate Plutto API to your software, making your developer life a little bit more enjoyable.

---

Installation

Install using pip

$ pip3 install plutto

Note: This SDK requires Python 3.7+

Usage

With this SDK we want to provide a wrapper to the Plutto API with a very intuitive way of use. All the methods were implemented as in the API documentation, we strongly recommend to read it before using this SDK

Quickstart

First of all, you will need a [Plutto] account. After creating it, you can get your API key, which will let you to use the Plutto object. Then, you're ready to use this awesome SDK!

from plutto import Plutto

client = Plutto("your_api_key")

Managers

To manage the resources retrieved by the SDK we use managers. They are python objects that let you with any object inside Plutto API.. All the existing managers are inside the Plutto object. These are:

• customers
• invoices
• meter_events
• permission_groups
• products
• subscriptions

all

Note: this method is only available in customers, invoices, permission_groups and products managers

customers = client.customers.all()

This method returns a a generator with all the instances of the customers resource. But, what if the API can recive more params? kwargs to the rescue! This way you can pass params like q[status_eq] and q[customer_eq] to filter the Invoices. If you want to get invoices with an specific status and customer, you need to pass those params to the request

params = {
    "q[status_eq]": "paid",
    "q[customer_eq]": "customer_id"
}
invoices = client.invoices.all(**params)

Also, if you pass the lazy=False parameter, this will force the method of the SDK to return a list of the instances of the resource, instead of the generetors of them. Disclaimer: This could take very long if you have a lot of instances to be retrieved.

customers = client.customers.all(lazy=False)
isinstance(customers, list) # True

get

Note: this method is only available in customers and invoices managers

This method returns an instance of a resource using it's identifier to find it

customer = client.customers.get("customer_id")
isinstance(customer, Customer) # True

create

Note: this method is only available in customers, meter_events and subscriptions managers

This method creates and returns a new instance of the resource. The attributes of the resource to be created must be passed as kwargs. This parameters are specified in the API documentation of the correspondant resource

payload = {
    "identifier": "your-id_12885305",
    "email": "[e-mail]",
    "name": "Donald",
    "billing_information": {
        "city": "Santiago",
        "country_iso_code": "CL",
        "state": "Metropolitana",
        "address": "Av. Las Condes",
        "zip": "12345",
        "tax_id": "73245432-1",
        "legal_name": "Plutto Inc",
        "activity": "Software Development",
        "phone": "[phone]"
    }
}

customer = client.customer.create(**payload)

update

Note: this method is only available in customers manager

customer = client.cuestomers.update(
    "user_id",
    email="[e-mail]",
    name="Goofy"
)

This is an example of how can be used the update method. The first parameter corresponds to the id of the customer, this way the manager can find the existing resource. Then, the attributes that want to be modified are passed as kwargs, this ones are specified in the API in the correspondant resource update method. This manager method is making two calls to the Plutto API, the first, to get the resource, and the second to update it. Therefore, if you only want to make one API call and already got the reource python object, you can call update directly on the object

# Get the object
example_customer = client.customers.get("customer_id")

# Update the customer
example_customer.update(
    email="[e-mail]",
    name="Goofy"
)

This way, you can call update on the objects you are already working with, evitating to make an innescesary API call and saving some words

delete

Note: this method is only available in customers manager

deleted_customer_id = client.customers.delete("customer_id")

This method deletes an existing instance of a resource by it's identifier, and returns it. As in the update method, you can call delete on an resource object, for the same reasons explained in the previous method

# Get the resource
customer = client.customers.get("customer_id")

# Delete de resource
deleted_customer_id = customer.delete()

How to use this SDK

The way to use is very similar to the API. For all the methods you need the Plutto object

Plutto object

Instantiate the object using your secret API key

from plutto import Plutto

client = Plutto("secret_api_key")

This client will give you access to all the managers that are available in this SDK. That means you can work with any manager you want from this object

customers manager

Available methods: all, get, create, update and delete

From the Plutto object you can manage your customers easily. You can get all the customers that have been created

customers = client.customers.all()
for customer in customers:
    print(customer.name)

Also, if you have the id, you can get a singular customer

customer = client.customers.get("id_of_the_customer")

Need a new customer? Creating it is very intuitive, just pass the parameters specified in the docs as kwargs

payload = {
    "email": "[e-mail]",
    "name": "donald",
    "billing_information": {
        "city": "Santiago",
        "country_iso_code": "CL",
        "legal_name": "Plutto",
        "activity": "Software Development"
    }
}

new_customer = client.customers.create(**payload)

If any customers need to be updated, you can do it with it's id and pass the params you want to update as kwargs

update_params = {
    "name": "Goofy",
    "email": "[e-mail]"
}

updated_customer = client.customers.update("update_customer_id", **update_params)

# It can also be done this way
update_params = {
    "name": "Goofy",
    "email": "[e-mail]"
}

customer = client.customers.get("update_customer_id")
updated_customer = customer.update(**update_params)

Delete a customer can be done by passing it's id to the delete method

deleted_customer_id = client.customers.delete("delete_customer_id")

# It can also be done this way
customer = client.customers.get("delete_customer_id")
deleted_customer_id = customer.delete()

subscriptions manager

To create a new subscription through the manager you can do the following. The attributes must be passed as kwargs. Required and optional ones are specified in the docs

payload = {
    "customer_id": "example_customer_id",
    "pricing_ids": ["example_pricing_id_1", "example_pricing_id_2"]
    "bills_at": "start",
    "billing_period_duration": "P0Y1M0DT0H0M0S"
}
subscription = client.subscriptions.create(**payload)

To end a subscription you only need the id

subscription = client.subscriptions.end("subscription_id")

Adding a product pricing to a subscription

# pricing_ids can have only one item, but it must be a list
payload = {
    "pricing_ids": ["pricing_id_1", "pricing_id_2", "pricing_id_3"]
}

subscription = client.subscriptions.add_pricings("subscription_id", **payload)

To remove a pricing, you can do the following

# pricing_ids can have only one item, but it must be a list
payload = {
    "pricings_id": ["pricing_id_1", "pricing_id_2", "pricing_id_3"]
}

subscription = client.subscriptions.remove_pricings("subscription_id", **payload)

Serialization

Any resource retrieved by the SDK can be serialize, and it's super easy to do it. You just need to call the serialize method, and it's available in any resource

customer = client.customers.get("customer_id")
serialized_customer = customer.serialize()

serialized_customer corresponds to a dictionary with only the attributes of the retrieved resource. It can be JSON-serialized

Testing

All the tests must be added in the tests/ directory. To run the tests you nedd to execute the following command on the root path of the plutto library

pytest .

Every piece of code modified or added must be tested. The coverage always have to be increased or maintained, this will be checked in all PR

Publishing

On master/main branch...

1. Change VERSION in plutto//version.py.
2. Change Unreleased title to current version in CHANGELOG.md.
3. Commit new release. For example: Releasing v0.1.0.
4. Create tag. For example: git tag v0.1.0.
5. Push tag. For example: git push origin v0.1.0.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Credits

Thank you contributors!

Plutto Ruby SDK is maintained by Plutto.

Acknowledgments

This SDK was strongly based on the Fintoc python's SDK, designed by Daniel Leal

License

Plutto Python SDK is © 2021 plutto, spa. It is free software and may be redistributed under the terms specified in the LICENSE file.