Era API

빠른 시작

시작하기 전에 Era 계정과 연결된 금융기관이 최소 하나 필요합니다. 연결이 없으면 이 엔드포인트들이 돌려줄 것이 없습니다.

1. 1

   Era에 로그인하고, 아직이라면 금융기관을 연결합니다.

2. 2

   대시보드에서 API 키를 열고 키를 만듭니다. 범위는 처음에 전부 체크되어 있으니 필요 없는 것을 해제하세요. 이 엔드포인트들에는 banking:read만 남기면 됩니다. 만료 기간도 고르는데, 만료되지 않는 선택지는 없습니다.

3. 3

   키를 복사합니다. 한 번만 보여 주고, 다시 보여 줄 수 없습니다. 복사해서 시크릿 매니저 같은 안전한 곳에 보관하세요. 키를 잃어버리면 다시 볼 수 없습니다. 대신 새 키를 만드세요.

4. 4

   요청 헤더에 담아 보냅니다.

curl "https://forge.era.app/api/banking/transactions?page=1&pageSize=20" \
  -H "X-API-Key: fmk_your_key_here"

{
  "transactions": [ … ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 412,
    "totalPages": 21
  },
  "historyWindowApplied": true,
  "historyWindowFloorDate": "2026-06-28",
  "historyWindowHiddenCount": 137,
  "historyWindowEarliestDate": "2024-03-02",
  "historyWindowDegraded": false
}

사용 가능한 API

Era API에는 다음 API가 포함되어 있습니다:

• GET/banking/accounts

  연결된 모든 기관에 걸쳐 볼 수 있는 모든 계정.

• GET/banking/accounts/{accountId}/balance

  계정 하나의 잔액. 부채 계정이면 신용 관련 필드도 포함됩니다.

• GET/banking/accounts/summary

  볼 수 있는 모든 계정에 대한 합계.

• GET/banking/transactions

  거래 내역을 페이지 단위로.

• PUT/banking/transactions/{id}

  거래 하나 바꾸기

• PUT/banking/transactions/bulk

  한 번에 최대 100개 바꾸기

• GET/banking/categories

  전체 카테고리 분류 체계, 하위 카테고리까지 중첩되어.

• POST/banking/categories

  카테고리 추가하기

• GET/banking/tags

  계정의 모든 태그를 한 번의 응답으로.

• POST/banking/tags

  태그 만들기

인증

키는 다음 두 가지 방법 중 하나로 보내세요:

모든 요청은 TLS로 암호화됩니다.

키는 만료되고, 만들 때 얼마 뒤에 만료될지 고릅니다. 최대는 무료 요금제 90일, 유료 요금제 365일입니다. 만료되지 않는 선택지는 없으니, 이 위에 무언가를 만든다면 만료 전에 키를 교체할 계획이 필요합니다.

응답 헤더

요청 ID는 모든 응답에 들어갑니다. 속도 제한 헤더는 Era가 계량한 호출에 붙습니다. Era가 사용량을 측정하지 못하면 호출을 그대로 처리하고 이 헤더는 하나도 보내지 않습니다.

오류

이 API가 반환하는 오류 상태 코드는 다음과 같습니다:

• 400

  잘못된 입력: 잘못된 파라미터, 비어 있거나 100개를 넘는 일괄 업데이트, 또는 같은 호출에서 같은 필드를 설정하면서 동시에 지우는 쓰기.

• 401

  키가 없거나 파싱할 수 없는 키입니다. X-API-Key 헤더나 베어러 토큰으로 보내세요.

• 402

  플랜 쿼터에 걸렸습니다 — 오늘 기준으로는 카테고리 생성에만 해당합니다. 얼마나 빨리 호출하느냐가 아니라 무엇을 만드느냐의 문제라서, 기다려도 풀리지 않고 상위 요금제로 올리면 풀립니다. 너무 빨리 호출해서 걸리는 건 429입니다.

• 403

  키가 이 호출에 필요한 범위를 지니지 않았거나 — 두 거래 쓰기 중 하나에서 id가 다른 사람의 것이거나 아예 존재하지 않는 경우입니다. API는 이 둘을 구분하지 않습니다.

• 404

  존재하지 않는 계좌입니다. 잔액 엔드포인트만 이 상태를 반환합니다. 어떤 계좌도 가리키지 않는 accountGroupKey나 아예 키 형태가 아닌 값은 본문 없이 404로 돌아옵니다. 거래는 404를 반환하지 않습니다 — 403을 참고하세요.

