API Dokümantasyonu

Genel bakış

Ritapos REST API v1, mağaza, franchise, ü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.
Franchise ve 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. Franchise uçlarında anahtar, o franchise'a ait bir mağazadan gelmelidir. 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.
Franchise uçları başarılı yanıtta mağaza zarfını kullanır: { "status": true|false, "data": ... }. Kimlik doğrulama ve kota hatalarında sipariş zarfı kullanılır: { "status": "error", "message" } ve gerçek HTTP kodları (401, 403, 429).
Sipariş uçları: { "status": "ok"|"error", "data" | "message" }. Hatalarda gerçek HTTP kodları kullanılır (400, 401, 403, 404, 429, 500).

Sipariş ve franchise 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

Notlar

Yanıt yalnızca şu alanları içerir: _id, guid, name, alias, logoUrl, description, city, country, photos.

Örnek istek

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

Başarılı yanıt

{
  "status": true,
  "data": {
    "_id": "Ey29a22Wa5cxxq1r4o",
    "guid": "...",
    "name": "Example Cafe",
    "alias": "example-cafe",
    "logoUrl": "https://...",
    "description": "...",
    "city": "Istanbul",
    "country": "TR",
    "photos": [
      {
        "imageId": "...",
        "imageUrl": "https://..."
      }
    ]
  }
}

Hata yanıtı

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

Franchise bilgisini getir

GET /api/v1/franchises/:franchiseId

Kimlik doğrulama gerekli

Merkez mağazanın _id değeri ile franchise kaydını döndürür. Path parametresi guid değildir; franchiseId alanına yazılan merkez _id kullanılır.

Parametreler

Ad	Konum	Zorunluluk	Açıklama
`franchiseId`	path	zorunlu	Merkez mağazanın Mongo _id değeri (franchiseId alanı)

Notlar

Yanıt yalnızca şu alanları içerir: _id, guid, name, alias, logoUrl, description, city, country, photos.
API anahtarı, bu franchise'a bağlı bir mağazadan oluşturulmuş olmalıdır. Aksi halde HTTP 403 döner.

Örnek istek

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

Başarılı yanıt

{
  "status": true,
  "data": {
    "_id": "x7Km9Pq2nR4wT6yLz",
    "guid": "...",
    "name": "Example Franchise",
    "alias": "example-franchise",
    "logoUrl": "https://...",
    "description": "...",
    "city": "Istanbul",
    "country": "TR",
    "photos": [
      {
        "imageId": "...",
        "imageUrl": "https://..."
      }
    ]
  }
}

Hata yanıtı

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

Franchise mağazalarını listele

GET /api/v1/franchises/:franchiseId/stores

Kimlik doğrulama gerekli

Franchise üyesi mağazaları listeler. Path, merkez _id veya bir mağaza guid değeri olabilir. Sonuçlar name alanına göre azalan sıralanır.

Parametreler

Ad	Konum	Zorunluluk	Açıklama
`franchiseId`	path	zorunlu	Merkez mağaza _id veya bir mağaza guid
`isActive`	query	opsiyonel	true veya false. Verilmezse aktiflik filtresi uygulanmaz
`isShownInRewarita`	query	opsiyonel	true veya false. Verilmezse Rewarita görünürlük filtresi uygulanmaz

Notlar

Yanıt alanları: _id, isActive, name, description, street, city, country, location, phone, link, franchiseOrder, photos. Listede guid yoktur.
API anahtarı bu franchise'a bağlı bir mağazadan gelmelidir. Aksi halde HTTP 403 döner.

Örnek istek

curl -sS 'https://app.ritapos.com/api/v1/franchises/x7Km9Pq2nR4wT6yLz/stores?isActive=true&isShownInRewarita=true' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Başarılı yanıt

{
  "status": true,
  "data": [
    {
      "_id": "x7Km9Pq2nR4wT6yLz",
      "isActive": true,
      "name": "Example Branch",
      "description": "...",
      "street": "...",
      "city": "Istanbul",
      "country": "TR",
      "location": "41.0082,28.9784",
      "phone": "+90...",
      "link": {
        "instagram": "https://...",
        "website": "https://..."
      },
      "franchiseOrder": 1,
      "photos": [
        {
          "imageId": "...",
          "imageUrl": "https://..."
        }
      ]
    }
  ]
}

Hata yanıtı

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

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/Ey29a22Wa5cxxq1r4o'

Başarılı yanıt

{
  "status": true,
  "data": [
    {
      "_id": "...",
      "storeId": "Ey29a22Wa5cxxq1r4o",
      "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/Ey29a22Wa5cxxq1r4o/qr-menu?filter=image

Örnek istek

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

Başarılı yanıt

{
  "status": true,
  "data": [
    {
      "_id": "...",
      "storeId": "Ey29a22Wa5cxxq1r4o",
      "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