retrieve-orders

POST /api/{team}/gateway/retrieve-orders

Siparişlerin güncel hâlini döndürür; hiçbir şeyi değiştirmez. Müşteri ödeme sayfasından size dönmediyse siparişin ödenip ödenmediğini ve ödeyen işlemin token'ını buradan öğrenirsiniz. Her sipariş kendi customer alanıyla döner.

Kimlik doğrulama

X-Api-Key, X-Timestamp, X-Signature, Content-Type: application/json. Ayrıntılar: Kimlik Doğrulama ve İmza.

İstek

Kayıt üç yoldan biriyle adlandırılır; en fazla biri gönderilir:

{ "token": "3b7e1f20-5c4a-4d8e-9f1b-7a6c5d4e3f21" }

{ "reference": "SIP-10233" }

{ "created_from": "2026-09-26", "created_to": "2026-10-02" }

Alan	Tip	Zorunlu	Açıklama
`token`	string (UUID)	hayır	Kaydın token'ı. `reference` ya da tarih aralığıyla birlikte gönderilmez.
`reference`	string	hayır	Siparişin referansı. Tarih aralığıyla birlikte gönderilmez. Bu referansla açılmış siparişlerin hepsi döner.
`created_from`	string	hayır	Başlangıç günü, `YYYY-MM-DD`. `created_to` ile birlikte gönderilir.
`created_to`	string	hayır	Bitiş günü, `YYYY-MM-DD`. `created_from` ile birlikte gönderilir; ondan önce olamaz. Aralık iki gün dahil en fazla 7 gündür.

Tarihler çalışma alanının saat dilimindedir. Hiçbir alan gönderilmezse ({}) bugün dahil son 7 gün listelenir. Yanıt her zaman bir listedir; eşleşen kayıt yoksa liste boştur. Başka bir çalışma alanının kaydı hiçbir zaman dönmez.

reference tekil değildir: aynı referansla yapılan her create-order çağrısı ayrı bir sipariş açar. reference ile sorgu bu siparişlerin hepsini, eskiden yeniye döndürür; aralarından istediğinizi token ile, ödenmiş olanı status: "paid" ile ayırt edin. Tek bir siparişi kesin olarak sorgulamak için create-order yanıtında aldığınız token gönderilir.

SDK örnekleri

not

Örneklerdeki $client / client nesnesinin kurulumu: İstemciyi Kurmak.

PHP
Node.js
Python
Java
cURL

use Gurmehub\Odemehub\Request\RetrieveOrders;

$order = $client->retrieveOrders(RetrieveOrders::byToken($orderToken))->orders[0] ?? null;

$order?->isPaid();
$order?->transaction?->token;   // ödeyen işlem; açıkken null
$order?->customer?->reference;

const [order] = (await client.retrieveOrders({ token: orderToken })).orders;

order?.isPaid();
order?.transaction?.token;   // ödeyen işlem; açıkken null
order?.customer?.reference;

from odemehub.request import RetrieveOrders

orders = client.retrieve_orders(RetrieveOrders(token=order_token)).orders

if orders:
    orders[0].is_paid()
    orders[0].transaction   # ödeyen işlem; açıkken None
    orders[0].customer

import com.odemehub.request.RetrieveOrders;

var orders = client.retrieveOrders(RetrieveOrders.byToken(orderToken)).getOrders();

if (!orders.isEmpty()) {
    orders.get(0).isPaid();
    orders.get(0).getTransaction();   // ödeyen işlem; açıkken null
    orders.get(0).getCustomer();
}

URI_PATH="/api/$ODEMEHUB_TEAM/gateway/retrieve-orders"
BODY='{"token":"3b7e1f20-5c4a-4d8e-9f1b-7a6c5d4e3f21"}'
TIMESTAMP=$(date +%s)
SIGNATURE=$(printf '%s\n%s\n%s\n%s' "$TIMESTAMP" "POST" "$URI_PATH" "$BODY" | openssl dgst -sha256 -hmac "$ODEMEHUB_API_SECRET" | sed 's/^.* //')

curl -X POST "https://sandbox.odemehub.com$URI_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $ODEMEHUB_API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  --data-raw "$BODY"

Yanıt

Ödeme sayfasında YAZ10 kuponuyla ödenmiş bir sipariş:

