cashctrl_api
is a lightweight Python package that implements the
CashCtrlClient class for interactions with the
CashCtrl REST API.
This API serves CashCtrl, a straightforward and
effective online accounting software with a clean data model and a clear
REST API. Our package acts as a thin wrapper, efficiently routing requests
through universal methods to the API without the need for implementing
individual endpoints.
CashCtrlClient
provides generic methods to transmit typical requests:
get()
, post()
, patch()
, put()
, and delete()
take an API endpoint
,
request parameters, and a JSON payload as arguments, and return the server's
response as a JSON dictionary.Specialized methods manage categories and files:
list_categories()
retrieves a category tree and flattens it into a pandas
DataFrame.update_categories()
updates a category tree on the server with a given
list of category paths, adding new categories and optionally removing
those that are no longer needed.list_files()
lists remote files, their attributes, and Unix-style path
representations of their hierarchical position in the category tree.list_tax_rates()
List remote tax rates with their attributes.list_accounts()
List remote accounts with their attributes, and
Unix-style path representation of their hierarchical position in the
category tree.list_journal_entries()
List remote journal entries with their attributes.upload_file()
uploads a file from the local file system to the server,
and optionally replaces an existing remote file.download_file()
downloads a file from the server and saves it to the local
file system.mirror_files()
mirrors a local set of nested categories with the category
tree on the server, mapping local sub-folders to categories on the remote
server.An active Pro subscription is required to interact with your CashCtrl account via the API. New users can explore the Pro version with a free 30-day trial. Software developers can create a new test account when the trial period expires, as they generally do not mind the data loss associated with switching accounts.
To set up a free test account, follow these steps:
The organization name and API key will be used to authenticate API requests.
Easily install the package using pip:
pip install https://github.com/macxred/cashctrl_api/tarball/main
Get started with the CashCtrl API client by following these steps:
from cashctrl_api import CashCtrlClient
# Initialize the client with your organization's name and API key
cc_client = CashCtrlClient("<my_organisation>", api_key="<my_api_key>")
# Example: Create a new contact
contact = {
"firstName": "Tina",
"lastName": "Test",
"addresses": [{
"type": "MAIN",
"address": "Teststreet 15",
"zip": "1234",
"city": "Testtown"
}],
"titleId": 2
}
response = cc_client.post("person/create.json", data=contact)
id = response["insertId"]
# Retrieve the newly created contact
response = cc_client.get("person/read.json", params={'id': id})
print(response)
# Delete the contact
response = cc_client.post("person/delete.json", params={'ids': id})
print(response)
For simplicity, API Key and organization can also be set as environment
variables CC_API_KEY
and CC_API_ORGANISATION
. For example, by setting both
variables in the shell when starting python:
CC_API_ORGANISATION=<myorg> CC_API_KEY=<mykey> python
This allows for an even simpler code snippet:
from cashctrl_api import CashCtrlClient
cc_client = CashCtrlClient()
response = cc_client.get("person/list.json")
See CONTRIBUTING.md for: