Organizze API SDK

Auto-generated client libraries for the Organizze API, simplifying integration with your personal finance data.

This repository provides type-safe, well-documented client libraries in multiple languages, based on the official Organizze API documentation. These SDKs handle authentication, request formatting, and response parsing, allowing you to focus on building your application.

Disclaimer

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

Important Notice

Note: While the official Organizze API documentation describes the available endpoints, some specifications in this repository's specs/openapi.yaml may not align perfectly with the official documentation. This is because the official documentation can become outdated over time.

The OpenAPI specification in this repository has been refined based on real-world API testing and may include corrections, additional constraints, or updated field definitions that better reflect the actual API behavior. When in doubt, the OpenAPI specification in this repository should be considered more accurate for implementation purposes.

Available Clients

Language	Status	Package	Source
Javascript/Typescript	✅	NPM	clients/typescript
Python	✅	PyPI	clients/python

Features

All clients support the complete Organizze API, including:

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

Installation & Usage

TypeScript

Installation

npm install organizze-api-sdk

Usage

import {
  Configuration,
  BankAccountsApi,
  TransactionsApi,
} from "organizze-api-sdk";

// Configure authentication
const config = new Configuration({
  basePath: "https://api.organizze.com.br/rest/v2",
  username: "your.email@example.com",
  password: "your_api_token",
  headers: {
    "User-Agent": "MyApp (your.email@example.com)",
  },
});

// List bank accounts
const bankAccountsApi = new BankAccountsApi(config);
const accounts = await bankAccountsApi.listBankAccounts();

// Create a transaction
const transactionsApi = new TransactionsApi(config);
const transaction = await transactionsApi.createTransaction({
  description: "Groceries",
  date: "2025-12-12",
  amount_cents: -5000,
  category_id: 123,
  account_id: 456,
});

Python

Installation

# From PyPI (recommended)
pip install organizze_api

# Or from source
cd clients/python
pip install -e .

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

Usage

import organizze_api
from organizze_api.rest import ApiException

# Configure authentication
configuration = organizze_api.Configuration(
    host="https://api.organizze.com.br/rest/v2",
    username="your.email@example.com",
    password="your_api_token"
)

# Set required User-Agent header
configuration.api_key['userAgent'] = 'MyApp (your.email@example.com)'

# 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()

    # Create a transaction
    transactions_api = organizze_api.TransactionsApi(api_client)
    transaction = organizze_api.Transaction(
        description="Groceries",
        date="2025-12-12",
        amount_cents=-5000,
        category_id=123,
        account_id=456
    )
    result = transactions_api.create_transaction(transaction)

    # Get current month budgets
    budgets_api = organizze_api.BudgetsApi(api_client)
    budgets = budgets_api.list_current_month_budgets()

API Authentication

All Organizze API requests require:

1. HTTP Basic Auth

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

2. User-Agent Header (Required)

   • Format: ApplicationName (email@example.com)
   • Omitting this header returns 400 Bad Request

Development

Prerequisites

This project uses proto for toolchain management and moon for task running.

1. Install proto

   Follow the installation instructions at https://moonrepo.dev/proto

2. Install the toolchain

   The project's toolchain is defined in .prototools. Install all required tools by running:

   proto use

   This will install:

   • moon
   • Node.js
   • Python
   • npm
   • uv

Regenerating Clients

This project uses OpenAPI Generator to automatically generate clients from the OpenAPI specification located at specs/openapi.yaml.

Generate All Clients (Recommended)

moon run :generate-client

Updating the OpenAPI Specification

The OpenAPI specification is the single source of truth for all generated clients. To update it:

1. Edit specs/openapi.yaml with your changes
2. Regenerate the clients using the commands above
3. Test the generated clients thoroughly
4. Update the package versions in client-specific files (if needed)
5. Submit a pull request with a clear description of the changes

Contributing

Contributions are welcome! Whether you've found an endpoint that's not properly documented, discovered a bug, or want to add support for a new language, we'd love your help.

How to Contribute

1. Fork the repository
2. Update the OpenAPI specification in specs/openapi.yaml
   • Add missing endpoints
   • Fix incorrect types or constraints
   • Improve descriptions
3. Regenerate the clients using the commands in the Development section
4. Test your changes thoroughly with real API calls
5. Submit a pull request with:
   • A clear description of what you changed and why
   • Examples of the issue you're fixing (if applicable)
   • Test results showing the changes work as expected

Found an Issue?

If you encounter discrepancies between the SDK and the actual API behavior, please open an issue with details about the expected vs. actual behavior.

License

See the LICENSE file for details.