{
  "result": { "successful": true, "message": null },
  "orders": [
    {
      "token": "3b7e1f20-5c4a-4d8e-9f1b-7a6c5d4e3f21",
      "reference": "SIP-10233",
      "description": null,
      "payment_provider_token": null,
      "status": "paid",
      "items": [
        { "reference": "SKU-1", "name": "Kulaklık", "image": null, "quantity": 1, "unit_amount": "1200.00", "tax_rate": "20.00" }
      ],
      "shipping_method": { "reference": "standart", "title": "Standart Kargo", "amount": "49.90", "tax_rate": "20.00" },
      "discount": { "code": "YAZ10", "amount": "120.00" },
      "subtotal": "900.00",
      "shipping_amount": "41.58",
      "tax_amount": "188.32",
      "amount": "1129.90",
      "currency": "TRY",
      "is_test": false,
      "created_at": "2026-10-02T09:20:00.000000Z",
      "checkout_url": null,
      "transaction": {
        "token": "0b8f6c2d-3e41-4a7b-9c5d-1e2f3a4b5c6d",
        "reference": "SIP-10233",
        "payment_status": "paid"
      },
      "customer": {
        "reference": "musteri-88",
        "billing_address": { "firstname": "Ahmet", "lastname": "Yılmaz", "email": "[email protected]" },
        "shipping_address": null
      }
    }
  ]
}

Alan	Tip	Açıklama
`created_from`, `created_to`	string	Yalnızca tarih aralığıyla (ya da boş gövdeyle) sorulduğunda: listenin kapsadığı günler.
`orders[]`	array	Sipariş nesneleri, her biri `customer` alanıyla; eskiden yeniye.

Sipariş nesnesi

create-order, update-order yanıtlarında ve bu listede aynı nesne döner.

Alan	Tip	Açıklama
`token`	string	Siparişin token'ı.
`reference`	string	Siparişin referansı. Tekil değildir; aynı referansla birden çok sipariş olabilir.
`description`	string \| null	Açıklama.
`payment_provider_token`	string \| null	İstekte verilen ödeme hesabı; verilmediyse `null`.
`status`	string	`open` (ödenmedi) ya da `paid`.
`items[]`	array	Kalemler: `reference`, `name`, `image`, `quantity`, `unit_amount` (KDV dahil), `tax_rate`.
`shipping_method`	object \| null	Ödeyenin çalışma alanınızın gönderim listesinden seçtiği yöntem: `reference`, `title`, `amount` (KDV dahil), `tax_rate`. Seçilmediyse `null`.
`discount`	object \| null	Ödeme sayfasında uygulanan kupon: `code`, `amount` (kalemlerden düşülen tutar, siparişin para biriminde). Kupon yoksa `null`. Bkz. Kupon ve `discount`.
`subtotal`	string	Kalemlerin KDV hariç toplamı; kupon varsa indirim düşülmüş.
`shipping_amount`	string	Seçilen gönderim yönteminin KDV hariç ücreti; seçilmediyse `"0.00"`.
`tax_amount`	string	Kalemlerin (kupon varsa indirim düşülmüş) ve gönderim ücretinin KDV'si.
`amount`	string	Karttan çekilecek toplam (KDV ve gönderim dahil, kupon indirimi düşülmüş). İndirim gönderim ücretinden düşülmez.
`currency`	string	Para birimi.
`is_test`	boolean \| null	Ödenene kadar `null`; ödenince ödemenin test modunda alınıp alınmadığı.
`created_at`	string	ISO 8601 UTC.
`checkout_url`	string \| null	Ödeme sayfası. Yalnızca sipariş ödenebilirken (`status` `open` ve Siparişler modülü açık) dolu; değilse `null`.
`transaction`	object \| null	Siparişi ödeyen işlem: `token`, `reference`, `payment_status` (`paid`, `cancelled`, `refunded`, `partially_refunded`; iadeden sonra sipariş `paid` kalır, iade bu alanda görünür). Açıkken `null`. Bu token `retrieve-payments`, `refund-payment` ve `cancel-payment` ile kullanılır.

Listedeki her siparişin customer alanı: Yanıttaki customer. Siparişin reddedilen ödeme denemeleri retrieve-payments listesinde order.token alanıyla görünür.

HTTP durum kodları

Kod	Durum
`200`	Liste döndü; eşleşen kayıt yoksa boş.
`401`	API anahtarı ya da imza geçersiz.
`403`	Çalışma alanı işlem yapamıyor, planı siparişleri kapsamıyor ya da Siparişler modülü kapalı.
`422`	Doğrulama hatası.
`429`	İstek sınırı aşıldı.

Hatalar

Alan	Mesaj
`token`	`Token ile birlikte referans ya da tarih aralığı gönderilmez.`
`reference`	`Referans ile birlikte tarih aralığı gönderilmez.`
`created_to`	`Bitiş tarihi başlangıç tarihinden önce olamaz.` / `Tarih aralığı en fazla 7 gün olabilir.`

Kimlik doğrulama​

İstek​

SDK örnekleri​

Yanıt​

Sipariş nesnesi​

HTTP durum kodları​

Hatalar​