organizze_api 1.0.16

Python SDK for Organizze API - Manage your personal finances programmatically with type-safe access to bank accounts, transactions, budgets, categories, and credit cards

Organizze API - Python SDK

Auto-generated Python client library for the Organizze personal finance API.

This SDK provides type-safe access to your Organizze financial data, based on the official API documentation at https://github.com/organizze/api-doc.

Disclaimer

This package and its owner are not affiliated with Organizze and offer no guarantee with regards to API stability or reliability. For legal information about license and liabilities, please check the license file.

Requirements

• Python 3.9+
• Dependencies: urllib3, python-dateutil, pydantic, typing-extensions

Installation

From PyPI (Recommended)

pip install organizze_api

From Source

# Clone the repository
git clone https://github.com/BarretoTech/organizze-api-sdk.git
cd organizze-api-sdk/clients/python

# Install
pip install -e .

From Git

pip install git+https://github.com/BarretoTech/organizze-api-sdk.git#subdirectory=clients/python

Authentication

All Organizze API requests require:

1. HTTP Basic Authentication

   • Username: Your Organizze account email
   • Password: API token from https://app.organizze.com.br/configuracoes/api-keys

2. User-Agent Header (REQUIRED)

   • Format: ApplicationName ([e-mail])
   • Important: Omitting this header will result in 400 Bad Request errors

Quick Start

import organizze_api
from organizze_api.rest import ApiException

# Configure authentication
configuration = organizze_api.Configuration(
    host="https://api.organizze.com.br/rest/v2",
    username="[e-mail]",
    password="your_api_token"
)

# Set required User-Agent header
configuration.api_key['userAgent'] = 'MyApp ([e-mail])'

# Use the API
with organizze_api.ApiClient(configuration) as api_client:
    # List bank accounts
    bank_accounts_api = organizze_api.BankAccountsApi(api_client)
    accounts = bank_accounts_api.list_bank_accounts()
    print(accounts)

    # Create a transaction
    transactions_api = organizze_api.TransactionsApi(api_client)
    transaction = organizze_api.Transaction(
        description="Groceries",
        date="2025-01-15",
        amount_cents=-5000,  # negative for expenses, positive for income
        category_id=123,
        account_id=456
    )
    result = transactions_api.create_transaction(transaction)
    print(result)

Usage Examples

Managing Bank Accounts

import organizze_api

configuration = organizze_api.Configuration(
    host="https://api.organizze.com.br/rest/v2",
    username="[e-mail]",
    password="your_api_token"
)
configuration.api_key['userAgent'] = 'MyApp ([e-mail])'

with organizze_api.ApiClient(configuration) as api_client:
    api = organizze_api.BankAccountsApi(api_client)

    # List all bank accounts
    accounts = api.list_bank_accounts()

    # Read a specific bank account
    account = api.read_bank_account(bank_account_id=123)

    # Create a new bank account
    new_account = organizze_api.BankAccount(
        name="Savings Account",
        description="My savings"
    )
    created = api.create_bank_account(new_account)

    # Update a bank account
    updated = api.update_bank_account(
        bank_account_id=123,
        bank_account=organizze_api.BankAccount(name="Updated Name")
    )

    # Delete a bank account
    api.delete_bank_account(bank_account_id=123)

Working with Transactions

import organizze_api
from datetime import date

configuration = organizze_api.Configuration(
    host="https://api.organizze.com.br/rest/v2",
    username="[e-mail]",
    password="your_api_token"
)
configuration.api_key['userAgent'] = 'MyApp ([e-mail])'

with organizze_api.ApiClient(configuration) as api_client:
    api = organizze_api.TransactionsApi(api_client)

    # List all transactions
    transactions = api.list_transactions()

    # Create a transaction
    transaction = organizze_api.Transaction(
        description="Salary",
        date="2025-01-01",
        amount_cents=500000,  # R$ 5,000.00
        category_id=456,
        account_id=789
    )
    created = api.create_transaction(transaction)

    # Read a specific transaction
    transaction = api.read_transaction(transaction_id=123)

    # Update a transaction
    updated = api.update_transaction(
        transaction_id=123,
        transaction=organizze_api.Transaction(
            description="Updated description",
            amount_cents=-3000
        )
    )

    # Delete a transaction
    api.delete_transaction(transaction_id=123)

