API Dokümantasyonu

Genel Bakış

Bu servis, MARS Gift Card API, hediye kuponu işlem kodu oluşturma, ödeme/iade işlemleri ve mutabakat raporlaması sağlar.

Base URL: https://connect.marsneo.com

API Version: v1.3

Son Güncelleme Tarihi: 10.02.2026

Content-Type: application/json

Desteklenen Diller: Türkçe (tr), İngilizce (en)

Kimlik Doğrulama (Authentication)

MARS Gift Card API, güvenli kimlik doğrulama için HMAC-SHA256 imza mekanizması kullanır.

Gerekli Header'lar

Her API isteği aşağıdaki header'ları içermelidir:

Header

Tip

Zorunlu

Açıklama

Content-Type

string

Evet

application/json

X-Lang

string

Hayır

Dil kodu (tr/en). Varsayılan: tr

X-Client-Id

string

Evet

İstemci benzersiz kimliği

X-Timestamp

integer

Evet

Unix timestamp (saniye cinsinden)

X-Signature

string

Evet

HMAC-SHA256 imzası

HMAC Signature Oluşturma

İmza aşağıdaki adımlarla oluşturulur:

Data String Oluşturma:

data = "{CLIENT_ID}:{TIMESTAMP}"

HMAC-SHA256 Hesaplama:

signature = HMAC-SHA256(CLIENT_SECRET, data)

Hex Format'a Çevirme:

X-Signature = hex(signature)

Örnek İmza Oluşturma (JavaScript)

const clientId = "21929721-5f5b-4d1f-a857-2ff01be5098g";
const clientSecret = "your-secret-key-here";
const timestamp = Math.floor(Date.now() / 1000).toString();

const data = `${clientId}:${timestamp}`;

const crypto = require('crypto');
const signature = crypto
  .createHmac('sha256', clientSecret)
  .update(data)
  .digest('hex');

// Headers
const headers = {
  'X-Client-Id': clientId,
  'X-Timestamp': timestamp,
  'X-Signature': signature,
  'Content-Type': 'application/json',
  'X-Lang': 'tr'
};

Timestamp Doğrulama Kuralları

Timestamp, Unix epoch formatında (saniye cinsinden) olmalıdır
Sunucu zamanı ile timestamp arasındaki fark ±5 dakika içinde olmalıdır
Geçersiz timestamp durumunda 1001 hata kodu döner

İmza Doğrulama Süreci

Sunucu, istemciden gelen X-Client-Id ile ilişkili CLIENT_SECRET değerini alır
Gelen X-Timestamp değeri ile aynı data string'i oluşturur: "{CLIENT_ID}:{TIMESTAMP}"
Kendi HMAC-SHA256 imzasını hesaplar
Hesaplanan imza ile gelen X-Signature değerini karşılaştırır
Eşleşme varsa istek işlenir, yoksa 1001 hata kodu döner

Endpoint Bilgileri

Tüm endpoint'ler aşağıdaki base URL'i kullanır:

https://connect.marsneo.com/api/v1/gift-card

Örnek Full Endpoint URL'leri:

POST https://connect.marsneo.com/api/v1/gift-card/{coupon_id}/transaction-code
POST https://connect.marsneo.com/api/v1/gift-card/transactions/pay
POST https://connect.marsneo.com/api/v1/gift-card/transactions/refund
GET  https://connect.marsneo.com/api/v1/gift-card/reconciliation/summary
GET  https://connect.marsneo.com/api/v1/gift-card/reconciliation/summary/details

Request Format

Request Body Format

POST istekleri için request body JSON formatında gönderilmelidir:

{
  "msisdn": "905551112233",
  "amountCents": 5000
}

Request Parametreleri

Path Parametreleri

URL içinde {parametre} şeklinde belirtilir.

Örnek:

POST /api/v1/gift-card/{coupon_id}/transaction-code

Query Parametreleri

URL sonuna ?key=value&key2=value2 şeklinde eklenir.

Örnek:

GET /api/v1/gift-card/reconciliation/summary?date=2026-01-28

Body Parametreleri

POST istekleri için JSON body içinde gönderilir.

Parametre Detayları

Parametre

Tip

Format

Açıklama

msisdn

string

E.164

Ülke kodu dahil telefon numarası (örn: 905551112233)

coupon_id

string

UUID/Integer

Kupon benzersiz kimliği

transaction_id

string

UUID

İşlem benzersiz kimliği

transaction_code

string

8 haneli

İşlem kodu

amount_cents

integer

Pozitif

Tutar (kuruş/cent cinsinden). 5000 = 50.00 TRY

branch_code

string

Maks 10 karakter

Şube kodu

client_reference

string

Maks 100 karakter

İstemci referans numarası

date

string

YYYY-MM-DD

Tarih formatı

status

string

SUCCESS/CANCEL

İşlem durumu

page

integer

Pozitif

Sayfa numarası (varsayılan: 1)

limit

integer

1-1000 arası

Sayfa başına kayıt sayısı

Request Örneği

curl -X POST "https://connect.marsneo.com/api/v1/gift-card/770e8400-e29b-41d4-a716-446655440003/transaction-code" \
  -H "Content-Type: application/json" \
  -H "X-Lang: tr" \
  -H "X-Client-Id: 21929721-5f5b-4d1f-a857-2ff01be5098g" \
  -H "X-Timestamp: 1770203235" \
  -H "X-Signature: 5dc142fdb3a539bc04d9390733c472b48ffe05201abfe04cbda6a5ef22912103" \
  -d '{
    "msisdn": "905364680467"
  }'

Response Format

Başarılı Response

Tüm başarılı yanıtlar aşağıdaki standart formatı kullanır:

{
  "responseId": "resp_698328642c14d2.55887397",
  "isSuccessful": true,
  "errorCode": "0",
  "message": "İşlem başarıyla tamamlandı",
  "data": {
    // Endpoint'e özgü veri
  },
  "dataHash": null,
  "challenge": null
}

Örnek Başarılı Response:

{
  "responseId": "resp_698328642c14d2.55887397",
  "isSuccessful": true,
  "errorCode": "0",
  "message": "Transaction code created successfully",
  "data": {
    "couponId": "770e8400-e29b-41d4-a716-446655440003",
    "transactionCode": "93754050",
    "expireAt": "2026-02-04T14:11:05+03:00",
    "ttlSeconds": 299
  },
  "dataHash": null,
  "challenge": null
}

Hata Response

Hata durumlarında dönen yanıt formatı:

{
  "responseId": "resp_698328642c14d2.55887397",
  "isSuccessful": false,
  "errorCode": "1001",
  "message": "Invalid signature",
  "data": null,
  "challenge": null
}

Validasyon Hatası Örneği:

{
  "responseId": "resp_698328642c14d2.55887397",
  "isSuccessful": false,
  "errorCode": "422",
  "message": "Validation failed",
  "data": {
    "errors": {
      "msisdn": ["MSISDN formatı geçersiz"]
    }
  },
  "challenge": null
}

Servis Hatası Örneği:

{
  "responseId": "resp_698328642c14d2.55887397",
  "isSuccessful": false,
  "errorCode": "500",
  "message": "Internal server error",
  "data": null,
  "challenge": null
}

Response Alanları

Alan

Tip

Açıklama

responseId

string

Yanıt benzersiz kimliği (loglama ve takip için)

isSuccessful

boolean

İşlem başarı durumu

errorCode

string

Hata kodu ("0" = başarılı, diğerleri hata)

message

string

Kullanıcıya gösterilecek mesaj

data

object/array/null

Endpoint'e özgü veri

dataHash

string/null

Veri bütünlük kontrolü için hash (gelecekte kullanılacak)

challenge

string/null

Güvenlik challenge'ı (gelecekte kullanılacak)

Hata Kodları

Kimlik Doğrulama Hataları

Kod

HTTP Status

Açıklama

1001

401

Invalid signature (İmza geçersiz)

1002

401

Invalid timestamp (Timestamp geçersiz veya süresi dolmuş)

1003

401

