Hediye kartları API

Kodu, bakiyesi, son kullanma tarihi ve tüm geçmişiyle hediye kartları.

Modül kodu gift_cards · 11 işlem · 3 veri modeli · 7 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ı: gift_cards (hepsi), gift_cards:read (yalnız okuma) ya da gift_cards:<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

gift_cards.add_note

Not ekle — Kartın geçmişine bir satır.

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

• Asıl adres: POST /api/v1/actions/gift_cards.add_note

Girdi

Ön koşullar

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

Yayımladığı olaylar: gift_cards.updated

Neye yazar: gift_card_event (insert) — Records the note

curl -X POST https://app.getera.io/api/v1/gift_card_events/actions/add_note \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"GIFT_CARD_ID","message":"Note"}'

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

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCardEvents.addNote({
  id: "GIFT_CARD_ID",
  message: "Note"
})

era gift_card_events add_note \
  --id "GIFT_CARD_ID" \
  --message "Note"

{
  "name": "era__gift_cards__add_note",
  "arguments": {
    "id": "GIFT_CARD_ID",
    "message": "Note"
  }
}

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

gift_cards.bulk_issue

Toplu hediye kartı oluştur — Aynı bakiye ve son kullanma tarihiyle, her biri kendi koduyla birçok kart.

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

• Asıl adres: POST /api/v1/actions/gift_cards.bulk_issue

Girdi

Ön koşullar

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

Yayımladığı olaylar: gift_cards.issued

Neye yazar: gift_card (insert) — Issues the cards; gift_card_event (insert) — Records each issue

curl -X POST https://app.getera.io/api/v1/gift_cards/actions/bulk_issue \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"count":1,"amount":1}'

{
  "ok": true,
  "result": "…",
  "events": [
    "gift_cards.issued"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCards.bulkIssue({
  count: 1,
  amount: 1
})

era gift_cards bulk_issue \
  --count 1 \
  --amount 1

{
  "name": "era__gift_cards__bulk_issue",
  "arguments": {
    "count": 1,
    "amount": 1
  }
}

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

gift_cards.expire_due

Süresi dolan kartları kapat — Son kullanma tarihi geçmiş her aktif kartı kapatır.

Gereken izin gift_cards:manage · veriyi değiştirir

• Asıl adres: POST /api/v1/actions/gift_cards.expire_due

Girdi

Yayımladığı olaylar: gift_cards.status_changed

Neye yazar: gift_card (update) — Deactivates it; gift_card_event (insert) — Records why

curl -X POST https://app.getera.io/api/v1/gift_card_events/actions/expire_due \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"asOf":"2026-11-02"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "gift_cards.status_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCardEvents.expireDue({
  asOf: "2026-11-02"
})

era gift_card_events expire_due \
  --as-of "2026-11-02"

{
  "name": "era__gift_cards__expire_due",
  "arguments": {
    "asOf": "2026-11-02"
  }
}

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

gift_cards.issue

Hediye kartı oluştur — Bakiyesi, kodu ve isteğe bağlı son kullanma tarihi olan yeni bir kart.

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

• Asıl adres: POST /api/v1/actions/gift_cards.issue

Girdi

Ön koşullar

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

Yayımladığı olaylar: gift_cards.issued

Neye yazar: gift_card (insert) — Issues the card; gift_card_event (insert) — Records the issue

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

{
  "ok": true,
  "result": "…",
  "events": [
    "gift_cards.issued"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCards.issue({
  amount: 1
})

era gift_cards issue \
  --amount 1

{
  "name": "era__gift_cards__issue",
  "arguments": {
    "amount": 1
  }
}

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

gift_cards.redeem

Hediye kartını kullan — Bakiyeden harcar. Tekrarlanan bir kullanım hiçbir şeyi iki kez harcamaz.

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

• Asıl adres: POST /api/v1/actions/gift_cards.redeem

Girdi

Ön koşullar

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

Yayımladığı olaylar: gift_cards.redeemed

Neye yazar: gift_card (update) — Lowers the balance; gift_card_event (insert) — Records the redemption

curl -X POST https://app.getera.io/api/v1/gift_cards/GIFT_CARD_ID/actions/redeem \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"amount":1,"currency":"Currency"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "gift_cards.redeemed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCards.redeem("GIFT_CARD_ID", {
  amount: 1,
  currency: "Currency"
})

era gift_cards redeem GIFT_CARD_ID \
  --amount 1 \
  --currency "Currency"

{
  "name": "era__gift_cards__redeem",
  "arguments": {
    "giftCardId": "GIFT_CARD_ID",
    "amount": 1,
    "currency": "Currency"
  }
}

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

gift_cards.refund

Hediye kartına iade et — Karttan harcanan parayı karta geri yükler.

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

• Asıl adres: POST /api/v1/actions/gift_cards.refund

Girdi

Ön koşullar

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

Yayımladığı olaylar: gift_cards.refunded

Neye yazar: gift_card (update) — Raises the balance; gift_card_event (insert) — Records the refund

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