Managing Categories

import organizze_api

configuration = organizze_api.Configuration(
    host="https://api.organizze.com.br/rest/v2",
    username="[e-mail]",
    password="your_api_token"
)
configuration.api_key['userAgent'] = 'MyApp ([e-mail])'

with organizze_api.ApiClient(configuration) as api_client:
    api = organizze_api.CategoriesApi(api_client)

    # List all categories
    categories = api.list_categories()

    # Read a specific category
    category = api.read_category(category_id=123)

    # Create a new category
    new_category = organizze_api.Category(
        name="Entertainment",
        color="#FF5733"
    )
    created = api.create_category(new_category)

Working with Credit Cards

import organizze_api

configuration = organizze_api.Configuration(
    host="https://api.organizze.com.br/rest/v2",
    username="[e-mail]",
    password="your_api_token"
)
configuration.api_key['userAgent'] = 'MyApp ([e-mail])'

with organizze_api.ApiClient(configuration) as api_client:
    api = organizze_api.CreditCardsApi(api_client)

    # List all credit cards
    cards = api.list_credit_cards()

    # Read a specific credit card
    card = api.read_credit_card(credit_card_id=123)

    # List invoices for a credit card
    invoices = api.list_credit_card_invoices(credit_card_id=123)

    # Read a specific invoice
    invoice = api.read_credit_card_invoice(
        credit_card_id=123,
        credit_card_invoice_id=456
    )

    # List payments for an invoice
    payments = api.list_credit_card_invoice_payments(
        credit_card_id=123,
        credit_card_invoice_id=456
    )

Managing Budgets

import organizze_api

configuration = organizze_api.Configuration(
    host="https://api.organizze.com.br/rest/v2",
    username="[e-mail]",
    password="your_api_token"
)
configuration.api_key['userAgent'] = 'MyApp ([e-mail])'

with organizze_api.ApiClient(configuration) as api_client:
    api = organizze_api.BudgetsApi(api_client)

    # Get current month budgets
    current_budgets = api.list_current_month_budgets()

    # Get budgets for a specific month
    monthly_budgets = api.list_monthly_budgets(year=2025, month=1)

    # Get annual budgets
    annual_budgets = api.list_annual_budgets(year=2025)

Error Handling

import organizze_api
from organizze_api.rest import ApiException

configuration = organizze_api.Configuration(
    host="https://api.organizze.com.br/rest/v2",
    username="[e-mail]",
    password="your_api_token"
)
configuration.api_key['userAgent'] = 'MyApp ([e-mail])'

with organizze_api.ApiClient(configuration) as api_client:
    api = organizze_api.TransactionsApi(api_client)

    try:
        transaction = api.read_transaction(transaction_id=123)
        print(transaction)
    except ApiException as e:
        print(f"API Error: {e.status} - {e.reason}")
        print(f"Response body: {e.body}")

Features

This SDK supports the complete Organizze API, including:

• Bank Accounts - Create, list, update, and delete bank accounts
• Categories - Manage transaction categories
• Credit Cards - Manage credit cards, invoices, and payments
• Transactions - Create and manage transactions (single, recurring, and installments)
• Budgets - Track and manage monthly/yearly budgets
• Users - Access user information

Documentation for API Endpoints

All URIs are relative to https://api.organizze.com.br/rest/v2

