API Dokümantasyonu

Genel bakış

Ritapos REST API v1, mağaza, ürün ve sipariş verilerine JSON üzerinden erişim sağlar.

Tüm istekler HTTPS üzerinden yapılır. Base URL: https://app.ritapos.com

Kimlik doğrulama

Mağaza ve ürün uçları herkese açıktır; Authorization başlığı gerekmez.
Sipariş uçları için Ritapos uygulamasından oluşturduğunuz API anahtarını kullanın: Authorization: Bearer YOUR_API_KEY
API anahtarını query parametresi veya istek gövdesinde göndermeyin; yalnızca Authorization başlığı kabul edilir.
Anahtar, oluşturulduğu mağazaya bağlıdır. read-only rolü bu okuma uçları için yeterlidir.

Yanıt zarfları

Mağaza ve ürün uçları: { "status": true|false, "data": ... }. İş mantığı hatalarında HTTP durumu çoğu zaman 200 kalır; başarıyı status alanı belirler.
Sipariş uçları: { "status": "ok"|"error", "data" | "message" }. Hatalarda gerçek HTTP kodları kullanılır (400, 401, 403, 404, 429, 500).

Sipariş okuma istekleri API anahtarı + IP başına dakikada 60 istekle sınırlıdır. Aşımda HTTP 429 ve Retry-After döner.

Uç noktalar

Mağaza bilgisini getir

GET /api/v1/stores/:storeId

Kimlik doğrulama gerekmez

Verilen storeId ile mağazayı döndürür. Path parametresi mağaza _id veya guid değeri olabilir.

Parametreler

Ad	Konum	Zorunluluk	Açıklama
`storeId`	path	zorunlu	Mağaza _id veya guid

Örnek istek

curl -sS 'https://app.ritapos.com/api/v1/stores/Ey29nwg2WB5cMvh2o'

Başarılı yanıt

{
  "status": true,
  "data": {
    "_id": "Ey29nwg2WB5cMvh2o",
    "guid": "...",
    "name": "Example Cafe",
    "alias": "example-cafe"
  }
}

Hata yanıtı

{
  "status": false,
  "data": "Store with storeId Ey29nwg2WB5cMvh2o not found."
}

Mağaza ürünlerini listele

GET /api/v1/products/:storeId

Kimlik doğrulama gerekmez

Belirtilen mağazaya ait tüm ürünleri listeler. Path parametresi ürün kimliği değil, mağaza kimliğidir (storeId).

Parametreler

Ad	Konum	Zorunluluk	Açıklama
`storeId`	path	zorunlu	Mağaza kimliği

Notlar

Yanıt, o mağazanın ürün belgelerinin dizisidir.

Örnek istek

curl -sS 'https://app.ritapos.com/api/v1/products/Ey29nwg2WB5cMvh2o'

Başarılı yanıt

{
  "status": true,
  "data": [
    {
      "_id": "...",
      "storeId": "Ey29nwg2WB5cMvh2o",
      "title": "Latte",
      "priceOut": 120,
      "tax": 0.1,
      "isVisible": true,
      "isVisibleInQrMenu": true
    }
  ]
}

Hata yanıtı

{
  "status": false,
  "data": "storeId is missing."
}

QR menü ürünlerini listele

GET /api/v1/products/:storeId/qr-menu

Kimlik doğrulama gerekmez

QR menüde görünen (isVisibleInQrMenu: true) ürünleri order ve title sırasıyla döndürür.

Parametreler

Ad	Konum	Zorunluluk	Açıklama
`storeId`	path	zorunlu	Mağaza kimliği
`filter`	query	opsiyonel	image değeri verilirse yalnızca imageId veya imageUrl olan ürünler döner

Notlar

Örnek: /api/v1/products/Ey29nwg2WB5cMvh2o/qr-menu?filter=image

Örnek istek

curl -sS 'https://app.ritapos.com/api/v1/products/Ey29nwg2WB5cMvh2o/qr-menu'

Başarılı yanıt

