Package: plutto
Plutto Python ClientThis library will help you easily integrate Plutto API to your software, making your developer life a little bit more enjoyable.InstallationInstall using pip$pip3installpluttoNote:This SDK requiresPython 3.7+UsageWith this SDK we want to provide a wrapper to thePlutto APIwith 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 SDKQuickstartFirst of all, you will need a [Plutto] account. After creating it, you can get your API key, which will let you to use thePluttoobject. Then, you're ready to use this awesome SDK!frompluttoimportPluttoclient=Plutto("your_api_key")ManagersTo 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 existingmanagersare inside thePluttoobject. These are:customersinvoicesmeter_eventspermission_groupsproductssubscriptionsallNote: this method is only available incustomers,invoices,permission_groupsandproductsmanagerscustomers=client.customers.all()This method returns aa generatorwith all the instances of the customers resource. But, what if the API can recive more params?kwargsto the rescue! This way you can pass params likeq[status_eq]andq[customer_eq]to filter theInvoices. If you want to getinvoiceswith an specificstatusandcustomer, you need to pass those params to the requestparams={"q[status_eq]":"paid","q[customer_eq]":"customer_id"}invoices=client.invoices.all(**params)Also, if you pass thelazy=Falseparameter, 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)# TruegetNote: this method is only available incustomersandinvoicesmanagersThis method returns an instance of a resource using it's identifier to find itcustomer=client.customers.get("customer_id")isinstance(customer,Customer)# TruecreateNote: this method is only available incustomers,meter_eventsandsubscriptionsmanagersThis method creates and returns a new instance of the resource. The attributes of the resource to be created must be passed askwargs. This parameters are specified in the API documentation of the correspondant resourcepayload={"identifier":"your-id_12885305","email":"donald@getplutto.com","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":"+56912345678"}}customer=client.customer.create(**payload)updateNote: this method is only available incustomersmanagercustomer=client.cuestomers.update("user_id",email="goofy@getplutto.com",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 askwargs, 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 objectexample_customer=client.customers.get("customer_id")# Update the customerexample_customer.update(email="goofy@getplutto.com",name="Goofy")This way, you can callupdateon the objects you are already working with, evitating to make an innescesary API call and saving some wordsdeleteNote: this method is only available incustomersmanagerdeleted_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 theupdatemethod, you can calldeleteon an resource object, for the same reasons explained in the previous method# Get the resourcecustomer=client.customers.get("customer_id")# Delete de resourcedeleted_customer_id=customer.delete()How to use this SDKThe way to use is very similar to the API. For all the methods you need thePluttoobjectPluttoobjectInstantiate the object using your secret API keyfrompluttoimportPluttoclient=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 anymanageryou want from this objectcustomersmanagerAvailable methods:all,get,create,updateanddeleteFrom thePluttoobject you can manage yourcustomerseasily. You can get all the customers that have been createdcustomers=client.customers.all()forcustomerincustomers:print(customer.name)Also, if you have the id, you can get a singular customercustomer=client.customers.get("id_of_the_customer")Need a new customer? Creating it is very intuitive, just pass theparameters specified in the docsas kwargspayload={"email":"donald@getplutto.com","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 kwargsupdate_params={"name":"Goofy","email":"goofy@getplutto.com"}updated_customer=client.customers.update("update_customer_id",**update_params)# It can also be done this wayupdate_params={"name":"Goofy","email":"goofy@getplutto.com"}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 thedeletemethoddeleted_customer_id=client.customers.delete("delete_customer_id")# It can also be done this waycustomer=client.customers.get("delete_customer_id")deleted_customer_id=customer.delete()invoicesmanagerAvailable methods:all,getandmark_asTo get all the existing invoices you can do the followinginvoices=client.invoices.all()forinvoiceininvoices:print(invoice.id)# If filtering by params is neededparams={"q[status_eq]":"paid","q[customer_eq]":"customer_id"}invoices=client.invoices.all(**params)To get a specific invoice, you can use it's idinovice=client.invoices.get("invoice_id")It's possible to change an invoice status through the manager. The possible status arespecified in the docsinvoice=client.invoices.mark_as("invoice_id",status="paid")meter_eventsmanagerAvailable methods: OnlycreateIt's possible to create a meter event this waypayload={"customer_id":"example_customer_id","meter_id":"example_meter_id","amout":100,"action":"set"}meter_event=client.meter_events.create(**payload)permission_groupsmanagerAvailable methods: OnlyallYou can get all the permission groups as followspermission_groups=client.permission_groups.all()forpermission_groupinpermission_groups:print(permission_group.name)productsmanagerAvailable methods: OnlyallYou can get all the products as followsproducts=client.products.all()forproductinproducts:print(product.name)subscriptionsmanagerTo create a new subscription through the manager you can do the following. The attributes must be passed as kwargs. Required and optional ones arespecified in the docspayload={"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 idsubscription=client.subscriptions.end("subscription_id")Adding a product pricing to a subscription# pricing_ids can have only one item, but it must be a listpayload={"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 listpayload={"pricings_id":["pricing_id_1","pricing_id_2","pricing_id_3"]}subscription=client.subscriptions.remove_pricings("subscription_id",**payload)SerializationAny resource retrieved by the SDK can be serialize, and it's super easy to do it. You just need to call theserializemethod, and it's available in any resourcecustomer=client.customers.get("customer_id")serialized_customer=customer.serialize()serialized_customercorresponds to a dictionary with only the attributes of the retrieved resource. It can be JSON-serializedTestingAll the tests must be added in thetests/directory. To run the tests you nedd to execute the following command on the root path of the plutto librarypytest.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 PRPublishingOn master/main branch...ChangeVERSIONinplutto/version.py.ChangeUnreleasedtitle to current version inCHANGELOG.md.Commit new release. For example:Releasing v0.1.0.Create tag. For example:git tag v0.1.0.Push tag. For example:git push origin v0.1.0.ContributingFork itCreate your feature branch (git checkout -b my-new-feature)Commit your changes (git commit -am 'Add some feature')Push to the branch (git push origin my-new-feature)Create new Pull RequestCreditsThank youcontributors!Plutto Ruby SDK is maintained byPlutto.AcknowledgmentsThis SDK was strongly based on theFintoc python's SDK, designed byDaniel LealLicensePlutto Python SDK is © 2021 plutto, spa. It is free software and may be redistributed under the terms specified in the LICENSE file.