개발자 API

POS나 스크립트 같은 다른 시스템에서 내 Money Tracker 계정의 거래, 카테고리, 결제 수단을 읽고 기록할 수 있어요. 키는 그 키를 만든 계정의 데이터에만 접근해요.

기본 URL
https://moneytracker.arizu.id
인증
X-Api-Key
X-Api-Secret
형식
HTTPS로 주고받는 JSON
사용 한도
키당 분당 60건

키 만들기

  1. Money Tracker 앱에서 프로필을 열고 API 키를 선택해요.
  2. 키 만들기를 탭하고 이름을 정한 뒤 허용할 작업을 체크해요.
  3. API_KEY와 API_SECRET을 복사해요. 시크릿은 한 번만 표시돼요.

계정마다 활성 키는 하나만 가질 수 있어요. 바꾸려면 같은 화면에서 키를 해지하고 새로 만들어요. 해지한 키는 바로 작동이 멈춰요.

인증

모든 요청에 두 값을 헤더로 보내요. 시크릿은 URL, 웹 페이지, 다른 사람이 열 수 있는 앱에 절대 넣지 마세요.

X-Api-Key
내 API_KEY예요. mtu_로 시작해요.
X-Api-Secret
내 API_SECRET이에요. 영문자와 숫자 40자예요.
요청
curl "https://moneytracker.arizu.id/api/v1/transactions?month=2026-11&type=income" \
  -H "X-Api-Key: mtu_YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

권한

키에는 체크한 권한만 주어져요. 쓰기 권한에는 읽기 권한이 포함돼요.

transactions:read
거래 읽기
transactions:write
거래 기록, 수정, 삭제
categories:read
카테고리 읽기
categories:write
카테고리 추가, 삭제
money_sources:read
결제 수단과 잔액 읽기
money_sources:write
결제 수단 추가, 수정, 삭제
profile:read
계정 이름, 이메일, 통화, 언어, 요금제 읽기

엔드포인트

경로는 기본 URL 기준이에요. 금액은 계정 통화로 표시돼요.

계정

  • GET/api/v1/auth/meprofile:read

    계정 프로필.

거래

  • GET/api/v1/transactionstransactions:read

    거래 목록(최신순). 필터: month(2026-11), type(income 또는 expense), source_id, page, per_page(최대 100).

  • GET/api/v1/transactions/{id}transactions:read

    거래 1건.

  • POST/api/v1/transactionstransactions:write

    거래를 기록해요. 필수: type, amount, occurred_on(2026-11-02). 선택: category_id, payment_source_id, note(최대 255자), client_ref.

  • PUT/api/v1/transactions/{id}transactions:write

    거래를 수정해요. 기록할 때와 같은 필드를 client_ref 없이 보내요.

  • DELETE/api/v1/transactions/{id}transactions:write

    거래를 삭제해요.

카테고리

  • GET/api/v1/categoriescategories:read

    수입 및 지출 카테고리.

  • POST/api/v1/categoriescategories:write

    카테고리를 추가해요. 필수: type, name. 선택: icon, color(#RRGGBB), client_ref.

  • DELETE/api/v1/categories/{id}categories:write

    카테고리를 삭제해요.

결제 수단

  • GET/api/v1/payment-sourcesmoney_sources:read

    결제 수단과 잔액.

  • POST/api/v1/payment-sourcesmoney_sources:write

    결제 수단을 추가해요. 필수: type(bank, card, ewallet, cash 중 하나), holder_name. 선택: bank_name, provider_name, card_type, card_last4, opening_balance, client_ref.

  • PUT/api/v1/payment-sources/{id}money_sources:write

    결제 수단을 수정해요.

  • DELETE/api/v1/payment-sources/{id}money_sources:write

    결제 수단을 삭제해요.

그 밖의 경로는 앱이 직접 쓰는 경로라도 API 키에는 403으로 응답해요.

예시: 판매 기록하기

POS는 판매 건마다 수입으로 기록할 수 있어요. 판매마다 고유한 client_ref를 붙이면 네트워크 오류 뒤 다시 보내도 두 번 기록되지 않아요.

요청
curl -X POST "https://moneytracker.arizu.id/api/v1/transactions" \
  -H "X-Api-Key: mtu_YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "income",
    "amount": 125000,
    "occurred_on": "2026-11-02",
    "note": "Sale 1042",
    "client_ref": "pos-sale-1042"
  }'

응답 상태는 201이고, 새 거래의 id가 data.id에 들어 있어요.

응답 201
{
  "data": {
    "id": 58213,
    "amount": "125000.00",
    "currency": "IDR",
    "original_amount": null,
    "original_currency": null,
    "fx_rate": null,
    "fx_date": null
  }
}

client_ref는 영문자, 숫자, 하이픈으로 된 8~64자예요. 계정에 같은 client_ref의 거래가 이미 있으면 API는 새로 기록하지 않고 그 거래를 돌려줘요.

응답과 오류

성공한 응답은 결과를 data에 담아요. 실패한 응답에는 계정 언어로 된 메시지가 error에 들어 있고, 많은 경우 언어와 상관없이 같은 code도 함께 와요.

응답 403
{
  "error": "This API key does not have the permission for this request",
  "code": "api_key_scope_missing",
  "scope": "transactions:write"
}
401
키나 시크릿이 없거나 틀렸어요. 또는 키가 해지됐거나 만료됐어요.
403
키에 이 요청에 대한 권한이 없거나, 그 경로가 API 키에 막혀 있거나, 계정이 차단됐어요.
404
이 계정에 해당 항목이 없어요.
422
필드가 빠졌거나 올바르지 않아요. fields가 있으면 고칠 내용이 나와요.
429
요청이 너무 많아요. Retry-After 헤더에 적힌 초만큼 기다려 주세요.

사용 한도

키마다 분당 최대 60건까지 요청할 수 있어요. 요금제 한도도 앱과 똑같이 적용돼요. Free 요금제에서는 하루에 새 거래를 최대 30건까지 기록할 수 있어요.

키 안전하게 관리하기

  • 시크릿은 POS 설정처럼 한 곳에만 보관하고, 채팅이나 이메일로 공유하지 마세요.
  • 시스템에 필요한 권한만 체크해요.
  • 시크릿이 유출되면 앱에서 키를 해지하고 새로 만들어요.
  • 앱에서 키의 마지막 사용 시각을 볼 수 있어요. 내 시스템과 맞지 않으면 키를 해지하세요.

API에 관해 궁금한 점은 ariefzufar@arizu.id / arizu.team@gmail.com(으)로 문의해 주세요.