Bütçeler API

Her gider kategorisi için harcama planı; aşıldığında uyarır.

Modül kodu budgets · 6 işlem · 2 veri modeli · 5 olay. Bir anahtar ya da token, arkasındaki kişinin bu modülde yapabildiğinden fazlasını asla yapamaz; satır düzeyindeki güvenlik uygulamadakiyle birebir aynıdır. Yetki kapsamları: budgets (hepsi), budgets:read (yalnız okuma) ya da budgets:<yetenek>.

Kaynaklar

Listeler limit (en çok 200), cursor, order (ör. -created_at), fields ve q alır; diğer her sorgu parametresi bir sütun süzgecidir: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

İşlemler

budgets.check_alerts

Bütçe uyarılarını kontrol et — Gerçek harcamayı planla karşılaştırır ve her eşik için bir kez uyarı verir.

Gereken izin budgets:write · veriyi değiştirir

• Asıl adres: POST /api/v1/actions/budgets.check_alerts

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: budgets.threshold_reached, budgets.exceeded

Neye yazar: budget_line (update) — Stamps the alert level

curl -X POST https://app.getera.io/api/v1/budget_lines/actions/check_alerts \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"expenseId":"EXPENSE_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "budgets.threshold_reached",
    "budgets.exceeded"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.budgetLines.checkAlerts({
  expenseId: "EXPENSE_ID"
})

era budget_lines check_alerts \
  --expense-id "EXPENSE_ID"

{
  "name": "era__budgets__check_alerts",
  "arguments": {
    "expenseId": "EXPENSE_ID"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde budgets:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 expense_not_found · 429 çok sık istek

budgets.close

Bütçeyi kapat — Planı dondurur; artık uyarı üretmez.

Gereken izin budgets:manage · dışarıya ulaşır (gönderir, yayımlar ya da ücret alır) · Era çalıştırırken bir kişiye onaylatır

• Asıl adres: POST /api/v1/actions/budgets.close

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: budgets.closed

Neye yazar: budget (update) — Closes it

curl -X POST https://app.getera.io/api/v1/budgets/BUDGET_ID/actions/close \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "budgets.closed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.budgets.close("BUDGET_ID")

era budgets close BUDGET_ID

{
  "name": "era__budgets__close",
  "arguments": {
    "id": "BUDGET_ID"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde budgets:manage izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 budget_not_found, budget_closed · 429 çok sık istek

budgets.create

Bütçe planla — Bir dönem, bir para birimi ve gider kategorisi başına planlanan tutar.

Gereken izin budgets:write · veriyi değiştirir

• REST kısayolu: POST /api/v1/budgets
• Asıl adres: POST /api/v1/actions/budgets.create

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: budgets.created

Neye yazar: budget (insert) — Plans the budget; budget_line (insert) — Writes its lines

curl -X POST https://app.getera.io/api/v1/budgets/actions/create \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name","periodStart":"2026-11-02","periodEnd":"2026-11-02"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "budgets.created"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.budgets.create({
  name: "Name",
  periodStart: "2026-11-02",
  periodEnd: "2026-11-02"
})

era budgets create \
  --name "Name" \
  --period-start "2026-11-02" \
  --period-end "2026-11-02"

{
  "name": "era__budgets__create",
  "arguments": {
    "name": "Name",
    "periodStart": "2026-11-02",
    "periodEnd": "2026-11-02"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde budgets:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 budget_period_invalid, invalid_currency, invalid_budget_lines, expense_category_not_available · 429 çok sık istek

budgets.remove_line

Kategoriyi kaldır — Bir kategoriyi plandan çıkarır.

Gereken izin budgets:write · siler ya da geri alınamaz · Era çalıştırırken bir kişiye onaylatır

• Asıl adres: POST /api/v1/actions/budgets.remove_line

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: budgets.updated

Neye yazar: budget_line (delete) — Removes the line

curl -X POST https://app.getera.io/api/v1/budget_lines/BUDGET_LINE_ID/actions/remove_line \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "budgets.updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.budgetLines.removeLine("BUDGET_LINE_ID")

era budget_lines remove_line BUDGET_LINE_ID

{
  "name": "era__budgets__remove_line",
  "arguments": {
    "id": "BUDGET_LINE_ID"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde budgets:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 budget_line_not_found, budget_closed · 429 çok sık istek

budgets.set_line

Kategoriyi planla — Bir gider kategorisi için planlanan tutarı belirler.

Gereken izin budgets:write · veriyi değiştirir

• Asıl adres: POST /api/v1/actions/budgets.set_line

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: budgets.updated

Neye yazar: budget_line (upsert) — Writes the line

curl -X POST https://app.getera.io/api/v1/budget_lines/actions/set_line \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"budgetId":"BUDGET_ID","categoryId":"EXPENSE_CATEGORY_ID","plannedAmount":1}'

{
  "ok": true,
  "result": "…",
  "events": [
    "budgets.updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.budgetLines.setLine({
  budgetId: "BUDGET_ID",
  categoryId: "EXPENSE_CATEGORY_ID",
  plannedAmount: 1
})

era budget_lines set_line \
  --budget-id "BUDGET_ID" \
  --category-id "EXPENSE_CATEGORY_ID" \
  --planned-amount 1

{
  "name": "era__budgets__set_line",
  "arguments": {
    "budgetId": "BUDGET_ID",
    "categoryId": "EXPENSE_CATEGORY_ID",
    "plannedAmount": 1
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde budgets:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 budget_not_found, budget_closed, invalid_budget_lines, expense_category_not_available · 429 çok sık istek

budgets.update

Bütçeyi düzenle — Yeniden adlandırır, uyarı eşiğini değiştirir ya da taslak ile aktif arasında geçirir.

Gereken izin budgets:write · veriyi değiştirir

• REST kısayolu: PATCH /api/v1/budgets/{id}
• Asıl adres: POST /api/v1/actions/budgets.update

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: budgets.updated

Neye yazar: budget (update) — Updates the budget; budget_line (update) — Clears alerts when the threshold moves

curl -X POST https://app.getera.io/api/v1/budgets/BUDGET_ID/actions/update \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "budgets.updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.budgets.update("BUDGET_ID", {
  name: "Name"
})

era budgets update BUDGET_ID \
  --name "Name"

{
  "name": "era__budgets__update",
  "arguments": {
    "id": "BUDGET_ID",
    "name": "Name"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde budgets:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 budget_not_found, budget_closed · 429 çok sık istek

Veri modelleri

BudgetLine

Tablo budget_line · Kaynak budget_lines

• GET /api/v1/budget_lines
• GET /api/v1/budget_lines/{id}

Birincil anahtar: id

Tekil: budget_id, expense_category_id

Denetimler:

• CHECK (((alert_level IS NULL) OR (alert_level = ANY (ARRAY['warning'::text, 'exceeded'::text]))))
• CHECK ((planned_amount >= 0))

Budget

Tablo budget · Kaynak budgets

• GET /api/v1/budgets
• GET /api/v1/budgets/{id}
• POST /api/v1/budgets → budgets.create
• PATCH /api/v1/budgets/{id} → budgets.update

Birincil anahtar: id

Denetimler:

• CHECK (((alert_threshold_percent > (0)::numeric) AND (alert_threshold_percent <= (100)::numeric)))
• CHECK ((currency ~ '^[A-Z]{3}$'::text))
• CHECK ((length(TRIM(BOTH FROM name)) > 0))
• CHECK ((period_end >= period_start))

Olaylar

İş akışları ve webhook'lar bu olaylara tepki verir.