• 409

  쓰는 동안 다른 무언가가 그 행을 바꿨습니다. 다시 읽고 다시 쓰세요.

• 429

  요청이 너무 많습니다. 하루 예산을 다 썼거나 분당 버스트 상한에 걸렸습니다. 얼마나 기다릴지는 Retry-After가 알려주고, 402와 달리 이건 기다리면 풀립니다. 어느 상한이 거절했는지와 요금제별 수치는 제한 섹션을 참고하세요.

오류 형태

대부분의 오류는 같은 형태로 돌아옵니다: statusCode, message, 그리고 무엇이 잘못됐는지 이름 붙인 errors 객체입니다. 전부는 아닙니다. 401과 404는 본문 없이 돌아오므로 본문보다 상태 코드를 먼저 확인하세요.

{
  "statusCode": 403,
  "message": "One or more errors occurred!",
  "errors": {
    "generalErrors": ["Transaction does not belong to the authenticated user"]
  }
}

요청 ID

모든 응답에는 fly-request-id 헤더가 담겨 있습니다. 특정 요청에 대해 지원팀에 문의할 때 이 값을 함께 알려주세요.

# Print the response headers, including fly-request-id; discard the body
curl -sS -D - -o /dev/null "https://forge.era.app/api/banking/transactions?page=1&pageSize=20" \
  -H "X-API-Key: fmk_your_key_here"

# A write call: same header, plus a JSON body
curl -sS -D - -X PUT "https://forge.era.app/api/banking/transactions/utgr_your_transaction_id" \
  -H "X-API-Key: fmk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"categoryKey": "fcat_dining", "merchantName": "Corner Cafe"}'

흔한 오류

• 같은 쓰기에서 필드를 설정하면서 동시에 지우기 — 400.

• 일괄 업데이트에 100개를 넘는 id — 400, 아무것도 바뀌지 않습니다. 1개 미만도 마찬가지입니다.

• 내 것이 아니거나 존재하지 않는 거래 — 403, 절대 404가 아닙니다. 그래서 응답은 그 id가 존재하는지는 절대 알려주지 않고, 단지 당신 것이 아니라는 것만 알려줍니다.

• 다른 무언가가 먼저 그 행을 바꿨습니다 — 409.

제한

문서화된 열 개의 엔드포인트 중 두 개는 한 번의 호출로 요청할 수 있는 양에 상한이 있습니다. 나머지 여덟 개는 없습니다.

상한이 없다고 해서 무제한이란 뜻은 아닙니다: 키는 여전히 만료되고, 쓰기에는 여전히 필드 길이 제한이 있고, 카테고리 생성은 요금제 쿼터에 걸릴 수 있으며, 요금제에 따라 오래된 내역이 계속 숨겨질 수 있습니다. 이 중 어느 것도 속도 제한은 아닙니다 — 아래를 참고하세요.

• 계좌, 잔액, 요약, 카테고리와 태그 목록, 카테고리 생성, 태그 생성, 그리고 단일 거래 쓰기는 호출당 물량 상한이 없습니다. 요청한 전체 세트, 또는 지정한 한 행 그대로를 돌려받습니다.

• pageSize는 거부되지 않고 100으로 조정됩니다. 더 많이 요청해도 200과 함께 100개 행이 돌아옵니다 — 보낸 값을 믿지 말고 응답의 pagination.pageSize를 읽으세요.

• 거래 일괄 쓰기는 id 100개로 제한되며, pageSize와 달리 조정이 아니라 거부됩니다: 101개를 보내면 400이 오고 아무것도 바뀌지 않습니다.

• 키는 생성할 때 선택한 일정에 따라 만료됩니다 — 무료 플랜은 최대 90일, 유료 플랜은 365일입니다. 만료되지 않는 옵션은 없습니다.

• 플랜에 따라 오래된 거래를 숨기는 히스토리 윈도우 하한이 적용될 수 있습니다. 거래 응답에는 하한이 적용됐는지와 어디에 걸렸는지를 알려주는 historyWindow 필드가 담겨 있습니다.

속도 제한

모든 요금제가 이 API를 호출할 수 있고, 모든 요금제가 계량됩니다. 계량되는 것은 당신이 키로 보내는 호출입니다. 하루 예산과 분당 버스트 상한이라는 두 상한이 동시에 적용되며, 둘 중 하나라도 넘기면 429가 돌아옵니다.

