API v1 레퍼런스

개요

Manilo API는 iOS 앱에서 쓰는 것과 동일한 장부(계좌, 카테고리, 예산, 공유 그룹, 거래)를 프로그래밍 방식으로 관리하기 위한 JSON REST API입니다. 가져오기 도구, 내보내기 도구, 동기화 브리지, 대시보드를 만들거나 직접 만든 자동화를 구동하는 데 사용하십시오.

• 기본 URL: https://api.manilo.app — 이전 기본 URL인 api.ledgy.app도 계속 동작합니다.
• 버전 접두사: 이 문서의 모든 엔드포인트는 /api/v1/ 아래에 있습니다.
• 전송 방식: HTTPS만 사용합니다. HTTP 요청은 허용되지 않습니다.
• 인코딩: 요청·응답 본문은 JSON, 문자 인코딩은 UTF-8입니다. 속성 이름은 camelCase를 사용합니다.
• 인증: Authorization: Bearer … 헤더를 모든 요청에 포함해야 합니다.
• Cloud 구독: 모든 v1 엔드포인트에 필요합니다. 구독 게이트 항목을 참고하십시오.

빠른 시작

첫 인증 요청까지 세 단계면 됩니다.

1. 개인 액세스 토큰 발급하기

1. 먼저 Manilo 대시보드에 로그인한 다음 설정 → API 액세스를 엽니다.
2. 화면에서 + 새 토큰을 클릭합니다.
3. 토큰에 알아보기 쉬운 이름을 지정하고(예: “Zapier — 주간 내보내기”), 필요한 스코프를 선택한 뒤(스코프 참고), 필요하면 만료일도 설정합니다.
4. 토큰을 복사합니다. 토큰은 한 번만 표시됩니다. 토큰은 접두사 lgpat_ 뒤에 64자리 16진수 문자가 붙는 형식입니다.

같은 페이지에서 활성 토큰 목록을 마지막 사용 시각 및 권한 개수와 함께 확인할 수 있고, “30일 내 만료” 경고가 표시되며, 휴지통 아이콘으로 토큰을 즉시 폐기할 수 있습니다. 계정당 활성 토큰은 최대 25개까지 보유할 수 있습니다.

2. 요청 보내기

# Replace lgpat_… with your token
curl "https://api.manilo.app/api/v1/accounts" \
  -H "Authorization: Bearer lgpat_a1b2c3d4e5…"

3. 응답 확인하기

{
  "items": [
    {
      "id": "acc_01HK8V…",
      "name": "Wise EUR",
      "currencyCode": "EUR",
      "initialBalance": 1240.50,
      "icon": "wallet",
      "color": "#4A90E2",
      "order": 0,
      "createdAt": "2026-04-12T08:13:09Z",
      "updatedAt": "2026-05-01T17:02:31Z"
    }
  ],
  "totalCount": 1
}

인증

모든 요청은 /api/v1/ 경로로 보낼 때 반드시 Authorization 헤더를 포함해야 합니다. 허용되는 토큰 유형은 두 가지입니다:

• 개인 액세스 토큰(PAT) — 대시보드의 설정 → API 액세스 페이지에서 생성하는 장기 유효 bearer 토큰입니다. 형식: lgpat_ + 64자리 16진수 문자. 스코프를 지정할 수 있고, 언제든 폐기할 수 있으며, 만료일도 설정할 수 있습니다. 모든 서드파티 연동에는 이 방식을 권장합니다.
• 세션 JWT — 퍼스트파티 앱(iOS, 대시보드)에 발급되는 단기 토큰입니다. 스코프 제한이 없습니다. 로그인된 세션에서 토큰을 추출할 수 있다면 일회성 테스트에 쓸 수 있지만, 공식적으로 지원되는 방식은 PAT입니다.

헤더 형식

Authorization: Bearer lgpat_a1b2c3d4e5f6…

토큰 제한

• Manilo 계정당 활성 PAT 25개까지 보유할 수 있습니다.
• 생성 시점에 만료일을 선택적으로 설정할 수 있습니다. 만료된 토큰은 401 Unauthorized를 반환합니다.
• 폐기된 토큰은 즉시 사용할 수 없게 됩니다. Manilo는 토큰 값 자체가 아니라 SHA-256 해시만 저장하므로, 유출된 토큰은 복구할 수 없고 폐기 후 재발급하는 방법뿐입니다.

흔한 인증 실패

401

토큰이 없거나, 형식이 잘못되었거나, 만료되었거나, 폐기되었습니다.

403

토큰은 유효하지만 요청한 엔드포인트에 필요한 스코프를 PAT가 갖고 있지 않거나, Cloud 구독이 활성 상태가 아닙니다.

스코프

PAT는 기본 거부(deny-by-default) 모델을 따릅니다. 토큰은 자신이 보유한 스코프가 요구되는 엔드포인트만 호출할 수 있고, 그 외에는 모두 403 Forbidden을 반환합니다. 연동에 실제로 필요한 최소한의 스코프만 부여하십시오.