{
  "status": true,
  "data": [
    {
      "_id": "...",
      "storeId": "Ey29nwg2WB5cMvh2o",
      "title": "Espresso",
      "isVisibleInQrMenu": true,
      "imageUrl": "https://..."
    }
  ]
}

Hata yanıtı

{
  "status": false,
  "data": "storeId is missing."
}

Mağaza siparişlerini listele

GET /api/v1/orders/store/:storeId

Kimlik doğrulama gerekli

Belirtilen mağazanın siparişlerini tarih aralığına göre listeler. API anahtarı mağaza ile eşleşmelidir.

Parametreler

Ad	Konum	Zorunluluk	Açıklama
`storeId`	path	zorunlu	Mağaza kimliği (API anahtarının mağazası ile aynı olmalı)
`startDate`	query	opsiyonel	ISO-8601 başlangıç tarihi. İkisi de yoksa son 7 gün kullanılır
`finishDate`	query	opsiyonel	ISO-8601 bitiş tarihi. Yalnızca biri verilirse diğeri ±7 gün hesaplanır
`limit`	query	opsiyonel	Varsayılan 100, en fazla 10000

Notlar

Tarih aralığı en fazla 90 gün olabilir.
startDate, finishDate'ten sonra olamaz.

Örnek istek

curl -sS 'https://app.ritapos.com/api/v1/orders/store/4Bo8zuMSkWSwvtrwi?startDate=2026-04-01&finishDate=2026-05-01&limit=100' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Başarılı yanıt

{
  "status": "ok",
  "data": [
    {
      "_id": "jatmsKpEXq5gepTK3",
      "storeId": "4Bo8zuMSkWSwvtrwi",
      "number": 42,
      "type": 1,
      "paymentType": "cash",
      "paymentTypeLabel": {
        "en": "Cash",
        "tr": "Nakit",
        "es": "Efectivo",
        "de": "Bar"
      },
      "priceOutTotal": 250,
      "grossTotalWithTax": 250,
      "createdAt": "2026-04-15T12:00:00.000Z"
    }
  ]
}

Hata yanıtı

{
  "status": "error",
  "message": "Unauthorized"
}

Tek sipariş getir

GET /api/v1/orders/:orderId

Kimlik doğrulama gerekli

Sipariş _id değerine göre tek siparişi döndürür. Yanıta mağaza adı (storeName) eklenir. Anahtar, siparişin mağazasına ait olmalıdır.

Parametreler

Ad	Konum	Zorunluluk	Açıklama
`orderId`	path	zorunlu	Sipariş _id

Örnek istek

curl -sS 'https://app.ritapos.com/api/v1/orders/jatmsKpEXq5gepTK3' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Başarılı yanıt

{
  "status": "ok",
  "data": {
    "_id": "jatmsKpEXq5gepTK3",
    "storeId": "4Bo8zuMSkWSwvtrwi",
    "storeName": "Example Cafe",
    "number": 42,
    "type": 1,
    "paymentType": "cash",
    "paymentTypeLabel": {
      "en": "Cash",
      "tr": "Nakit",
      "es": "Efectivo",
      "de": "Bar"
    },
    "grossTotalWithTax": 250,
    "createdAt": "2026-04-15T12:00:00.000Z"
  }
}

Hata yanıtı

{
  "status": "error",
  "message": "Not found"
}

Sipariş alanları

Sipariş yanıtlarında dönen başlıca alanlar:

_id
storeId
storeName (single-order endpoint only)
number
type
paymentType
paymentTypeLabel ({ en, tr, es, de })
paymentProvider
tip
serviceCharge
priceInTotal
priceOutTotal
grossTotalWithTax
grossTotalWithoutTax
grossTax
netTotalWithTax
netTotalWithoutTax
netTax
discount
discountNote
note
tableId
roomId
courierId
customerId
externalId
createdAt
updatedAt
completedAt
scheduledAt

Sipariş type değerleri

0. PENDING: Beklemede
1. COMPLETED: Tamamlandı
2. CANCELED: İptal
3. SOFT_REMOVED: Soft silindi
4. LOSS: Zayi
5. ON_ACCOUNT: Veresiye

API erişimi veya destek için bizimle iletişime geçin.

Sizi Arayalım