{
  "ok": true,
  "result": "…",
  "events": [
    "gift_cards.refunded"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCards.refund("GIFT_CARD_ID", {
  amount: 1
})

era gift_cards refund GIFT_CARD_ID \
  --amount 1

{
  "name": "era__gift_cards__refund",
  "arguments": {
    "id": "GIFT_CARD_ID",
    "amount": 1
  }
}

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

gift_cards.reset_balance

Bakiyeyi düzelt — Bakiyeyi elle belirler; neden kartın geçmişine yazılır.

Gereken izin gift_cards: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/gift_cards.reset_balance

Girdi

Ön koşullar

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

Yayımladığı olaylar: gift_cards.updated

Neye yazar: gift_card (update) — Writes the balance; gift_card_event (insert) — Records the correction

curl -X POST https://app.getera.io/api/v1/gift_cards/GIFT_CARD_ID/actions/reset_balance \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"balance":1,"reason":"Reason"}'

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

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCards.resetBalance("GIFT_CARD_ID", {
  balance: 1,
  reason: "Reason"
})

era gift_cards reset_balance GIFT_CARD_ID \
  --balance 1 \
  --reason "Reason"

{
  "name": "era__gift_cards__reset_balance",
  "arguments": {
    "id": "GIFT_CARD_ID",
    "balance": 1,
    "reason": "Reason"
  }
}

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

gift_cards.send

Müşteriye gönder — Kartı bildirimler modülü üzerinden e-postayla gönderir; kayıt, gidip gitmediğini gösterir.

Gereken izin gift_cards:write · 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/gift_cards.send

Girdi

Ön koşullar

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

Yayımladığı olaylar: gift_cards.send_requested

Neye yazar: gift_card_event (insert) — Records who it was sent to

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

{
  "ok": true,
  "result": "…",
  "events": [
    "gift_cards.send_requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCardEvents.send({
  id: "GIFT_CARD_ID"
})

era gift_card_events send \
  --id "GIFT_CARD_ID"

{
  "name": "era__gift_cards__send",
  "arguments": {
    "id": "GIFT_CARD_ID"
  }
}

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

gift_cards.set_active

Etkinleştir veya devre dışı bırak — Devre dışı kart bakiyesini korur ama harcanamaz.

Gereken izin gift_cards:manage · veriyi değiştirir

• Asıl adres: POST /api/v1/actions/gift_cards.set_active

Girdi

Ön koşullar

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

Yayımladığı olaylar: gift_cards.status_changed

Neye yazar: gift_card (update) — Flips the card; gift_card_event (insert) — Records it

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

{
  "ok": true,
  "result": "…",
  "events": [
    "gift_cards.status_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCards.setActive("GIFT_CARD_ID", {
  active: true
})

era gift_cards set_active GIFT_CARD_ID \
  --active true

{
  "name": "era__gift_cards__set_active",
  "arguments": {
    "id": "GIFT_CARD_ID",
    "active": true
  }
}

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

gift_cards.set_expiry

Son kullanma tarihini değiştir — Son kullanma tarihini taşır veya kaldırır.

Gereken izin gift_cards:manage · veriyi değiştirir

• Asıl adres: POST /api/v1/actions/gift_cards.set_expiry

Girdi

Ön koşullar

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

Yayımladığı olaylar: gift_cards.updated

Neye yazar: gift_card (update) — Writes the expiry; gift_card_event (insert) — Records the change

curl -X POST https://app.getera.io/api/v1/gift_cards/GIFT_CARD_ID/actions/set_expiry \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"expiryDate":"2026-11-02"}'

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

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.giftCards.setExpiry("GIFT_CARD_ID", {
  expiryDate: "2026-11-02"
})

era gift_cards set_expiry GIFT_CARD_ID \
  --expiry-date "2026-11-02"

{
  "name": "era__gift_cards__set_expiry",
  "arguments": {
    "id": "GIFT_CARD_ID",
    "expiryDate": "2026-11-02"
  }
}

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

gift_cards.site_apply

Hediye kartı kullan (site) — Ziyaretçi sepetine ya da ödeme bağlantısına bir hediye kartı ekler: kartın karşıladığı tutar 15 dakika ayrılır ve ödeme adımında karttan düşülür. Boş kod kartı kaldırır.

Gereken izin gift_cards:write · veriyi değiştirir · Yayındaki bir siteden de çağrılabilir (visitor)

• Asıl adres: POST /api/v1/actions/gift_cards.site_apply

Girdi

Ön koşullar

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

Yayımladığı olaylar: gift_cards.hold_changed

Neye yazar: gift_card_hold (insert) — Holds the part of the card that pays; gift_card_hold (update) — Lets go of an earlier hold on the same checkout

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde gift_cards:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 basket_not_found, pay_link_invalid, nothing_due, gift_card_not_found, gift_card_inactive, gift_card_expired, gift_card_currency_mismatch, gift_card_insufficient_balance · 429 çok sık istek

Veri modelleri

GiftCardEvent

Tablo gift_card_event · Kaynak gift_card_events

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

Birincil anahtar: id

Denetimler:

• CHECK ((balance_after >= 0))
• CHECK ((currency ~ '^[A-Z]{3}$'::text))

GiftCardHold

Tablo gift_card_hold · Kaynak gift_card_holds

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

Birincil anahtar: id

Denetimler:

• CHECK ((amount > 0))
• CHECK ((NOT ((redeemed_at IS NOT NULL) AND (released_at IS NOT NULL))))

GiftCard

Tablo gift_card · Kaynak gift_cards

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

Birincil anahtar: id

Denetimler:

• CHECK (((length(code) >= 8) AND (length(code) <= 16)))
• CHECK ((currency ~ '^[A-Z]{3}$'::text))
• CHECK ((current_balance_amount >= 0))
• CHECK ((initial_balance_amount >= 0))

Olaylar

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