사용 가능한 스코프:

아래 각 엔드포인트에는 필요한 스코프가 작은 보라색 칩으로 표시됩니다. :write 스코프가 :read 스코프를 포함하지는 않습니다 — 둘 다 필요하면 둘 다 요청하십시오.

구독 게이트

읽기 전용 엔드포인트를 포함한 모든 v1 엔드포인트는 호출하는 사용자에게 활성 Manilo Cloud 구독이 있어야 합니다. 구독이 중단되었거나, 만료되었거나, 한 번도 시작한 적이 없으면 API는 다음과 같이 응답합니다:

HTTP/1.1 403 Forbidden
X-Subscription-Required: true
Content-Type: application/json

{ "error": "Active cloud subscription required" }

응답의 X-Subscription-Required 헤더를 통해 클라이언트는 구독으로 인한 차단과 일반적인 권한 거부를 구분할 수 있습니다. iOS 앱에서 Cloud를 다시 활성화하거나 dashboard.manilo.app/upgrade에서 접근 권한을 복구하십시오.

오류

오류에는 표준 HTTP 상태 코드를 사용합니다. 응답 본문은 필드가 하나뿐인 JSON 객체입니다:

{ "error": "Human-readable message" }

처리해야 할 상태 코드:

200

OK — 리소스 또는 목록이 반환되었습니다.

201

Created — 새 리소스가 생성되었습니다. Location 헤더가 정규 URL을 가리킵니다.

204

No Content — 삭제에 성공했습니다. 본문은 없습니다.

400

유효성 검사 실패 — 필수 필드 누락, 값 범위 초과, 잘못된 JSON 형식.

401

인증 실패 — 인증 항목을 참고하십시오.

403

권한 거부 — 스코프가 부족하거나 구독이 활성 상태가 아닙니다.

404

리소스를 찾을 수 없거나, 권한이 없어 노출되지 않습니다.

409

충돌 — 예: 고유 제약 조건 위반.

5xx

서버 측 오류. 멱등한 읽기 요청은 지수 백오프로 재시도해도 안전합니다.

페이지네이션 및 필터

목록 엔드포인트는 기본적으로 조건에 맞는 모든 항목을 반환합니다. 크게 늘어날 수 있는 유일한 리소스인 거래는 커서 기반 페이지네이션을 지원합니다.

거래 커서

curl "https://api.manilo.app/api/v1/transactions?limit=50&type=expense&dateFrom=2026-01-01" \
  -H "Authorization: Bearer lgpat_…"

응답에는 nextCursor가 포함됩니다. 이 값을 cursor 쿼리 파라미터로 다시 전달하면 다음 페이지를 가져옵니다. nextCursor가 null이면 마지막 페이지에 도달한 것입니다.

• limit — 페이지 크기이며 1..200 범위로 제한됩니다. 기본값은 50입니다.
• cursor — 불투명한 토큰입니다. 내부 구조를 해석하지 말고 그대로 사용하십시오.
• type, dateFrom, dateTo, categoryId, accountId, groupId — 선택적 필터입니다. 거래 목록 조회 엔드포인트를 참고하십시오.

타입과 형식

• ID — 불투명한 문자열입니다. 파싱하지 말고, 대소문자를 구분하는 UTF-8 식별자로 취급하십시오.
• 타임스탬프 — UTC 기준 ISO-8601이며 끝에 Z가 붙습니다. 예: "2026-05-13T10:30:00Z".
• 날짜 (예: 거래의 date) — 형식은 동일한 ISO-8601이지만 날짜 부분만 의미가 있습니다.
• 금액 — 소수점 이하 최대 4자리까지 표현하는 주 단위 JSON 숫자입니다(예: 12.50). 보조 단위는 절대 사용하지 않습니다. 항상 currencyCode와 함께 사용합니다.
• 통화 코드 — ISO-4217 기준으로 정확히 세 자리 대문자입니다(예: "EUR", "USD", "GBP").
• 삭제 — 모든 삭제 작업은 소프트 삭제입니다. 삭제된 항목은 목록·조회 응답에 더 이상 나타나지 않지만, 공유 상대와 과거 영수증은 그대로 보존됩니다.
• 부수 효과 — 계좌, 카테고리 또는 그룹을 삭제해도 이에 연결된 거래는 그대로 남고 참조만 해제됩니다. 계좌 삭제 엔드포인트에서는 처리 방식을 명시적으로 지정할 수 있습니다.

계좌

계좌는 잔액을 담는 그릇입니다 — 은행 계좌, 신용카드, 현금 지갑, 증권 계좌 등이 여기에 해당합니다. 모든 거래는 하나의 계좌(이체의 경우 두 개)에 연결됩니다.

POST /api/v1/accounts
{
  "name": "Cash",
  "currencyCode": "EUR",
  "initialBalance": 50.00,
  "order": 2,
  "icon": "wallet",
  "color": "#22C55E"
}