Missing authentication headers (Kimlik doğrulama header'ları eksik)

1004

403

Client not authorized (İstemci yetkisiz)

1005

401

Client ID not found (Client ID bulunamadı)

Validasyon Hataları

Kod

HTTP Status

Açıklama

422

422

Validation failed (Girdi validasyon hatası)

400

400

Bad request (Hatalı istek formatı)

404

404

Resource not found (Kaynak bulunamadı)

409

409

Conflict (Çakışma - örn: kod zaten kullanılmış)

Servis Hataları

Kod

HTTP Status

Açıklama

500

500

Internal server error (Sunucu hatası)

503

503

Service unavailable (Servis kullanılamıyor)

504

504

Gateway timeout (Ağ geçidi zaman aşımı)

1000

500

General error (Genel hata)

API Endpoints

İşlem Kodu Oluştur (Generate Transaction Code)

Bir kupon için tek kullanımlık 8 haneli işlem kodu üretir (5 dakika geçerli).

Endpoint: POST /api/v1/gift-card/{coupon_id}/transaction-code

Path Parametreleri:

Parametre

Tip

Zorunlu

Açıklama

coupon_id

string

Evet

Kupon ID'si

Request Body:

{
  "msisdn": "905551112233"
}

Alan

Tip

Zorunlu

Açıklama

msisdn

string

Evet

Telefon numarası (ownership kontrolü için)

Örnek İstek:

POST https://connect.marsneo.com/api/v1/gift-card/770e8400-e29b-41d4-a716-446655440003/transaction-code
Content-Type: application/json
X-Client-Id: 21929721-5f5b-4d1f-a857-2ff01be5098g
X-Timestamp: 1770203235
X-Signature: 5dc142fdb3a539bc04d9390733c472b48ffe05201abfe04cbda6a5ef22912103

{
  "msisdn": "905364680467"
}

Başarılı Response (201 Created):

{
  "responseId": "resp_698328642c14d2.55887397",
  "isSuccessful": true,
  "errorCode": "0",
  "message": "Transaction code created successfully",
  "data": {
    "couponId": "770e8400-e29b-41d4-a716-446655440003",
    "transactionCode": "93754050",
    "expireAt": "2026-02-04T14:11:05+03:00",
    "ttlSeconds": 299
  },
  "dataHash": null,
  "challenge": null
}

Hata Durumları:

400: Kupon aktif değil veya bakiye yetersiz
404: Kupon bulunamadı veya MSISDN eşleşmiyor
409: Aktif (süresi dolmamış) bir kod zaten mevcut

Ödeme İşlemi (Pay Transaction)

İşlem kodu ile kupon bakiyesinden ödeme alır.

Endpoint: POST /api/v1/gift-card/transactions/pay

Request Body:

{
  "transactionCode": "93754050",
  "amountCents": 5000,
  "branchCode": "01",
  "clientReference": "REF-20260204-001"
}

Alan

Tip

Zorunlu

Açıklama

transactionCode

string

Evet

8 haneli işlem kodu

amountCents

integer

Evet

Ödeme tutarı (kuruş cinsinden)

branchCode

string

Hayır

Şube kodu

clientReference

string

Hayır

İstemci referans numarası

Örnek İstek:

POST https://connect.marsneo.com/api/v1/gift-card/transactions/pay
Content-Type: application/json
X-Client-Id: 21929721-5f5b-4d1f-a857-2ff01be5098g
X-Timestamp: 1770203235
X-Signature: 5dc142fdb3a539bc04d9390733c472b48ffe05201abfe04cbda6a5ef22912103

{
  "transactionCode": "93754050",
  "amountCents": 5000,
  "branchCode": "01",
  "clientReference": "REF-20260204-001"
}

Başarılı Response (200 OK):

{
  "responseId": "resp_698328642c14d2.55887397",
  "isSuccessful": true,
  "errorCode": "0",
  "message": "Payment completed successfully",
  "data": {
    "couponId": "770e8400-e29b-41d4-a716-446655440003",
    "debitedAmountCents": 5000,
    "transactionCode": "93754050",
    "expiresAt": "2026-02-04T14:11:05+03:00",
    "status": "PAID",
    "transactionId": "ad82fb18-6c44-4bf0-a8f0-e0b6ad9094c3"
  },
  "dataHash": null,
  "challenge": null
}

Hata Durumları:

400: İşlem kodu kullanılmış veya tutar geçersiz
404: İşlem kodu bulunamadı
409: İşlem kodu süresi dolmuş
422: Bakiye yetersiz

İade İşlemi (Refund Transaction)

Tamamlanmış bir işlemi iade eder.

Endpoint: POST /api/v1/gift-card/transactions/refund

Request Body:

{
  "transactionId": "ad82fb18-6c44-4bf0-a8f0-e0b6ad9094c3",
  "amountCents": 5000,
  "branchCode": "01",
  "clientReference": "REF-REFUND-20260204-001"
}

Alan

Tip

Zorunlu

Açıklama

transactionId

string

Evet

Orijinal işlem ID'si (UUID)

amountCents

integer

Evet

İade tutarı (kuruş cinsinden)

branchCode

string

Hayır

Şube kodu

clientReference

string

Hayır

İstemci referans numarası

Örnek İstek:

POST https://connect.marsneo.com/api/v1/gift-card/transactions/refund
Content-Type: application/json
X-Client-Id: 21929721-5f5b-4d1f-a857-2ff01be5098g
X-Timestamp: 1770203235
X-Signature: 5dc142fdb3a539bc04d9390733c472b48ffe05201abfe04cbda6a5ef22912103

{
  "transactionId": "ad82fb18-6c44-4bf0-a8f0-e0b6ad9094c3",
  "amountCents": 5000,
  "branchCode": "01",
  "clientReference": "REF-REFUND-20260204-001"
}

Başarılı Response (200 OK):

{
  "responseId": "resp_698328642c14d2.55887397",
  "isSuccessful": true,
  "errorCode": "0",
  "message": "Refund completed successfully",
  "data": {
    "refundTransactionId": "a9c5df22-0b61-4f0c-a5c0-8765cdef1234",
    "originalTransactionId": "ad82fb18-6c44-4bf0-a8f0-e0b6ad9094c3",
    "refundedAmountCents": 5000,
    "status": "CANCELLED",
    "createdAt": "2026-02-04T12:05:00Z"
  },
  "dataHash": null,
  "challenge": null
}

Hata Durumları:

400: İade tutarı orijinal tutardan büyük veya işlem zaten iade edilmiş
404: Orijinal işlem bulunamadı
409: İşlem aynı anda başka bir süreçte iade ediliyor

Mutabakat Özeti (Reconciliation Summary)

Belirli bir günün toplam işlem sayısı ve tutarını döner.

Endpoint: GET /api/v1/gift-card/reconciliation/summary

Query Parametreleri:

Parametre

Tip

Zorunlu

Açıklama

date

string

Evet

Tarih (YYYY-MM-DD formatında)

Örnek İstek:

GET https://connect.marsneo.com/api/v1/gift-card/reconciliation/summary?date=2026-01-28
X-Client-Id: 21929721-5f5b-4d1f-a857-2ff01be5098g
X-Timestamp: 1770203235
X-Signature: 5dc142fdb3a539bc04d9390733c472b48ffe05201abfe04cbda6a5ef22912103

Başarılı Response (200 OK):

{
  "responseId": "resp_698328642c14d2.55887397",
  "isSuccessful": true,
  "errorCode": "0",
  "message": "Reconciliation summary retrieved successfully",
  "data": {
    "date": "2026-01-28",
    "totalTransactions": 152,
    "totalAmountCents": 1875000,
    "currency": "TRY",
    "lastCalculatedAt": "2026-01-29T02:05:00Z"
  },
  "dataHash": null,
  "challenge": null
}

Hata Durumları:

422: Tarih formatı geçersiz
404: Belirtilen tarih için kayıt bulunamadı

Mutabakat Detayları (Reconciliation Details)

Belirli bir günün tüm işlem satırlarını listeler.

Endpoint: GET /api/v1/gift-card/reconciliation/summary/details

Query Parametreleri:

Parametre

Tip

Zorunlu

Açıklama

date

string

Evet

Tarih (YYYY-MM-DD formatında)

status

string

Hayır

İşlem durumu (SUCCESS/CANCEL). Boş ise tümü

page

integer

Hayır

Sayfa numarası (varsayılan: 1)

limit

integer

Hayır

Sayfa başına kayıt (varsayılan: 100, maks: 1000)

Örnek İstek:

GET https://connect.marsneo.com/api/v1/gift-card/reconciliation/summary/details?date=2026-01-28&status=SUCCESS&page=1&limit=50
X-Client-Id: 21929721-5f5b-4d1f-a857-2ff01be5098g
X-Timestamp: 1770203235
X-Signature: 5dc142fdb3a539bc04d9390733c472b48ffe05201abfe04cbda6a5ef22912103

Başarılı Response (200 OK):

{
  "responseId": "resp_698328642c14d2.55887397",
  "isSuccessful": true,
  "errorCode": "0",
  "message": "Reconciliation details retrieved successfully",
  "data": {
    "date": "2026-01-28",
    "statusFilter": "SUCCESS",
    "rows": [
      {
        "transactionId": "f6781272-a433-4ac0-a43e-6a44d555432d",
        "amountCents": 7500,
        "processedAt": "2026-01-28T18:45:12Z",
        "status": "SUCCESS"
      },
      {
        "transactionId": "a2f4dd13-58aa-4f6d-9f2e-4bde12fab567",
        "amountCents": 125000,
        "processedAt": "2026-01-28T20:10:05Z",
        "status": "SUCCESS"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 152
    }
  },
  "dataHash": null,
  "challenge": null
}

Hata Durumları:

422: Tarih formatı veya parametreler geçersiz
404: Belirtilen tarih için kayıt bulunamadı

Kullanım Örnekleri

Senaryo 1: Kupon ile Ödeme

# 1. İşlem kodu oluştur
POST https://connect.marsneo.com/api/v1/gift-card/8421/transaction-code
{
  "msisdn": "905551112233"
}

# 2. Ödeme yap
POST https://connect.marsneo.com/api/v1/gift-card/transactions/pay
{
  "transactionCode": "93754050",
  "amountCents": 5000,
  "branchCode": "01",
  "clientReference": "ORDER-12345"
}

Senaryo 2: İade İşlemi

# İade işlemi yap
POST https://connect.marsneo.com/api/v1/gift-card/transactions/refund
{
  "transactionId": "ad82fb18-6c44-4bf0-a8f0-e0b6ad9094c3",
  "amountCents": 5000,
  "branchCode": "01",
  "clientReference": "REFUND-ORDER-12345"
}

Senaryo 3: Günlük Mutabakat

# 1. Günlük özeti al
GET https://connect.marsneo.com/api/v1/gift-card/reconciliation/summary?date=2026-01-28

# 2. Detaylı rapor al
GET https://connect.marsneo.com/api/v1/gift-card/reconciliation/summary/details?date=2026-01-28&page=1&limit=100

PreviousÜrün & Teknik Akış NextBatch (Toplu) İşlemler

Last updated 22 days ago

hashtagGenel Bakış

hashtagKimlik Doğrulama (Authentication)

hashtagGerekli Header'lar

hashtagHMAC Signature Oluşturma

hashtagÖrnek İmza Oluşturma (JavaScript)

hashtagTimestamp Doğrulama Kuralları

hashtagİmza Doğrulama Süreci

hashtagEndpoint Bilgileri

hashtagRequest Format

hashtagRequest Body Format

hashtagRequest Parametreleri

hashtagPath Parametreleri

hashtagQuery Parametreleri

hashtagBody Parametreleri

hashtagParametre Detayları

hashtagRequest Örneği

hashtagResponse Format

hashtagBaşarılı Response

hashtagHata Response

hashtagResponse Alanları

hashtagHata Kodları

hashtagKimlik Doğrulama Hataları

hashtagValidasyon Hataları

hashtagServis Hataları

hashtagAPI Endpoints

hashtagİşlem Kodu Oluştur (Generate Transaction Code)

hashtagÖdeme İşlemi (Pay Transaction)

hashtagİade İşlemi (Refund Transaction)

hashtagMutabakat Özeti (Reconciliation Summary)

hashtagMutabakat Detayları (Reconciliation Details)

hashtagKullanım Örnekleri

hashtagSenaryo 1: Kupon ile Ödeme

hashtagSenaryo 2: İade İşlemi

hashtagSenaryo 3: Günlük Mutabakat

Genel Bakış

Kimlik Doğrulama (Authentication)

Gerekli Header'lar

HMAC Signature Oluşturma

Örnek İmza Oluşturma (JavaScript)

Timestamp Doğrulama Kuralları

İmza Doğrulama Süreci

Endpoint Bilgileri

Request Format

Request Body Format

Request Parametreleri

Path Parametreleri

Query Parametreleri

Body Parametreleri

Parametre Detayları

Request Örneği

Response Format

Başarılı Response

Hata Response

Response Alanları

Hata Kodları

Kimlik Doğrulama Hataları

Validasyon Hataları

Servis Hataları

API Endpoints

İşlem Kodu Oluştur (Generate Transaction Code)

Ödeme İşlemi (Pay Transaction)

İade İşlemi (Refund Transaction)

Mutabakat Özeti (Reconciliation Summary)

Mutabakat Detayları (Reconciliation Details)

Kullanım Örnekleri

Senaryo 1: Kupon ile Ödeme

Senaryo 2: İade İşlemi

Senaryo 3: Günlük Mutabakat