node-zaim

Node.js client library for Zaim API

Installation

npm i node-zaim

Usage

Initialization

If you already have an access token, you can initialize the client directly:

import { Zaim } from 'node-zaim';

const zaim = new Zaim({
	consumerKey: 'your-consumer-key',
	consumerSecret: 'your-consumer-secret',
	accessToken: 'your-access-token',
	accessTokenSecret: 'your-access-token-secret',
});

OAuth Authorization Flow

If you need to obtain an access token via OAuth, use the following flow:

import Zaim from 'node-zaim';

const zaim = new Zaim({
	consumerKey: 'your-consumer-key',
	consumerSecret: 'your-consumer-secret',
});

// 1. Get a request token
const { token, tokenSecret } = await zaim.getRequestToken();

// 2. Redirect the user to the authorization URL
const authorizeUrl = zaim.getAuthorizeUrl(token);
console.log('Redirect user to:', authorizeUrl);

// 3. After the user authorizes, exchange for an access token
//    using the oauth_verifier from the callback
const { accessToken, accessTokenSecret } = await zaim.getAccessToken(
	token,
	tokenSecret,
	'oauth-verifier-from-callback'
);

// 4. Store the access token for future use
console.log('Access Token:', accessToken);
console.log('Access Token Secret:', accessTokenSecret);

You can also set the access token later on an existing instance:

zaim.setAccessToken(accessToken, accessTokenSecret);

User

verify()

Representation of the requesting user if authentication was successful.

const user = await zaim.user.verify();
console.log(user.name); // 'MyName'
console.log(user.inputCount); // 100
console.log(user.currencyCode); // 'JPY'

Money

list()

Showing the list of input data

// Get all records
const allMoney = await zaim.money.list();
console.log(allMoney[0].amount); // 10000
console.log(allMoney[0].mode); // 'income'

// Filter by date range and type
const payments = await zaim.money.list({
	mode: 'payment',
	startDate: '2024-01-01',
	endDate: '2024-12-31',
	limit: 50,
});

Payment

create()

Input payment data

const payment = await zaim.payment.create({
	categoryId: 101,
	genreId: 10101,
	amount: 1,
	date: '2026-02-04',
	comment: 'test',
	name: 'test',
	place: 'test',
});
console.log(payment);

update()

Update payment data

const payment = await zaim.payment.update({
	amount: 1,
	date: '2026-02-04',
	genreId: 10101,
	categoryId: 101,
	placeUid: 'zm-12345',
	comment: 'test',
});
console.log(payment);

delete()

Delete payment data

const payment = await zaim.payment.delete(11820767);
console.log(payment);

Income

create()

Input income data

const income = await zaim.income.create({
	categoryId: 101,
	amount: 1,
	date: '2026-02-04',
	place: 'test',
	comment: 'test',
});
console.log(income);

update()

Update income data

const income = await zaim.income.update({
	categoryId: 101,
	amount: 1,
	date: '2026-02-04',
	placeUid: 'zm-12345',
	comment: 'test',
});
console.log(income);

delete()

Delete income data

const income = await zaim.income.delete(11820767);
console.log(income);

Transfer

create()

Input transfer data

const transfer = await zaim.transfer.create({
	amount: 1,
	date: '2026-02-04',
	fromAccountId: 1,
	toAccountId: 1,
	comment: 'test',
});
console.log(transfer);

update()

Update transfer data

const transfer = await zaim.transfer.update({
	amount: 1,
	date: '2026-02-04',
	comment: 'test',
});
console.log(transfer);

delete()

Delete transfer data

const transfer = await zaim.transfer.delete(11820767);
console.log(transfer);

Category

list()

Showing the list of your categories

const categories = await zaim.category.list();
console.log(categories[0].name); // 'Food'

default()

Get default category list

const categories = await zaim.category.default('en');
console.log(categories[0].name); // 'Food'

Genre

list()

Showing the list of your genres

const genres = await zaim.genre.list();
console.log(genres[0].name); // 'Geocery'

default()

Get default genre list

const genres = await zaim.genre.default('en');
console.log(genres[0].name); // 'Geocery'

Account

list()

Showing the list of your accounts

const accounts = await zaim.account.list();
console.log(accounts[0].name); // 'Credit card'

default()

Get default account list

const accounts = await zaim.account.default('en');
console.log(accounts[0].name); // 'Wallet'

Currency

list()

const currencies = await zaim.currency.list();
console.log(currencies[0].currencyCode); // 'AUD'
console.log(currencies[0].name); // 'Australian dollar'

API Reference

Endpoint	Method	Description
zaim.user.verify()	GET	Representation of the requesting user if authentication was successful
zaim.money.list(params?)	GET	Showing the list of input data
zaim.payment.create(params)	POST	Input payment data
zaim.payment.update(id, params)	PUT	Update payment data
zaim.payment.delete(id)	DELETE	Delete payment data
zaim.income.create(params)	POST	Input income data
zaim.income.update(id, params)	PUT	Update income data
zaim.income.delete(id)	DELETE	Delete income data
zaim.transfer.create(params)	POST	Input transfer data
zaim.transfer.update(id, params)	PUT	Update transfer data
zaim.transfer.delete(id)	DELETE	Delete transfer data
zaim.category.list()	GET	Showing the list of your categories
zaim.genre.list()	GET	Showing the list of your genres
zaim.account.list()	GET	Showing the list of your accounts
zaim.account.default(lang?)	GET	List default accounts
zaim.category.default(lang?)	GET	List default categories
zaim.genre.default(lang?)	GET	List default genres
zaim.currency.list()	GET	List available currencies

For full details on each endpoint, refer to the Zaim API documentation.

Contributing

Please see CONTRIBUTING.md for contribution guidelines.

License

MIT