{
  "id": "acc_01HK8V…",
  "name": "Cash",
  "currencyCode": "EUR",
  "initialBalance": 50.00,
  "order": 2,
  "icon": "wallet",
  "color": "#22C55E",
  "iconColor": null,
  "shareInviteToken": null,
  "createdAt": "2026-05-13T10:30:00Z",
  "updatedAt": "2026-05-13T10:30:00Z"
}

카테고리

카테고리는 거래의 용도를 나타냅니다(장보기, 임대료, 프리랜스 수입 등). 시스템 카테고리는 읽기 전용이며 모든 사용자가 공유합니다. 사용자 카테고리는 직접 관리할 수 있습니다. 카테고리 그룹은 관련 카테고리를 하나로 묶습니다.

사용자 카테고리

카테고리 그룹

예산

예산은 반복되는 기간 동안 특정 카테고리의 지출에 한도를 설정합니다(categoryId가 null이면 장부 전체가 대상입니다). groupId를 설정하면 예산을 그룹과 공유할 수 있습니다.

그룹

그룹은 공유 장부입니다 — 가정, 여행, 함께 쓰는 집 등이 여기에 해당합니다. 모든 구성원이 동일한 거래를 보지만 소유권은 개인에게 남습니다. 구성원 관리와 초대는 iOS 앱에서 처리하며, 여기 API에서 다루는 것은 그룹 리소스 자체입니다.

거래

거래는 장부의 동사에 해당합니다. 네 가지 형태가 있습니다: income, expense, transfer(계좌 간 이체), 그리고 adjustment(일회성 잔액 조정)입니다. 기본 엔드포인트는 수입과 지출을 생성하고, 이체에는 별도의 엔드포인트가 있으며, 대량 가져오기를 위한 벌크 엔드포인트도 제공합니다.

{
  "items": [ /* TransactionDto[] */ ],
  "totalCount": 317,
  "nextCursor": "eyJrIjoiMjAyNi0wNS0xM1QxMDoz…"
}

POST /api/v1/transactions
{
  "type": "expense",
  "amount": 8.50,
  "currencyCode": "EUR",
  "date": "2026-05-12T09:14:00Z",
  "accountId": "acc_01HK8V…",
  "categoryId": "cat_food_drinks",
  "payee": "Pret",
  "note": "Flat white"
}

벌크 작업

가져오기 도구를 위해 설계되었습니다. 한 배치는 최대 100건까지 처리하며, 최선 노력(best-effort) 방식으로 동작합니다. 잘못된 항목 하나 때문에 나머지가 롤백되지는 않습니다. 성공한 항목과 항목별 오류가 따로 보고되므로 실패한 것만 재시도할 수 있습니다.

{
  "items": [ /* successful TransactionDto[] */ ],
  "errors": [
    { "index": 3, "error": "Invalid currency code" }
  ]
}

{
  "deleted": 97,
  "notFound": [ "tx_old1", "tx_old2", "tx_old3" ]
}

거래 객체

아이콘

Manilo는 계좌, 카테고리, 그룹 등 곳곳에서 쓰이는 선별된 아이콘 세트와 색상 팔레트를 제공합니다. 카탈로그를 한 번 가져와 캐시해 두고, 리소스를 생성할 때 그 식별자를 재사용하십시오.

{
  "version": "2026.05.10",
  "library": "font-awesome-6",
  "categories": [
    {
      "id": "finance",
      "name": "Finance",
      "icons": [ "wallet", "credit-card", "piggy-bank" ]
    }
  ],
  "colors": [
    { "name": "Blue", "hex": "#4A90E2" },
    { "name": "Green", "hex": "#22C55E" }
  ]
}

버전 관리

• v1 내에서는 호환성이 깨지는 변경이 없습니다. 새 엔드포인트, 새 선택 필드, 새 열거형 값만 추가합니다. 기존 필드의 타입, null 허용 여부, 필수 여부는 변경하지 않습니다.
• 새 열거형 값 추가는 호환성을 깨지 않습니다. 알 수 없는 type, source 또는 action 값은 오류로 처리하지 말고 “표시하지 않음”으로 다루십시오 — 제품이 성장하면 값이 추가됩니다.
• 호환성이 깨지는 변경이 필요해지는 경우에는 /api/v2/ 아래에 배포하며, 최소 6개월간 v1과 병행 제공하고 v1 응답에 지원 중단 헤더를 포함합니다.

지원

버그를 발견했거나, 필요한 엔드포인트가 있거나, 문서에 없는 동작을 만나셨나요? 고객 지원을 이용하거나 support@manilo.app으로 메일을 보내 주십시오 — 문제를 알려주실 때는 요청 id(X-Request-Id 응답 헤더에 그대로 반환됩니다)를 함께 적어 주십시오.

보안에 민감한 제보(토큰 유출, 권한 우회, 무단 열람)는 security@manilo.app으로 보내 주십시오.