API de Era

Inicio rápido

Antes de empezar necesitas una cuenta de Era con al menos una institución conectada: sin conexión no hay nada que estos endpoints puedan devolver.

1. 1

   Inicia sesión en Era y conecta una institución, si aún no lo has hecho.

2. 2

   Abre tus claves de API en el panel y crea una. Todos los alcances vienen marcados, así que desmarca los que no necesites: para estos endpoints queda banking:read. También eliges una caducidad; no hay opción de que nunca caduque.

3. 3

   Copia la clave. Se muestra una sola vez y no podemos volver a mostrarla. Cópiala y guárdala en un lugar seguro, como un gestor de secretos. Si pierdes una clave, no puedes volver a verla. Crea una nueva en su lugar.

4. 4

   Mándala en un encabezado junto con tu petición.

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
}

APIs disponibles

La API de Era incluye las siguientes APIs:

• GET/banking/accounts

  Cada cuenta que puedas ver, en todas tus instituciones conectadas.

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

  El saldo de una cuenta, con los campos de crédito incluidos si es un pasivo.

• GET/banking/accounts/summary

  Totales de todas las cuentas que puedas ver.

• GET/banking/transactions

  Tus transacciones, una página a la vez.

• PUT/banking/transactions/{id}

  Cambiar una transacción

• PUT/banking/transactions/bulk

  Cambiar hasta 100 a la vez

• GET/banking/categories

  Toda la taxonomía de categorías, con las subcategorías anidadas.

• POST/banking/categories

  Agregar una categoría

• GET/banking/tags

  Todas las etiquetas de tu cuenta, en una sola respuesta.

• POST/banking/tags

  Crear una etiqueta

Autenticación

Envía tu clave de una de estas dos formas:

Toda petición va cifrada con TLS.

Las claves caducan, y tú eliges qué tan pronto al crearlas. Lo máximo son 90 días en el plan gratis y 365 en uno de pago; no existe la opción de que nunca caduquen, así que lo que construyas sobre esto necesita un plan para rotar la clave antes de que venza.

Encabezados de respuesta

Toda respuesta incluye:

Errores

La API devuelve estos códigos de estado de error:

• 400

  Entrada malformada: un parámetro incorrecto, una actualización masiva vacía o con más de 100 elementos, o una escritura que establece y borra el mismo campo en la misma llamada.

• 401

  Sin clave, o una que no se puede interpretar. Envíala como cabecera X-API-Key o como token bearer.

• 402

  Una cuota del plan se interpone — hoy, eso ocurre solo al crear categorías.

• 403

  La clave no lleva el alcance que esta llamada necesita — o, en cualquiera de las dos escrituras de transacciones, el id pertenece a otra persona o no existe. La API no distingue entre esos dos casos.

• 409

  Algo más cambió la fila mientras escribías. Léela de nuevo y envía tu escritura de nuevo.

Formas de error

Todo error vuelve con la misma forma: statusCode, message y un objeto errors que nombra lo que falló. Una clave ausente o inválida puede volver sin cuerpo en absoluto.

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

ID de solicitud

Toda respuesta lleva un encabezado fly-request-id. Inclúyelo cuando contactes a soporte sobre una solicitud específica.

# 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"}'

Errores comunes

• Establecer un campo y borrarlo en la misma escritura — 400.

• Más de 100 ids en una actualización masiva — 400, y no se cambia nada. Menos de uno es igual.

• Una transacción que no es tuya, o que no existe — 403, nunca 404. Así que la respuesta nunca te dice si un id existe, solo que no es tuyo para verlo.

• Algo más cambió la fila primero — 409.

Límites

Dos de los diez endpoints documentados limitan cuánto puedes pedir en una sola llamada. Los otros ocho no.

Eso no significa ilimitado: las claves siguen caducando, las escrituras siguen teniendo límites de longitud de campo, y tu plan puede seguir ocultando historial antiguo. Nada de esto es un límite de tasa — ver más abajo.

• Cuentas, saldo, resumen, categorías, etiquetas y la escritura de una sola transacción no tienen límite de volumen por llamada. Recibes el conjunto completo, o la única fila que nombraste.

• pageSize se limita a 100, no se rechaza. Pide más y recibes 100 filas con un 200 — lee pagination.pageSize en la respuesta en vez de confiar en lo que enviaste.

• La escritura masiva de transacciones está topada en 100 ids, y a diferencia de pageSize se rechaza en vez de limitarse: envía 101 y recibes un 400 sin que cambie nada.

• Las claves caducan según el plazo que elijas al crearlas — hasta 90 días en el plan gratuito, 365 en uno de pago. No hay opción de que nunca caduquen.

• Tu plan puede aplicar un límite de ventana de historial que oculta transacciones más antiguas. La respuesta de transacciones lleva los campos historyWindow que te dicen si se aplicó uno y dónde cayó.

• Los planes también indican una asignación de solicitudes de API — 500 en el plan gratuito, más en cada uno de pago.

Lo que no hay: no existe limitación por solicitud en REST hoy, ni 429, ni cabeceras de límite de tasa — así que una clave filtrada no se ve frenada por nada de nuestro lado. Si alguna vez tienes dudas sobre una clave, revócala: eso la corta al instante (mira Seguridad y manejo de claves más arriba). Y, como esta API está en beta, no des por hecho que eso seguirá siendo así.

Convenciones

Los campos de respuesta van en camelCase. Los parámetros de consulta no distinguen mayúsculas de minúsculas, así que ahí camelCase también funciona: la especificación publicada los escribe en PascalCase, y por eso verás las dos formas dando vueltas.

Un campo que nombra un día del calendario va en YYYY-MM-DD. Un campo que nombra un instante va en ISO 8601 con desfase horario.

Los tamaños de página se recortan, no se rechazan. Pide un pageSize de 500 y recibes 100 filas y un 200, no un error, así que lee de vuelta pagination.pageSize en lugar de confiar en lo que mandaste.

Una respuesta puede traer campos que esta página no lista. Ignora los que no reconozcas en vez de fallar por ellos: eso es lo que mantiene tu cliente funcionando conforme la API va creciendo.

REST es HTTP normal, así que no se necesita ningún SDK para llamarlo: cualquier lenguaje con un cliente HTTP ya sirve. No hay nada que instalar.

Seguridad y gestión de claves

Cuentas

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

Saldo de una cuenta

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

Resumen de cuentas

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

Transacciones

{
  "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": [ … ]
}

Categorías

{
  "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": [ … ],
  …
}

Etiquetas

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