organizze-api-sdk

v1.0.8

Published

15 days ago

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

Downloads

640

Organizze API SDK for TypeScript/JavaScript

Auto-generated TypeScript/JavaScript 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.

Installation

# NPM
npm install --save organizze-api-sdk

# Yarn
yarn add organizze-api-sdk

# pNpm
pnpm install organizze-api-sdk

Compatibility

Browsers: Any modern browser capable of supporting ES6
Node.js: >= 18 (due to the usage of the Fetch API)

Authentication

All Organizze API requests require:

HTTP Basic Authentication
- Username: Your Organizze account email
- Password: API token from https://app.organizze.com.br/configuracoes/api-keys
User-Agent Header (REQUIRED)
- Format: ApplicationName ([email protected])
- Important: Omitting this header will result in 400 Bad Request errors

Quick Start

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

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

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

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

Usage Examples

Listing Bank Accounts

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

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

const api = new BankAccountsApi(config);
const accounts = await api.listBankAccounts();

Reading a Specific Bank Account

const accountId = 123;
const account = await api.readBankAccount({ id: accountId });

Managing Transactions

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

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

const api = new TransactionsApi(config);

// List all transactions
const transactions = await api.listTransactions();

// Create a new transaction
const newTransaction = await api.createTransaction({
  description: "Salary",
  date: "2025-01-01",
  amount_cents: 500000, // R$ 5,000.00
  category_id: 456,
  account_id: 789,
});

// Read a specific transaction
const transaction = await api.readTransaction({ id: 123 });

// Update a transaction
const updated = await api.updateTransaction({
  id: 123,
  transaction: {
    description: "Updated description",
    amount_cents: -3000,
  },
});

// Delete a transaction
await api.deleteTransaction({ id: 123 });

Working with Categories

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

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

const api = new CategoriesApi(config);

// List all categories
const categories = await api.listCategories();

// Read a specific category
const category = await api.readCategory({ id: 123 });

Managing Credit Cards

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

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

const api = new CreditCardsApi(config);

// List all credit cards
const cards = await api.listCreditCards();

// Read a specific credit card
const card = await api.readCreditCard({ id: 123 });

// List invoices for a credit card
const invoices = await api.listCreditCardInvoices({ creditCardId: 123 });

// Read a specific invoice
const invoice = await api.readCreditCardInvoice({
  creditCardId: 123,
  id: 456,
});

// List payments for an invoice
const payments = await api.listCreditCardInvoicePayments({
  creditCardId: 123,
  invoiceId: 456,
});

Accessing User Information

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

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

const api = new UsersApi(config);

// List all users
const users = await api.listUsers();

// Read a specific user
const user = await api.readUser({ id: 123 });

Available APIs and Operations

Quick reference table of all available operations. Click on any API or operation name for detailed documentation.

| API | Operation | Description | | -------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------ | | BankAccountsApi | listBankAccounts | List all bank accounts | | BankAccountsApi | readBankAccount | Get details of a specific bank account | | BudgetsApi | listCurrentMonthBudgets | List budgets for the current month | | BudgetsApi | listYearMonthBudgets | List budgets for a specific year and month | | CategoriesApi | listCategories | List all transaction categories | | CategoriesApi | readCategory | Get details of a specific category | | CreditCardsApi | listCreditCards | List all credit cards | | CreditCardsApi | readCreditCard | Get details of a specific credit card | | CreditCardsApi | listCreditCardInvoices | List invoices for a credit card | | CreditCardsApi | readCreditCardInvoice | Get details of a specific invoice | | CreditCardsApi | listCreditCardInvoicePayments | List payments for a credit card invoice | | TransactionsApi | listTransactions | List all transactions | | TransactionsApi | createTransaction | Create a new transaction | | TransactionsApi | readTransaction | Get details of a specific transaction | | TransactionsApi | updateTransaction | Update an existing transaction | | TransactionsApi | deleteTransaction | Delete a transaction | | UsersApi | listUsers | List all users | | UsersApi | readUser | Get details of a specific user |

Features

This SDK supports the complete Organizze API, including:

Bank Accounts - List and view bank account details
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

API Reference Documentation

API Classes

Detailed documentation for each API class:

BankAccountsApi - Bank account operations
BudgetsApi - Budget management operations
CategoriesApi - Category management operations
CreditCardsApi - Credit card, invoice, and payment operations
TransactionsApi - Transaction management operations
UsersApi - User information operations

Data Models

Documentation for request/response types and models:

Core Models:

BankAccount - Bank account data structure
BankAccountInput - Bank account creation/update input
Budget - Budget data structure
Category - Category data structure
CategoryInput - Category creation/update input
CreditCard - Credit card data structure
CreditCardInput - Credit card creation/update input
CreditCardInvoice - Credit card invoice data structure
CreditCardInvoiceFull - Complete invoice data with details
Transaction - Transaction data structure
TransactionInput - Transaction creation/update input
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

Additional Models:

Tag - Tag data structure
TransactionTagsInner - Transaction tag structure

Error Models:

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

Error Handling

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

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

const api = new TransactionsApi(config);

try {
  const transaction = await api.readTransaction({ id: 123 });
  console.log(transaction);
} catch (error) {
  console.error("API Error:", error);
}

Important Notes

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.
Amount Format: Transaction amounts are in cents (e.g., -5000 = -R$ 50.00). Use negative values for expenses and positive values for income.
Date Format: Dates should be in YYYY-MM-DD format (e.g., "2025-01-15").
Authentication: Keep your API token secure. Never commit it to version control or expose it in client-side code.

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.