하루 예산은 키가 아니라 사용자에게 붙습니다. 계정의 모든 REST 키가 같은 하루 예산에서 차감되므로, 키를 하나 더 만든다고 호출 횟수가 늘지는 않습니다. MCP 도구 호출은 따로 집계됩니다. 한쪽을 써도 다른 쪽은 줄지 않습니다.

Era가 호출을 계량하면 응답에 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset이 실립니다. 셋 다 하루 예산을 설명합니다. 이 예산은 자정에 초기화되지 않고 24시간에 걸쳐 굴러갑니다. 가장 오래된 호출이 24시간이 지날 때마다 요청이 한 건씩 돌아옵니다. 분당 버스트 상한에는 헤더가 없으니, 표의 수치를 보고 직접 속도를 조절하세요. Remaining이 0보다 한참 높아도 버스트는 429로 돌아올 수 있습니다. Era가 사용량을 측정하지 못하면 호출을 그대로 처리하고 속도 제한 헤더를 보내지 않으니, 헤더가 없으면 오류가 아니라 측정값이 빠진 것으로 다루세요.

429가 알려주는 것

problem-details 본문입니다. detail 필드는 구조화된 필드가 아니라 일반 텍스트입니다. 걸린 상한, 그 상한이 허용하는 양, 다음 요청이 비는 시각, 그리고 상한을 올려주는 요금제(이미 최상위라면 그렇다는 사실)를 알려줍니다. 파싱하지 마세요. 코드에서 분기하려면 헤더를 읽으세요. Remaining이 0이면 하루 예산이, 0보다 크면 분당 버스트 상한이 거절한 것입니다.

{
  "type": "https://httpstatuses.com/429",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "You've used up your daily budget of 250 requests. Your next request frees up at 2026-09-16T09:00:00Z. The Organize plan raises it."
}

429에는 Retry-After도 실립니다. 거절한 상한을 기준으로 잰 정수 초로, 분당 버스트 상한이면 최대 1분, 하루 예산이면 최대 24시간입니다. 거절된 호출은 아무것도 쓰지 않으므로 일찍 재시도해도 손해는 없지만, 다시 429가 돌아옵니다. Retry-After가 지나면 요청 한 건이 비는 것이지, 예산 전체가 돌아오는 게 아닙니다. 그 요청을 보낸 뒤 헤더나 다음 Retry-After를 읽으세요.

이 중 어느 것도 행방을 놓친 키를 지켜주지는 않습니다. 유출된 키는 사용자 본인과 똑같이 예산을 씁니다. 키가 의심스러우면 폐기하세요. 아래의 보안과 키 관리를 참고하세요.

공통 규칙

응답 필드는 camelCase입니다. 쿼리 파라미터는 대소문자를 가리지 않으니 여기서도 camelCase가 통합니다. 공개된 명세는 PascalCase로 적혀 있어서, 두 표기를 모두 보게 됩니다.

달력의 하루를 가리키는 필드는 YYYY-MM-DD입니다. 어느 한 시점을 가리키는 필드는 오프셋이 붙은 ISO 8601입니다.

페이지 크기는 거절되는 것이 아니라 잘려 맞춰집니다. pageSize에 500을 넣어도 돌아오는 것은 100건과 200이지 오류가 아닙니다. 그러니 보낸 값을 믿지 말고 pagination.pageSize를 다시 읽으세요.

응답에는 이 페이지에 적히지 않은 필드가 담길 수 있습니다. 모르는 필드는 오류로 만들지 말고 그냥 넘기세요. 그래야 API가 자라도 당신의 클라이언트가 계속 동작합니다.

REST는 평범한 HTTP라 호출하는 데 SDK가 필요 없습니다. HTTP 클라이언트가 있는 언어면 어떤 것이든 됩니다. 설치할 것은 없습니다.

버전과 변경

여기 문서로 적힌 것은 모두 이 정책의 대상입니다.

경로에 버전 번호가 없고 버전 헤더도 없습니다. 엔드포인트마다 살아 있는 버전은 하나이고, 그것이 여기 적힌 버전입니다.

예고 없이 바꿀 수 있는 것

위의 규약을 따르는 클라이언트를 깨뜨리는 것은 하나도 없습니다.

