API di Era

Avvio rapido

Prima di iniziare ti serve un account Era con almeno un istituto collegato: senza una connessione questi endpoint non hanno niente da restituire.

1. 1

   Accedi a Era e collega un istituto, se non l'hai già fatto.

2. 2

   Apri le tue chiavi API nella dashboard e creane una. All'inizio sono spuntati tutti gli scope, quindi togli la spunta a quelli che non ti servono — per questi endpoint resta banking:read. Scegli anche una scadenza; non esiste un'opzione senza scadenza.

3. 3

   Copia la chiave. Viene mostrata una volta sola e non possiamo mostrartela di nuovo. Copiala e conservala in un posto sicuro, come un gestore di segreti. Se perdi una chiave, non puoi più vederla. Creane una nuova al suo posto.

4. 4

   Mandala in un header insieme alla tua richiesta.

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 disponibili

L'API di Era include le seguenti API:

• GET/banking/accounts

  Ogni account che puoi vedere, su tutte le istituzioni collegate.

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

  Il saldo di un account, con i campi di credito compilati se è una passività.

• GET/banking/accounts/summary

  I totali su tutti gli account che puoi vedere.

• GET/banking/transactions

  Le tue transazioni, una pagina alla volta.

• PUT/banking/transactions/{id}

  Modifica una transazione

• PUT/banking/transactions/bulk

  Modifica fino a 100 alla volta

• GET/banking/categories

  L'intera tassonomia delle categorie, con le sottocategorie annidate.

• POST/banking/categories

  Aggiungi una categoria

• GET/banking/tags

  Tutti i tag del tuo account, in un'unica risposta.

• POST/banking/tags

  Crea un tag

Autenticazione

Invia la tua chiave in uno di questi due modi:

Ogni richiesta è cifrata con TLS.

Le chiavi scadono, e quando ne crei una scegli tu tra quanto. La durata massima disponibile è di 90 giorni sul piano gratuito e di 365 su uno a pagamento: non esiste un'opzione senza scadenza, quindi qualsiasi cosa tu costruisca su questo ha bisogno di un piano per ruotare la chiave prima che scada.

Header di risposta

Ogni risposta include:

Errori

L'API restituisce questi codici di stato di errore:

• 400

  Input malformato: un parametro sbagliato, un aggiornamento massivo vuoto o con più di 100 elementi, o una scrittura che imposta e cancella lo stesso campo nella stessa chiamata.

• 401

  Nessuna chiave, o una che non si può interpretare. Inviala nell'intestazione X-API-Key o come token bearer.

• 402

  Una quota del piano è d'intralcio — oggi succede solo con la creazione di categorie.

• 403

  La chiave non porta lo scope di cui questa chiamata ha bisogno — oppure, su una delle due scritture di transazioni, l'id appartiene a qualcun altro o non esiste affatto. L'API non distingue i due casi.

• 409

  Qualcos'altro ha cambiato la riga mentre stavi scrivendo. Rileggila e reinvia la tua scrittura.

Forme di errore

Ogni errore torna nella stessa forma: statusCode, message e un oggetto errors che indica cosa non andava. Una chiave mancante o non valida può tornare senza alcun corpo.

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

ID richiesta

Ogni risposta porta un'intestazione fly-request-id. Includila quando contatti il supporto per una richiesta specifica.

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

Errori comuni

• Impostare un campo e cancellarlo nella stessa scrittura — 400.

• Più di 100 id in un aggiornamento massivo — 400, e non cambia nulla. Meno di uno è lo stesso.

• Una transazione che non è tua, o che non esiste — 403, mai 404. Quindi la risposta non ti dice mai se un id esiste, solo che non è tuo da vedere.

• Qualcos'altro ha cambiato la riga per primo — 409.

Limiti

Due dei dieci endpoint documentati limitano quanto puoi chiedere in una singola chiamata. Gli altri otto no.

Questo non significa illimitato: le chiavi continuano a scadere, le scritture hanno comunque limiti di lunghezza dei campi, e il tuo piano può comunque nascondere lo storico più vecchio. Niente di tutto questo è un rate limit — vedi sotto.

• Account, saldo, riepilogo, categorie, tag e la scrittura di una singola transazione non hanno alcun limite di volume per chiamata. Ricevi l'intero insieme, oppure la singola riga che hai indicato.

• pageSize è limitato a 100, non rifiutato. Chiedine di più e ricevi 100 righe con un 200 — leggi pagination.pageSize nella risposta invece di fidarti di ciò che hai inviato.

• La scrittura massiva delle transazioni è limitata a 100 id, e a differenza di pageSize viene rifiutata anziché limitata: invia 101 e ricevi un 400, senza che nulla cambi.

• Le chiavi scadono secondo il programma che scegli alla creazione — fino a 90 giorni nel piano gratuito, 365 in uno a pagamento. Non esiste un'opzione senza scadenza.

• Il tuo piano può applicare un limite di finestra della cronologia che nasconde le transazioni più vecchie. La risposta delle transazioni porta i campi historyWindow che dicono se un limite si è applicato e dove è caduto.

• I piani indicano anche un'assegnazione di richieste API — 500 nel piano gratuito, di più in ogni piano a pagamento.

Cosa manca: oggi su REST non c'è nessuna limitazione per richiesta, nessun 429, e nessuna intestazione di limite di frequenza — quindi una chiave trapelata non viene rallentata da nulla dal nostro lato. Se hai mai un dubbio su una chiave, revocala: la disattiva subito (vedi Sicurezza e gestione della chiave più sopra). E, dato che questa API è in beta, non dare per scontato che rimanga così.

Convenzioni

I campi delle risposte sono in camelCase. I parametri di query non distinguono maiuscole e minuscole, quindi lì funziona anche il camelCase: la specifica pubblicata li scrive in PascalCase, ed è per questo che in giro vedi entrambe le forme.

Un campo che indica un giorno di calendario è in formato YYYY-MM-DD. Un campo che indica un istante è in ISO 8601 con l'offset.

Le dimensioni delle pagine vengono limitate, non rifiutate. Chiedi un pageSize di 500 e ottieni 100 righe e un 200, non un errore: leggi quindi pagination.pageSize invece di fidarti di quello che hai mandato.

Una risposta può portare campi che questa pagina non elenca. Ignora quelli che non riconosci invece di fallire: è questo che tiene in piedi il tuo client mentre l'API cresce.

REST è semplice HTTP, quindi per chiamarlo non serve nessun SDK: va bene qualsiasi linguaggio con un client HTTP. Non c'è niente da installare.

Sicurezza e gestione delle chiavi

Conti

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

Saldo di un conto

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

Riepilogo dei conti

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

Transazioni

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

Categorie

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

Tag

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