2. Temel bilgiler
2.1 Ortamlar
| Ortam | Adres | Ne için |
|---|---|---|
| Test | https://partner-api.firsat.dev | Geliştirme ve test. Sahte kuponlar, bir test işletmesi. |
| Canlı | https://partner-api.firsat.com | Gerçek restoranlar, gerçek para. |
Test ve canlı ortamın kimlik bilgileri farklıdır. Test token'ı canlıda çalışmaz, tersi de çalışmaz.
Token isteği POST /api/partner/oauth/token adresindedir. Bu rehberdeki diğer tüm API yolları /api/partner/pos/v1 ile başlar. Yani "POST /redemptions" demek POST https://partner-api.firsat.dev/api/partner/pos/v1/redemptions demektir.
İhtiyacınız olabilecek iki adres daha:
GET <host>/healthcevabı{"ok":true}. Token istemez; bağlantı kontrolü için kullanışlıdır.GET <host>/openapi/jsonmakinenin okuyabileceği API tanımıdır. Bununla client üretebilirsiniz.
2.2 Format kuralları
- Gövde: JSON (
Content-Type: application/json). Tek istisna token isteğidir; oapplication/x-www-form-urlencodedda kabul eder. - Gövde boyutu: istek başına en fazla 64 KiB. Gerçek istekler birkaç KB'dır.
- Para: TL cinsinden sayı, en fazla 2 ondalık.
95= 95,00 TL,99.5= 99,50 TL. Ondalık ayraç noktadır. Parayı asla string olarak göndermeyin. - Zaman: UTC cinsinden ISO 8601, ör.
2026-10-08T12:40:00.000Z. Göstermeden önce yerel saate (Europe/Istanbul) çevirin. - Id'ler: bizim id'lerimiz UUID'dir (ör.
0199a3c2-7f1e-7c3a-9d2b-5e8f0a1b2c3d). String olarak saklayın; büyük/küçük harfini veya formatını asla değiştirmeyin.
2.3 Header'lar
| Header | Ne zaman | Örnek |
|---|---|---|
Authorization: Bearer <access_token> | Token isteği ve /health dışındaki her çağrıda | Authorization: Bearer fpt_Xk3… |
X-Firsat-Pos: <POS header id'niz> | Token isteği ve /health dışındaki her çağrıda, Fırsat'ın verdiği gibi aynen. Yoksa veya biçimi bozuksa 400 POS_SOLUTION_HEADER_REQUIRED; token'ınızın ait olduğu header id değilse 403 POS_SOLUTION_HEADER_MISMATCH döner. | X-Firsat-Pos: adisyo/k7qm2x |
X-Firsat-Connection: <connectionId> | Bir işletme adına yapılan her çağrıda (token isteği, claim ve /health dışında hepsi) | X-Firsat-Connection: 0199a3c2-… |
Idempotency-Key: <sizin key'iniz> | Sadece POST /redemptions (onay) çağrısında | Idempotency-Key: 6f1c2b8e-4c1d-4a8b-9e3f-2a7d5c9b1e04 |
Content-Type: application/json | Gövdesi olan her istekte |
2.4 Hata formatı
Her hata cevabı aynı şekildedir (application/problem+json):
{
"type": "about:blank",
"title": "Conflict",
"status": 409,
"code": "POS_REDEMPTION_FAILED",
"detail": "the redemption was refused",
"correlationId": "c0ffee12-3456-7890-abcd-ef0123456789",
"details": { "reason": "used" }
}- Ne yapacağınıza
statusvecodeile karar verin (bu rehberin andığı yerlerdedetails.code/details.reasonile de).detailalanını asla parse etmeyin; insanlar için yazılmış bir cümledir ve değişebilir. - Her hatada
correlationId'yi loglayın. Fırsat desteğine (dev@firsat.com) yazarken bunu gönderin; tam olarak hangi istek olduğunu bulmamızı sağlar. detailssadece bazı hatalarda bulunur. Bölüm 9'da hepsi listeli.