API de Era

Inicio rápido

Antes de empezar necesitas una cuenta de Era con al menos una institución conectada: sin conexión, estos endpoints no tienen nada que 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 no caduque nunca.

3. 3

   Copia la clave. Se muestra una sola vez y no podemos volver a enseñártela. 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 una cabecera 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

  Añadir 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 al crearlas eliges en cuánto tiempo. Lo máximo son 90 días en el plan gratuito y 365 en uno de pago; no existe la opción de que no caduquen nunca, así que lo que construyas sobre esto necesita un plan para rotar la clave antes de que venza.

Cabeceras de respuesta

Un ID de petición vuelve en todas las respuestas. Las cabeceras de límite vuelven en las llamadas que Era ha medido. Si Era no puede medir tu uso, atiende la llamada y no envía ninguna.

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. Va de qué estás creando, no de a qué velocidad llamas: esperar no lo resuelve y un plan mayor sí. Llamar demasiado rápido es un 429.

• 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.

• 404

  Una cuenta que no existe. Solo lo devuelve el endpoint de saldo: un accountGroupKey que no nombra ninguna cuenta, o que ni siquiera tiene forma de clave, vuelve como 404 sin cuerpo. Las transacciones nunca dan 404 — ver 403.

• 409

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

• 429

  Demasiadas peticiones. Has gastado tu presupuesto diario o has llegado al tope de ráfaga por minuto. Retry-After dice cuánto esperar y, a diferencia de un 402, esperar lo resuelve. En Límites verás qué límite la rechazó y las cifras por plan.

Formas de error

La mayoría de los errores vuelven con la misma forma: statusCode, message y un objeto errors que nombra lo que falló. No todos: un 401 y un 404 vuelven sin cuerpo en absoluto, así que lee el estado antes que el cuerpo.

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

ID de solicitud

Toda respuesta lleva una cabecera fly-request-id. Inclúyela cuando contactes con soporte sobre una solicitud concreta.

# 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, crear una categoría puede alcanzar una cuota del plan, y tu plan puede seguir ocultando historial antiguo. Nada de esto es un límite de tasa — ver más abajo.

• Cuentas, saldo, resumen, las listas de categorías y etiquetas, crear una categoría, crear una etiqueta 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ó.

Límites de tasa

Todos los planes pueden llamar a esta API, y todos están medidos. Lo que cuenta: las llamadas que haces con una clave. Funcionan dos límites a la vez — un presupuesto diario y un tope de ráfaga por minuto — y pasarte de cualquiera de los dos devuelve un 429.

Tu presupuesto diario es tuyo, no de una clave. Todas las claves REST de tu cuenta descuentan del mismo presupuesto diario, así que crear una segunda clave no te compra más llamadas. Las llamadas a herramientas MCP se miden aparte: gastar una nunca gasta la otra.

Cuando Era mide una llamada, la respuesta lleva X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Las tres describen tu presupuesto diario, que se renueva de forma continua a lo largo de 24 horas en vez de reiniciarse a medianoche: las peticiones vuelven de una en una a medida que tus llamadas más antiguas cumplen 24 horas. El tope de ráfaga por minuto no tiene cabecera, así que marca tú el ritmo con la cifra de la tabla. Remaining puede estar muy por encima de cero y, aun así, una ráfaga volver con 429. Si Era no puede medir tu uso, atiende la llamada y no envía cabeceras de límite, así que trata la falta de cabeceras como una lectura que falta, no como un error.

Qué te dice un 429

Un cuerpo problem-details. Su campo detail es texto plano, no campos estructurados: nombra el límite que alcanzaste, lo que permite ese límite, cuándo se libera tu próxima petición y el plan que lo sube, o que ya estás en el más alto. No lo analices. Para ramificar en el código, lee las cabeceras: Remaining en 0 significa que lo rechazó el presupuesto diario, y por encima de 0, el tope de ráfaga por minuto.

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

Un 429 también lleva Retry-After, un número entero de segundos medido desde el límite que rechazó: hasta un minuto para el tope de ráfaga por minuto, hasta 24 horas para el presupuesto diario. Una llamada rechazada no gasta nada, así que reintentar antes no te cuesta nada, pero vuelve con 429 otra vez. Cuando pasa el tiempo de Retry-After, se libera una petición, no el presupuesto entero. Envíala y luego lee las cabeceras o el siguiente Retry-After.

Nada de esto protege una clave que has perdido de vista. Una clave filtrada gasta tu presupuesto igual que lo harías tú. Si tienes dudas sobre una, revócala. Mira Seguridad y gestión de claves más abajo.

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 por ahí.

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 fiarte de 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 a medida que la API va creciendo.

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

Versionado y cambios

Todo lo que está documentado aquí queda cubierto por esta política.

No hay número de versión en la ruta ni cabecera de versión. Cada endpoint tiene una versión activa, y es la que está documentada aquí.

Lo que podemos cambiar sin avisar

Nada de esto rompe un cliente que siga las convenciones de arriba.

• Añadir un endpoint, o una operación sobre uno que ya existe.

• Añadir un campo a una respuesta.

• Añadir un parámetro opcional. Omítelo y no cambia nada.

• Añadir un valor a un conjunto fijo, como un estado o un tipo.

• Añadir una cabecera de respuesta.

Lo que no cambiamos sin avisar

Cualquiera de estos puede romper un cliente que ya funciona.

• Quitar un endpoint, o cambiar su ruta o su método.

• Quitar o renombrar un campo de respuesta.

• Cambiar el tipo de un campo o su significado.

• Volver obligatorio un parámetro que hoy es opcional.

• Rechazar entradas que hoy se aceptan.

• Cambiar el alcance que necesita un endpoint.

Antes de cualquiera de ellos, el changelog lo anuncia con al menos 90 días de antelación y te dice qué cambiar. Lo que funciona hoy sigue funcionando hasta entonces.

Los cambios se anuncian en el changelog, enlazado en la sección Changelog de abajo. Todavía no hay correo ni feed, así que consúltalo cuando planifiques trabajo sobre la API.

Mientras la API esté en beta, el conjunto documentado seguirá creciendo. Lo que ya está aquí no te va a romper nada sin avisar.

Changelog

Novedades de la Era Developer Platform, incluida la API de Era, de la más reciente a la más antigua. La política de arriba dice qué se avisa y con cuánta antelación; el changelog es donde aparecen esos avisos.

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