API da Era

Início rápido

Antes de começar, você precisa de uma conta da Era com pelo menos uma instituição conectada: sem conexão, esses endpoints não têm o que devolver.

1. 1

   Entre na Era e conecte uma instituição, se ainda não tiver feito isso.

2. 2

   Abra suas chaves de API no painel e crie uma. Todos os escopos vêm marcados, então desmarque os que você não precisa — para esses endpoints sobra banking:read. Você também escolhe uma validade; não existe opção de nunca expirar.

3. 3

   Copie a chave. Ela aparece uma vez só, e não conseguimos mostrar de novo. Copie-a e guarde-a em um lugar seguro, como um gerenciador de segredos. Se você perder uma chave, não pode vê-la de novo. Crie uma nova no lugar dela.

4. 4

   Mande no cabeçalho junto com a sua requisição.

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 disponíveis

A API da Era inclui as seguintes APIs:

• GET/banking/accounts

  Cada conta que você pode ver, em todas as instituições conectadas.

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

  O saldo de uma conta, com os campos de crédito preenchidos se for um passivo.

• GET/banking/accounts/summary

  Os totais de todas as contas que você pode ver.

• GET/banking/transactions

  Suas transações, uma página de cada vez.

• PUT/banking/transactions/{id}

  Mudar uma transação

• PUT/banking/transactions/bulk

  Mudar até 100 de uma vez

• GET/banking/categories

  Toda a taxonomia de categorias, com as subcategorias aninhadas.

• POST/banking/categories

  Adicionar uma categoria

• GET/banking/tags

  Todas as tags da sua conta, em uma única resposta.

• POST/banking/tags

  Criar uma etiqueta

Autenticação

Envie sua chave de uma das duas formas:

Toda requisição é criptografada com TLS.

As chaves expiram, e você escolhe em quanto tempo ao criar. O máximo é 90 dias no plano gratuito e 365 num pago — não existe opção de nunca expirar, então o que você construir em cima disso precisa de um plano para rotacionar a chave antes que ela vença.

Cabeçalhos de resposta

Um ID de requisição volta em toda resposta. Os cabeçalhos de limite voltam nas chamadas que a Era mediu. Se a Era não conseguir medir seu uso, ela atende a chamada e não envia nenhum deles.

Erros

A API retorna estes códigos de status de erro:

• 400

  Entrada malformada: um parâmetro incorreto, uma atualização em lote vazia ou com mais de 100 itens, ou uma escrita que define e limpa o mesmo campo na mesma chamada.

• 401

  Sem chave, ou uma que não pode ser interpretada. Envie-a no cabeçalho X-API-Key ou como token bearer.

• 402

  Uma cota do plano está no caminho — hoje, isso só acontece na criação de categorias. É sobre o que você está criando, não sobre a velocidade com que chama: esperar não resolve, um plano maior resolve. Chamar rápido demais é um 429.

• 403

  A chave não carrega o escopo que essa chamada precisa — ou, em qualquer uma das duas escritas de transações, o id pertence a outra pessoa ou não existe. A API não distingue esses dois casos.

• 404

  Uma conta que não existe. Só o endpoint de saldo retorna isso: um accountGroupKey que não indica nenhuma conta, ou que nem tem formato de chave, volta como 404 sem corpo. Transações nunca dão 404 — veja 403.

• 409

  Outra coisa mudou a linha enquanto você escrevia. Leia-a de novo e envie sua escrita de novo.

• 429

  Requisições demais. Você gastou seu orçamento diário ou bateu no teto de rajada por minuto. Retry-After diz quanto esperar e, diferente de um 402, esperar resolve. Veja em Limites qual limite recusou e os números por plano.

Formatos de erro

A maioria dos erros volta na mesma forma: statusCode, message e um objeto errors que nomeia o que deu errado. Nem todos: um 401 e um 404 voltam sem corpo nenhum, então leia o status antes de ler o corpo.

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

ID da solicitação

Toda resposta carrega um cabeçalho fly-request-id. Inclua-o ao entrar em contato com o suporte sobre uma solicitação 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"}'

Erros comuns

• Definir um campo e limpá-lo na mesma escrita — 400.

• Mais de 100 ids em uma atualização em lote — 400, e nada é alterado. Menos de um é igual.

• Uma transação que não é sua, ou que não existe — 403, nunca 404. Então a resposta nunca diz se um id existe, só que não é seu para ver.

• Outra coisa mudou a linha primeiro — 409.

Limites

Dois dos dez endpoints documentados limitam quanto você pode pedir em uma única chamada. Os outros oito não.

Isso não significa ilimitado: as chaves continuam expirando, as escritas continuam com limites de tamanho de campo, criar uma categoria pode atingir uma cota do plano, e seu plano ainda pode ocultar histórico antigo. Nada disso é um limite de taxa — veja abaixo.

• Contas, saldo, resumo, as listas de categorias e tags, criar uma categoria, criar uma tag e a escrita de uma única transação não têm limite de volume por chamada. Você recebe o conjunto inteiro de volta, ou a única linha que você nomeou.

• pageSize é limitado a 100, não recusado. Peça mais e você recebe 100 linhas de volta com um 200 — leia pagination.pageSize na resposta em vez de confiar no que você enviou.

• A escrita em lote de transações é limitada a 100 ids, e diferente de pageSize ela é recusada em vez de limitada: envie 101 e você recebe um 400, e nada muda.

