# Kart Kampanyaları ve Fırsatlar (SBX-FIRSAT)

Wings, World, Bonus, Maximum ve Axess'in güncel kart kampanyaları — taksit, indirim, puan ve çekilişler — sektöre ve hedef kitle segmentine (öğrenci, tatilci, araç sahibi vb.) göre etiketlenmiş, her gün yenilenir.

Sürüm: v1.0

## Kimlik doğrulama

API anahtarınızı her istekte Bearer token olarak ya da `apikey` sorgu parametresiyle gönderin:

```
Authorization: Bearer <API_ANAHTARINIZ>
https://api.servicebox.io/v1/deals/...?apikey=<API_ANAHTARINIZ>
```

Anahtar almak için https://servicebox.io/signup adresinden kaydolun ve panelden bir anahtar oluşturun. Bir ajan `POST https://api.servicebox.io/v1/accounts` ve `{"email": "...", "apis": ["deals"]}` ile kendisi kaydolabilir: e-posta sahibi e-postadaki bağlantıyla onaylar, ajan dönen `poll_url` adresini yoklayarak kısa ömürlü bir anahtar alır.

## Temel URL

`https://api.servicebox.io`

## Uç noktalar

### GET /v1/deals/campaigns

**List card campaigns**

The current campaigns of Turkish credit-card programs — Wings, World, Bonus, Maximum and Axess — read daily from the programs' public campaign pages: installment offers, discounts, points (chip-para, Bonus, Worldpuan, MaxiPuan, miles) and prize draws, with the merchant, dates, amounts parsed from the headline, our sector tags and audience segments (student, traveler, driver, homemaker, …). Filter by `card`, `sector`, `segment`, `reward`, `brand`, a text search `q` (Turkish letters optional), and `ending_within` days; `status=ended` lists what ended in the last week. Soonest to end first. Use when the user asks what campaigns, discounts, installment offers or points their card has, for a shop or brand, for a kind of spending (market, fuel, travel, clothing), or for a kind of person; link the `url` for the terms — the program's page is authoritative.

**Kredi:** çağrı başına 1

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `card` | query | string | hayır | Comma-separated card program ids from /deals/cards, e.g. bonus,axess. |
| `sector` | query | string | hayır | Comma-separated sector ids from /deals/sectors (any of), e.g. grocery,dining. |
| `segment` | query | string | hayır | Comma-separated segment ids from /deals/segments (any of), e.g. student,traveler. |
| `reward` | query | string | hayır | Comma-separated reward types (any of): installment, discount, points, draw, other. |
| `brand` | query | string | hayır | A merchant name as it appears in `brand`, e.g. Trendyol (case-insensitive). |
| `q` | query | string | hayır | Words to find at the start of words of the title, brand or summary; Turkish letters optional: `market`, `akaryakit`, `trendyol`. |
| `status` | query | string (`active`, `ended`, `all`) | hayır | `active` (default), `ended` (ended within the last 7 days) or `all`. |
| `ending_within` | query | integer | hayır | Only active campaigns ending within this many days (1–60), soonest first. |
| `limit` | query | integer | hayır | Items per page, 1–200. |
| `cursor` | query | string | hayır | The `next_cursor` of the previous page, with the same filters. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/deals/campaigns" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/deals/campaigns/{id}

**Get a campaign**

One campaign by its id from /deals/campaigns, e.g. bonus:bauhaus-yapi-taksit-kampanyasi. Ended campaigns stay for 7 days, then 404.

**Kredi:** çağrı başına 1

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `id` | path | string | evet | A campaign id, `<card>:<slug>`. |

**Örnek**

```bash
curl "https://api.servicebox.io/v1/deals/campaigns/<id>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/deals/cards

**List card programs**

The five card programs covered — Wings (Şekerbank), World (Yapı Kredi), Bonus (Garanti BBVA), Maximum (İşbank), Axess (Akbank) — with their active campaign count, when each program's page was last read completely (`lastUpdated`), and the attribution to show. Free.

**Kredi:** ücretsiz (çağrı başına 0 kredi)

Parametre yok.

**Örnek**

```bash
curl "https://api.servicebox.io/v1/deals/cards" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/deals/sectors

**List sectors**

What a campaign is for — grocery, fuel & automotive, fashion, electronics, home, travel, dining, education, health, entertainment, online shopping, insurance, bills & taxes, card services, other — in English and Turkish, with active counts. Free.

**Kredi:** ücretsiz (çağrı başına 0 kredi)

Parametre yok.

**Örnek**

```bash
curl "https://api.servicebox.io/v1/deals/sectors" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/deals/segments

**List audience segments**

Who a campaign is for — students, parents, travellers, people spending abroad, car owners, home makers, fashion and tech shoppers, online shoppers, diners, grocery shoppers, culture, health & sport, pet owners, football fans, bill payers, mobile/QR payers, new card applicants — in English and Turkish, with active counts. Free.

**Kredi:** ücretsiz (çağrı başına 0 kredi)

Parametre yok.

**Örnek**

```bash
curl "https://api.servicebox.io/v1/deals/segments" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

## Hatalar

Hatalar, makinece okunabilir bir `type` taşıyan RFC 9457 `application/problem+json` gövdeleridir.

- `401` — anahtar eksik, bilinmiyor, süresi dolmuş ya da iptal edilmiş.
- `402` — kredi yetersiz: gövde `credits_required` ve `upgrade_url` (https://servicebox.io/pricing) taşır.
- `403` — anahtarın bu API'yi çağırma izni yok.
- `429` — hız sınırı: `retry_after` saniye bekleyin (`Retry-After` başlığıyla da gönderilir); `upgrade_url` daha büyük bir plana yönlendirir.

## Bağlantılar

- OpenAPI belgesi: https://api.servicebox.io/v1/deals/openapi.json
- Fiyatlandırma: https://servicebox.io/pricing?api=SBX-FIRSAT
- API sayfası: https://servicebox.io/apis/deals