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일입니다. 만료되지 않는 선택지는 없으니, 이 위에 무언가를 만든다면 만료 전에 키를 교체할 계획이 필요합니다.

응답 헤더

모든 응답에는 다음이 포함됩니다:

오류

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

• 400

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

• 401

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

• 402

  플랜 쿼터에 걸렸습니다 — 오늘 기준으로는 카테고리 생성에만 해당합니다.

• 403

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

• 409

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

오류 형태

모든 오류는 같은 형태로 돌아옵니다: statusCode, message, 그리고 무엇이 잘못됐는지 이름 붙인 errors 객체입니다. 키가 없거나 유효하지 않으면 본문 없이 돌아올 수도 있습니다.

{
  "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 요청 허용량도 명시합니다 — 무료 플랜은 500건, 모든 유료 플랜은 그보다 많습니다.

여기 없는 것: 오늘 REST에는 요청 단위 제한이 없고, 429도 없고, 속도 제한 헤더도 없습니다 — 즉 유출된 키는 이쪽에서 아무것도 늦추지 않습니다. 키가 의심스러우면 언제든 취소하세요: 그러면 즉시 차단됩니다(위의 보안 및 키 관리 참고). 그리고 이 API는 베타이므로 앞으로도 계속 그러리라고 가정하지 마세요.

공통 규칙

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

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

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

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

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

보안과 키 관리

계좌

{
  "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"
  }
}