• As chaves expiram conforme o prazo que você escolhe na criação — até 90 dias no plano gratuito, 365 em um pago. Não existe opção que nunca expira.

• Seu plano pode aplicar um piso de janela de histórico que esconde transações mais antigas. A resposta de transações carrega os campos historyWindow que dizem se um piso se aplicou e onde ele caiu.

Limites de taxa

Todo plano pode chamar essa API, e todo plano é medido. O que conta: as chamadas que você faz com uma chave. Dois limites valem ao mesmo tempo — um orçamento diário e um teto de rajada por minuto — e passar de qualquer um deles volta como 429.

Seu orçamento diário é seu, não da chave. Todas as chaves REST da sua conta descontam do mesmo orçamento diário, então criar uma segunda chave não compra mais chamadas. As chamadas de ferramentas MCP são contadas à parte: gastar uma nunca gasta a outra.

Quando a Era mede uma chamada, a resposta carrega X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Os três descrevem seu orçamento diário, que se renova continuamente ao longo de 24 horas em vez de zerar à meia-noite: as requisições voltam uma de cada vez conforme suas chamadas mais antigas completam 24 horas. O teto de rajada por minuto não tem cabeçalho, então controle o ritmo você mesmo pelo número da tabela. O Remaining pode estar bem acima de zero e, ainda assim, uma rajada voltar com 429. Se a Era não conseguir medir seu uso, ela atende a chamada e não envia cabeçalhos de limite, então trate a falta de cabeçalhos como uma leitura ausente, não como um erro.

O que um 429 te diz

Um corpo problem-details. O campo detail é texto simples, não campos estruturados: ele diz qual limite você atingiu, quanto esse limite permite, quando sua próxima requisição é liberada e o plano que o aumenta, ou que você já está no mais alto. Não faça parse dele. Para ramificar no código, leia os cabeçalhos: Remaining em 0 significa que o orçamento diário recusou, e acima de 0, que foi o teto de rajada 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."
}

Um 429 também carrega Retry-After, um número inteiro de segundos medido a partir do limite que recusou: até um minuto para o teto de rajada por minuto, até 24 horas para o orçamento diário. Uma chamada recusada não gasta nada, então tentar de novo cedo não custa nada, mas ela volta com 429 outra vez. Quando o Retry-After passa, uma requisição é liberada, não o orçamento inteiro. Envie-a e depois leia os cabeçalhos ou o próximo Retry-After.

Nada disso protege uma chave que você perdeu de vista. Uma chave vazada gasta seu orçamento exatamente como você gastaria. Se tiver dúvida sobre alguma, revogue-a. Veja Segurança e gestão de chaves abaixo.

Convenções

Os campos de resposta são camelCase. Os parâmetros de consulta não diferenciam maiúsculas de minúsculas, então camelCase funciona ali também — a especificação publicada escreve em PascalCase, e é por isso que você vê as duas formas por aí.

Um campo que nomeia um dia do calendário vem em YYYY-MM-DD. Um campo que nomeia um instante vem em ISO 8601 com o deslocamento de fuso.

Os tamanhos de página são limitados, não recusados. Peça um pageSize de 500 e você recebe 100 linhas e um 200, não um erro — então leia pagination.pageSize de volta em vez de confiar no que você mandou.

Uma resposta pode carregar campos que esta página não lista. Ignore os que você não reconhece em vez de falhar por causa deles — é isso que mantém o seu cliente funcionando conforme a API cresce.

REST é HTTP puro, então não precisa de SDK nenhum para chamar: qualquer linguagem com um cliente HTTP já serve. Não há nada para instalar.

Versionamento e mudanças

Tudo que está documentado aqui é coberto por esta política.

Não há número de versão no caminho nem cabeçalho de versão. Cada endpoint tem uma única versão ativa, e é a que está documentada aqui.

O que podemos mudar sem aviso

Nada disso quebra um cliente que segue as convenções acima.

• Adicionar um endpoint, ou uma operação em um que já existe.

• Adicionar um campo a uma resposta.

• Adicionar um parâmetro opcional. Deixe de fora e nada muda.

• Adicionar um valor a um conjunto fixo, como um status ou um tipo.

• Adicionar um cabeçalho de resposta.

O que não mudamos sem aviso

Qualquer um destes pode quebrar um cliente que já funciona.

• Remover um endpoint, ou mudar o caminho ou o método dele.

• Remover ou renomear um campo de resposta.

• Mudar o tipo de um campo ou o que ele significa.

• Tornar obrigatório um parâmetro que hoje é opcional.

• Recusar uma entrada que hoje é aceita.

• Mudar o escopo que um endpoint exige.

Antes de qualquer uma delas, o changelog avisa com pelo menos 90 dias de antecedência e diz o que mudar. O que funciona hoje continua funcionando até lá.

As mudanças são anunciadas no changelog, com link na seção Changelog abaixo. Ainda não há e-mail nem feed, então confira lá quando estiver planejando trabalho sobre a API.

Enquanto a API estiver em beta, o conjunto documentado vai continuar crescendo. O que já está aqui não vai quebrar sem aviso.

Changelog

Novidades da Era Developer Platform, incluindo a API da Era, da mais recente para a mais antiga. A política acima diz o que recebe aviso e com quanta antecedência; o changelog é onde esses avisos aparecem.

Segurança e gestão de chaves

Contas

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

Saldo de uma conta

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

Resumo das contas

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

Transações

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

Categorias

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