• 엔드포인트를 추가하거나, 이미 있는 엔드포인트에 작업을 추가한다.

• 응답에 필드를 추가한다.

• 선택적 파라미터를 추가한다. 넣지 않으면 달라지는 것이 없다.

• 정해진 값 집합에 값을 추가한다. 상태나 종류 같은 것.

• 응답 헤더를 추가한다.

예고 없이 바꾸지 않는 것

어느 것이든 잘 돌던 클라이언트를 깨뜨릴 수 있습니다.

• 엔드포인트를 없애거나, 경로나 메서드를 바꾼다.

• 응답 필드를 없애거나 이름을 바꾼다.

• 필드의 타입이나 의미를 바꾼다.

• 지금은 선택인 파라미터를 필수로 만든다.

• 지금은 받아 주는 입력을 거부한다.

• 엔드포인트에 필요한 범위를 바꾼다.

이런 변경을 하기 전에는 최소 90일 앞서 변경 이력에서 알리고, 무엇을 바꿔야 하는지 안내합니다. 지금 동작하는 것은 그때까지 계속 동작합니다.

변경은 변경 이력에서 알립니다. 링크는 아래 '변경 이력' 섹션에 있습니다. 이메일이나 피드는 아직 없으니 API 관련 작업을 계획할 때 그곳을 확인하세요.

API가 베타인 동안 문서로 적힌 범위는 계속 넓어집니다. 이미 여기 있는 것은 예고 없이 깨지지 않습니다.

변경 이력

Era API를 포함한 Era Developer Platform의 업데이트를 최신순으로 정리했습니다. 위의 정책은 무엇을 얼마나 앞서 예고하는지를 정하고, 변경 이력은 그 예고가 실리는 곳입니다.

보안과 키 관리

계좌

{
  "accounts": [
    {
      "accountGroupKey": "uagr_7f3c9a21",
      "connectionId": "ucon_4b19e02c",
      "name": "Everyday Checking",
      "currentBalance": 4820.16,
      "supportsTransactions": true,
      …
    }
  ],
  "excludedAccountCount": 1
}

계좌 잔액

{
  "accountGroupKey": "uagr_7f3c9a21",
  "currentBalance": 4820.16,
  "availableBalance": 4712.03,
  "creditLimit": null,
  "currencyCode": "USD",
  "availableCredit": null,
  "asOf": "2026-08-11T09:32:00Z",
  "visibility": null
}

계좌 요약

{
  "userId": "7d1c0b93a8e24f60",
  "accounts": [ … ],
  "totalVisibleCount": 6,
  "totalHiddenCount": 2,
  "totalAssets": 48210.75,
  "totalLiabilities": 9327.40,
  "netWorthHint": 38883.35,
  "computedAt": "2026-08-11T09:32:00Z"
}

거래

{
  "transactions": [ … ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 412,
    "totalPages": 21
  },
  "historyWindowApplied": true,
  "historyWindowFloorDate": "2026-06-28",
  "historyWindowHiddenCount": 137,
  "historyWindowEarliestDate": "2024-03-02",
  "historyWindowDegraded": false
}

{
  "transaction": { … }
}

{
  "transactions": [ … ]
}

카테고리

{
  "packs": [
    {
      "packSlug": "default",
      "packName": "Era default categories",
      "isDefault": true,
      "categories": [
        {
          "projectionKey": "fcat_food_dining",
          "categoryName": "Food & dining",
          "isTopLevel": true,
          "children": [ … ]
        }
      ]
    }
  ],
  "meterLimit": 25,
  "canCreateCustomCategories": true
}

{
  "categoryKey": "fcat_side_hustle_9f2a",
  "overlayProjectionKey": "fcov_9f2a1c",
  "action": "created",
  "isQuotaExceeded": false,
  "createdMappingRuleKeys": [ … ],
  …
}

태그

{
  "tags": [
    {
      "tagKey": "utag_9c2f01ab",
      "name": "business-expense",
      "displayName": "Business expense",
      "tagType": "user",
      "color": "#6DC6BA",
      "transactionCount": 42
    }
  ]
}

{
  "tag": {
    "tagKey": "utag_9c2f01ab",
    "name": "business-expense",
    "displayName": "Business expense",
    "tagType": "user",
    "version": 1,
    "createdAt": "2026-08-26T09:15:00Z"
  }
}