Class	Method	HTTP request	Description
BankAccountsApi	create_bank_account	POST /accounts	Create Bank Account
BankAccountsApi	delete_bank_account	DELETE /accounts/{bankAccountID}	Delete Bank Account
BankAccountsApi	list_bank_accounts	GET /accounts	List Bank Accounts
BankAccountsApi	read_bank_account	GET /accounts/{bankAccountID}	Read Account
BankAccountsApi	update_bank_account	PUT /accounts/{bankAccountID}	Update Bank Account
BudgetsApi	list_annual_budgets	GET /budgets/{year}	Get Annual Budgets
BudgetsApi	list_current_month_budgets	GET /budgets	Get Current Month Budgets
BudgetsApi	list_monthly_budgets	GET /budgets/{year}/{month}	Get Monthly Budgets
CategoriesApi	create_category	POST /categories	Create Category
CategoriesApi	delete_category	DELETE /categories/{categoryID}	Delete Category
CategoriesApi	list_categories	GET /categories	List Categories
CategoriesApi	read_category	GET /categories/{categoryID}	Read Category
CategoriesApi	update_category	PUT /categories/{categoryID}	Update Category
CreditCardsApi	create_credit_card	POST /credit_cards	Create Credit Card
CreditCardsApi	delete_credit_card	DELETE /credit_cards/{creditCardID}	Delete Credit Card
CreditCardsApi	list_credit_card_invoice_payments	GET /credit_cards/{creditCardID}/invoices/{creditCardInvoiceID}/payments	List Credit Card Invoice Payments
CreditCardsApi	list_credit_card_invoices	GET /credit_cards/{creditCardID}/invoices	List Credit Card Invoices
CreditCardsApi	list_credit_cards	GET /credit_cards	List Credit Cards
CreditCardsApi	read_credit_card	GET /credit_cards/{creditCardID}	Read Credit Card
CreditCardsApi	read_credit_card_invoice	GET /credit_cards/{creditCardID}/invoices/{creditCardInvoiceID}	Read Credit Card Invoice
CreditCardsApi	update_credit_card	PUT /credit_cards/{creditCardID}	Update Credit Card
TransactionsApi	create_transaction	POST /transactions	Create Transaction
TransactionsApi	delete_transaction	DELETE /transactions/{transactionID}	Delete Transaction
TransactionsApi	list_transactions	GET /transactions	List Transactions
TransactionsApi	read_transaction	GET /transactions/{transactionID}	Read Transaction
TransactionsApi	update_transaction	PUT /transactions/{transactionID}	Update Transaction
UsersApi	list_users	GET /users	List Users
UsersApi	read_user	GET /users/{userID}	Read User

API Reference Documentation

API Classes

Detailed documentation for each API class:

• BankAccountsApi - Bank account operations (create, list, read, update, delete)
• BudgetsApi - Budget management operations (current month, monthly, annual)
• CategoriesApi - Category management operations (create, list, read, update, delete)
• CreditCardsApi - Credit card, invoice, and payment operations
• TransactionsApi - Transaction management operations (create, list, read, update, delete)
• UsersApi - User information operations

Data Models

Documentation for request/response types and models:

Core Models:

• BankAccount - Bank account data structure
• Budget - Budget data structure
• Category - Category data structure
• CreditCard - Credit card data structure
• CreditCardInvoice - Credit card invoice data structure
• CreditCardInvoiceFull - Complete invoice data with details
• Transaction - Transaction data structure
• User - User data structure

Transaction Types:

• InstallmentTransaction - Installment transaction structure
• InstallmentTransactionAllOfInstallmentsAttributes - Installment-specific attributes
• RecurringTransaction - Recurring transaction structure
• RecurringTransactionAllOfRecurrenceAttributes - Recurrence-specific attributes

Request/Response Models:

• CreateTransactionRequest - Transaction creation request
• UpdateTransactionRequest - Transaction update request
• DeleteTransactionRequest - Transaction deletion request

Error Models:

• FailedAuthentication - Authentication failure response
• NotFound - Resource not found response
• ValidationError - Validation error response

Important Notes

1. User-Agent Header: Always include a User-Agent header with your application name and contact email. Requests without this header will fail with a 400 error.

2. Amount Format: Transaction amounts are in cents (e.g., -5000 = -R$ 50.00). Use negative values for expenses and positive values for income.

3. Date Format: Dates should be in YYYY-MM-DD format (e.g., "2025-01-15").

4. Authentication: Keep your API token secure. Never commit it to version control or expose it in publicly accessible code.

5. Type Safety: This SDK uses Pydantic for data validation, providing runtime type checking and better IDE support.

Testing

Execute pytest to run the tests:

pytest

API Documentation

For more details about the Organizze API, visit:

• Official API Documentation: https://github.com/organizze/api-doc
• Get your API token: https://app.organizze.com.br/configuracoes/api-keys

Support

This is an auto-generated client library. For issues or contributions, please visit the main repository.

License

See the LICENSE file for details.