{
  "openapi": "3.1.0",
  "info": {
    "title": "KuryeSoft Entegrasyon API'si",
    "version": "1.0.0+2026-11-20",
    "summary": "Kurye firmasına sipariş gönderme, durum sorgulama ve webhook bildirimleri.",
    "description": "KuryeSoft her kurye firmasına ayrı kurulur; taban adres firmanın alan adıdır (`https://{host}/api/v1`). Sunucu değişkenine kendi firmanızın adresini yazın.\n\nKimlik doğrulaması `X-Api-Key: ks_...` başlığıyla yapılır; anahtarı kurye firmanızın yöneticisi panelden oluşturur.\n\nAyrıntılı belgeler, örnekler ve webhook imza doğrulaması: https://docs.kuryesoft.com,"
  },
  "externalDocs": {
    "description": "Geliştirici belgeleri",
    "url": "https://docs.kuryesoft.com,"
  },
  "servers": [
    {
      "url": "https://{host}/api/v1",
      "description": "Kurye firmanızın KuryeSoft sunucusu",
      "variables": {
        "host": {
          "default": "kurye.firmaniz.com",
          "description": "Kurye firmanızın KuryeSoft alan adı"
        }
      }
    }
  ],
  "security": [
    {
      "ApiKey": []
    },
    {
      "Bearer": []
    }
  ],
  "tags": [
    {
      "name": "Bağlantı",
      "description": "Anahtar sınama."
    },
    {
      "name": "Tanımlar",
      "description": "Kurye firmasının tanımladığı listeler."
    },
    {
      "name": "Siparişler",
      "description": "Sipariş gönderme, sorgulama, hazır işaretleme ve iptal."
    }
  ],
  "paths": {
    "/ping": {
      "get": {
        "operationId": "ping",
        "tags": [
          "Bağlantı"
        ],
        "summary": "Bağlantıyı sına",
        "description": "Anahtarın geçerli olduğunu doğrular; anahtarın adını ve bağlı olduğu işletmeyi döndürür.\n\nEntegrasyonu kurarken ilk çağrınız bu olsun: adres, anahtar ve ağ bağlantısı doğruysa `200` döner. Sistemde hiçbir değişiklik yapmaz.\n\n`restaurant_id` doluysa anahtar o işletmeye bağlıdır ve siparişler kendiliğinden o işletmeye yazılır. `null` ise anahtar firma genelidir; sipariş gönderirken işletmeyi siz belirtirsiniz.\n\nBelge: https://docs.kuryesoft.com,/api/ping",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Anahtar geçerli.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "description": "Her zaman `true`."
                    },
                    "key": {
                      "type": "string",
                      "description": "Anahtara panelde verilen ad."
                    },
                    "restaurant_id": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "description": "Anahtarın bağlı olduğu işletme; firma geneli anahtarda `null`."
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "key": "Kasa POS",
                  "restaurant_id": 1
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: İstekte API anahtarı yok ya da `ks_` ile başlamıyor. `API_KEY_INVALID`: Anahtar yanlış, silinmiş ya da pasif.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "API_KEY_REQUIRED",
                    "message": "İstekte API anahtarı yok ya da `ks_` ile başlamıyor."
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Dakikalık istek sınırı aşıldı.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Dakikalık istek sınırı aşıldı."
                  }
                }
              }
            }
          },
          "500": {
            "description": "`INTERNAL`: Sunucuda beklenmeyen bir hata oluştu.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL",
                    "message": "Sunucuda beklenmeyen bir hata oluştu."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/payment-types": {
      "get": {
        "operationId": "listPaymentTypes",
        "tags": [
          "Tanımlar"
        ],
        "summary": "Ödeme tiplerini listele",
        "description": "Kurye firmasında tanımlı etkin ödeme tipleri.\n\nSipariş gönderirken ödemeyi `payment.kind` (tür) ile ya da buradaki `id` ile (`payment.payment_type_id`) belirtirsiniz. Firma aynı türden birden çok ödeme tipi tanımladıysa (ör. iki ayrı yemek kartı) doğru olanı seçmek için `id` kullanın.\n\n`collect_from_customer: true` olan tiplerde kurye kapıda tahsilat yapar; `false` olanlarda (önceden ödenmiş) tahsil edilecek tutar her zaman `0` olur.\n\nListe kurye firması tarafından değiştirilebilir; sabit kodlamak yerine günde bir kez çekip saklayın.\n\nBelge: https://docs.kuryesoft.com,/api/odeme-tipleri",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Etkin ödeme tipleri, paneldeki sırayla.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "description": "Ödeme tipi kimliği."
                          },
                          "name": {
                            "type": "string",
                            "description": "Firmanın verdiği ad."
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "cash",
                              "card",
                              "online",
                              "meal_card",
                              "other"
                            ],
                            "description": "Ödeme türü."
                          },
                          "collect_from_customer": {
                            "type": "boolean",
                            "description": "Kurye kapıda tahsilat yapar mı."
                          }
                        }
                      },
                      "description": "Ödeme tipleri."
                    }
                  }
                },
                "example": {
                  "items": [
                    {
                      "id": 1,
                      "name": "Kapıda Nakit",
                      "kind": "cash",
                      "collect_from_customer": true
                    },
                    {
                      "id": 2,
                      "name": "Kapıda Kredi Kartı",
                      "kind": "card",
                      "collect_from_customer": true
                    },
                    {
                      "id": 3,
                      "name": "Online Ödeme",
                      "kind": "online",
                      "collect_from_customer": false
                    },
                    {
                      "id": 4,
                      "name": "Yemek Kartı",
                      "kind": "meal_card",
                      "collect_from_customer": true
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: İstekte API anahtarı yok ya da `ks_` ile başlamıyor. `API_KEY_INVALID`: Anahtar yanlış, silinmiş ya da pasif.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "API_KEY_REQUIRED",
                    "message": "İstekte API anahtarı yok ya da `ks_` ile başlamıyor."
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Dakikalık istek sınırı aşıldı.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Dakikalık istek sınırı aşıldı."
                  }
                }
              }
            }
          },
          "500": {
            "description": "`INTERNAL`: Sunucuda beklenmeyen bir hata oluştu.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL",
                    "message": "Sunucuda beklenmeyen bir hata oluştu."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/cancel-reasons": {
      "get": {
        "operationId": "listCancelReasons",
        "tags": [
          "Tanımlar"
        ],
        "summary": "İptal sebeplerini listele",
        "description": "Kurye firmasının tanımladığı hazır iptal sebepleri.\n\nSipariş iptalinde sebep serbest metindir; raporlarda aynı sebepler bir arada görünsün diye kullanıcınıza bu listeden seçtirmeniz önerilir. Seçilen sebebin `name` değerini [Siparişi iptal et](https://docs.kuryesoft.com,/api/siparis-iptal) çağrısında `reason` olarak gönderin.\n\nBelge: https://docs.kuryesoft.com,/api/iptal-sebepleri",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Etkin iptal sebepleri.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "description": "Sebep kimliği."
                          },
                          "name": {
                            "type": "string",
                            "description": "Sebep metni."
                          }
                        }
                      },
                      "description": "Sebepler."
                    }
                  }
                },
                "example": {
                  "items": [
                    {
                      "id": 1,
                      "name": "Müşteri vazgeçti"
                    },
                    {
                      "id": 2,
                      "name": "Yanlış sipariş girildi"
                    },
                    {
                      "id": 3,
                      "name": "Ürün kalmadı"
                    },
                    {
                      "id": 6,
                      "name": "Diğer"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: İstekte API anahtarı yok ya da `ks_` ile başlamıyor. `API_KEY_INVALID`: Anahtar yanlış, silinmiş ya da pasif.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "API_KEY_REQUIRED",
                    "message": "İstekte API anahtarı yok ya da `ks_` ile başlamıyor."
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Dakikalık istek sınırı aşıldı.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Dakikalık istek sınırı aşıldı."
                  }
                }
              }
            }
          },
          "500": {
            "description": "`INTERNAL`: Sunucuda beklenmeyen bir hata oluştu.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL",
                    "message": "Sunucuda beklenmeyen bir hata oluştu."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/quote": {
      "post": {
        "operationId": "quoteOrder",
        "tags": [
          "Siparişler"
        ],
        "summary": "Mesafe ve ücret hesapla",
        "description": "Sipariş göndermeden önce adresin hizmet bölgesinde olup olmadığını, mesafeyi ve teslimat ücretini öğrenin.\n\nÖdeme ekranında müşteri adresini seçtiğinde çağırın: adres hizmet dışındaysa siparişi baştan almayabilirsiniz. Sistemde kayıt oluşturmaz.\n\nAdres hizmet dışındaysa hata **dönmez**; yanıt `200` ile `{ \"ok\": false, \"message\": \"...\" }` olur. `message` müşteriye gösterilebilir.\n\nÜcret, kurye firmasının işletmeye tanımladığı fiyat profiliyle hesaplanır. Profil ödeme türüne ya da paket sayısına göre değişiyorsa kesin ücret siparişte hesaplanır ve buradakinden farklı olabilir.\n\nBelge: https://docs.kuryesoft.com,/api/ucret-hesapla",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Adres hizmet bölgesinde. Adres en fazla teslimat mesafesinin ya da hizmet bölgesinin dışında.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "ok": {
                          "type": "boolean",
                          "description": "`true`: sipariş gönderilebilir."
                        },
                        "distance_m": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Yol mesafesi (metre)."
                        },
                        "duration_s": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "description": "Tahmini yol süresi (saniye)."
                        },
                        "delivery_fee": {
                          "type": "number",
                          "description": "Teslimat ücreti (TL). İşletmenin ücretleri görmesi kapalıysa yer almaz."
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "ok": {
                          "type": "boolean",
                          "description": "`false`."
                        },
                        "message": {
                          "type": "string",
                          "description": "Sebep; müşteriye gösterilebilir."
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "default": {
                    "summary": "Adres hizmet bölgesinde.",
                    "value": {
                      "ok": true,
                      "distance_m": 1754,
                      "duration_s": 253,
                      "delivery_fee": 70
                    }
                  },
                  "alt1": {
                    "summary": "Hizmet dışı",
                    "value": {
                      "ok": false,
                      "message": "Adres en fazla teslimat mesafesinin (8 km) dışında"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: İstekte API anahtarı yok ya da `ks_` ile başlamıyor. `API_KEY_INVALID`: Anahtar yanlış, silinmiş ya da pasif.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "API_KEY_REQUIRED",
                    "message": "İstekte API anahtarı yok ya da `ks_` ile başlamıyor."
                  }
                }
              }
            }
          },
          "404": {
            "description": "`NOT_FOUND`: Sipariş ya da işletme bulunamadı. Anahtarınızın göremediği bir işletmenin siparişi de böyle görünür.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "NOT_FOUND",
                    "message": "Sipariş ya da işletme bulunamadı. Anahtarınızın göremediği bir işletmenin siparişi de böyle görünür."
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION`: Eksik ya da hatalı alan. Hangi alanın neden reddedildiği `fields` içinde yazar.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "VALIDATION",
                    "message": "Eksik ya da hatalı alan. Hangi alanın neden reddedildiği `fields` içinde yazar."
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Dakikalık istek sınırı aşıldı.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Dakikalık istek sınırı aşıldı."
                  }
                }
              }
            }
          },
          "500": {
            "description": "`INTERNAL`: Sunucuda beklenmeyen bir hata oluştu.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL",
                    "message": "Sunucuda beklenmeyen bir hata oluştu."
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "restaurant_id": {
                    "type": "integer",
                    "examples": [
                      1
                    ],
                    "description": "İşletmenin kimliği. Anahtarınız bir işletmeye bağlı değilse `restaurant_id` ya da `restaurant_code` zorunludur; bağlıysa yok sayılır. Gövde yerine sorgu dizgisinde de gönderilebilir."
                  },
                  "restaurant_code": {
                    "type": "string",
                    "examples": [
                      "R001"
                    ],
                    "description": "`restaurant_id` yerine işletme kodu (ör. `R001`). Kodu kurye firmanız verir."
                  },
                  "lat": {
                    "type": "number",
                    "minimum": -90,
                    "maximum": 90,
                    "examples": [
                      40.9969
                    ],
                    "description": "Teslimat konumu (enlem)."
                  },
                  "lng": {
                    "type": "number",
                    "minimum": -180,
                    "maximum": 180,
                    "examples": [
                      29.0342
                    ],
                    "description": "Teslimat konumu (boylam)."
                  },
                  "total_amount": {
                    "type": "number",
                    "minimum": 0,
                    "default": 0,
                    "examples": [
                      285.5
                    ],
                    "description": "Sipariş tutarı (TL). Tutara göre değişen ücret profilleri için."
                  }
                },
                "required": [
                  "lat",
                  "lng"
                ]
              },
              "example": {
                "lat": 40.9969,
                "lng": 29.0342,
                "total_amount": 285.5
              }
            }
          }
        }
      }
    },
    "/orders": {
      "post": {
        "operationId": "createOrder",
        "tags": [
          "Siparişler"
        ],
        "summary": "Sipariş oluştur",
        "description": "Kurye firmasına yeni bir paket siparişi gönderir; sistem uygun kuryeyi kendisi atar.\n\nSipariş `pending` (Bekliyor) durumunda yazılır; kurye ataması kurye firmasının atama senaryosuna göre başlar (çoğunlukla hemen). Paket hazır olduğunda [Hazır işaretle](https://docs.kuryesoft.com,/api/siparis-hazir) çağrısını yapın. Bkz. [Hazırlık süresi](https://docs.kuryesoft.com,/temel-kavramlar#hazirlik).\n\n**Aynı siparişi iki kez açmaz.** Aynı işletme için aynı `external_id` ile ikinci kez gönderilen istek yeni sipariş açmaz, mevcut siparişi `200` ile döndürür. Bu yüzden zaman aşımı ya da ağ hatasında isteği aynı gövdeyle güvenle yeniden gönderebilirsiniz. Yinelenen istekteki değişiklikler (ör. yeni tutar) uygulanmaz.\n\nTeslimat konumunu (`address.lat`, `address.lng`) gönderin. Konumsuz siparişte mesafe ve ücret hesaplanamaz: firmanın fiyat profili konuma dayanıyorsa sipariş `OUT_OF_ZONE` ile reddedilir, dayanmıyorsa alınır ama kurye firması haritada konumu işaretleyene kadar otomatik atama bekler. API adres metninden konum bulmaz.\n\nBelge: https://docs.kuryesoft.com,/api/siparis-olustur",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Bu `external_id` ile sipariş zaten var; mevcut sipariş olduğu gibi döner.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiOrder"
                }
              }
            }
          },
          "201": {
            "description": "Sipariş oluşturuldu.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiOrder"
                },
                "example": {
                  "id": 1842,
                  "code": "2611200042",
                  "external_id": "POS-10452",
                  "status": "pending",
                  "status_label": "Bekliyor",
                  "restaurant_id": 1,
                  "tracking_url": "https://kurye.firmaniz.com/takip/oKe9xPqrlr7b_4jbNQiNCw",
                  "courier": null,
                  "distance_m": 1754,
                  "eta_at": null,
                  "delivery_fee": 70,
                  "total_amount": 285.5,
                  "collect_amount": 285.5,
                  "created_at": "2026-11-20T18:10:32.000Z",
                  "assigned_at": null,
                  "picked_up_at": null,
                  "delivered_at": null,
                  "cancelled_at": null,
                  "cancel_reason": null
                }
              }
            }
          },
          "400": {
            "description": "`OUT_OF_RANGE`: Adres, firmanın tanımladığı en fazla teslimat mesafesinin dışında. `OUT_OF_ZONE`: Adres hizmet bölgesinin dışında ya da ücret hesaplanamadı (çoğu zaman konum eksik). `PAYMENT_TYPE_NOT_FOUND`: `payment.kind` türünde etkin bir ödeme tipi tanımlı değil. `RESTAURANT_INACTIVE`: İşletme pasif durumda; sipariş alınmıyor. `OPEN_ORDER_LIMIT`: İşletmenin aynı anda açık sipariş sınırı doldu. `CREDIT_LIMIT`: İşletmenin cari borcu firmanın belirlediği sınırı aştı. `INVALID_JSON`: Gövde geçerli bir JSON değil.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "OUT_OF_RANGE",
                    "message": "Adres, firmanın tanımladığı en fazla teslimat mesafesinin dışında."
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: İstekte API anahtarı yok ya da `ks_` ile başlamıyor. `API_KEY_INVALID`: Anahtar yanlış, silinmiş ya da pasif.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "API_KEY_REQUIRED",
                    "message": "İstekte API anahtarı yok ya da `ks_` ile başlamıyor."
                  }
                }
              }
            }
          },
          "404": {
            "description": "`NOT_FOUND`: Sipariş ya da işletme bulunamadı. Anahtarınızın göremediği bir işletmenin siparişi de böyle görünür.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "NOT_FOUND",
                    "message": "Sipariş ya da işletme bulunamadı. Anahtarınızın göremediği bir işletmenin siparişi de böyle görünür."
                  }
                }
              }
            }
          },
          "413": {
            "description": "`BODY_TOO_LARGE`: Gövde 2 MB'tan büyük.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "BODY_TOO_LARGE",
                    "message": "Gövde 2 MB'tan büyük."
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION`: Eksik ya da hatalı alan. Hangi alanın neden reddedildiği `fields` içinde yazar.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "VALIDATION",
                    "message": "Eksik ya da hatalı alan. Hangi alanın neden reddedildiği `fields` içinde yazar."
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Dakikalık istek sınırı aşıldı.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Dakikalık istek sınırı aşıldı."
                  }
                }
              }
            }
          },
          "500": {
            "description": "`INTERNAL`: Sunucuda beklenmeyen bir hata oluştu.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL",
                    "message": "Sunucuda beklenmeyen bir hata oluştu."
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "external_id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100,
                    "examples": [
                      "POS-10452"
                    ],
                    "description": "Siparişin sizin sisteminizdeki benzersiz kimliği. Yinelenen gönderimleri ayıklamak ve siparişi sonradan `ext:` ile bulmak için kullanılır."
                  },
                  "external_code": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 100,
                    "examples": [
                      "A-52"
                    ],
                    "description": "Panelde ve kurye uygulamasında gösterilecek kısa sipariş numaranız (ör. adisyon no)."
                  },
                  "restaurant_id": {
                    "type": "integer",
                    "examples": [
                      1
                    ],
                    "description": "İşletmenin kimliği. Anahtarınız bir işletmeye bağlı değilse `restaurant_id` ya da `restaurant_code` zorunludur; bağlıysa yok sayılır. Gövde yerine sorgu dizgisinde de gönderilebilir."
                  },
                  "restaurant_code": {
                    "type": "string",
                    "examples": [
                      "R001"
                    ],
                    "description": "`restaurant_id` yerine işletme kodu (ör. `R001`). Kodu kurye firmanız verir."
                  },
                  "customer": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 150,
                        "examples": [
                          "Ayşe Yılmaz"
                        ],
                        "description": "Müşterinin adı."
                      },
                      "phone": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 30,
                        "examples": [
                          "05321234567"
                        ],
                        "description": "Müşterinin telefonu. `+90 532 123 45 67`, `905321234567`, `5321234567` gibi biçimler kabul edilir ve `05321234567` olarak saklanır. Kurye firması \"Müşteri telefonu zorunlu\" ayarını açtıysa zorunludur."
                      }
                    },
                    "description": "Müşteri."
                  },
                  "address": {
                    "type": "object",
                    "properties": {
                      "text": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 500,
                        "examples": [
                          "Caferağa Mah. Moda Cad. No:12 Kadıköy"
                        ],
                        "description": "Tam adres metni. Verilmezse `neighborhood`, `street`, `building`, `district`, `city` parçalarından birleştirilir; sonuç en az 3 karakter olmalıdır."
                      },
                      "city": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 60,
                        "description": "İl."
                      },
                      "district": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 60,
                        "description": "İlçe."
                      },
                      "neighborhood": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 100,
                        "description": "Mahalle."
                      },
                      "street": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 150,
                        "description": "Cadde/sokak."
                      },
                      "building": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 40,
                        "description": "Bina numarası; adres metnine `No:` ile eklenir."
                      },
                      "floor": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 20,
                        "examples": [
                          "3"
                        ],
                        "description": "Kat. `detail` verilmezse `Kat 3, Daire 7` biçiminde adres ayrıntısına yazılır."
                      },
                      "apartment": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 20,
                        "examples": [
                          "7"
                        ],
                        "description": "Daire."
                      },
                      "detail": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 255,
                        "description": "Adres ayrıntısı (bina adı, kat, daire). Verilirse `floor` ve `apartment` yok sayılır."
                      },
                      "directions": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "maxLength": 500,
                        "examples": [
                          "Eczanenin yanındaki bina"
                        ],
                        "description": "Kuryeye adres tarifi."
                      },
                      "lat": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "minimum": -90,
                        "maximum": 90,
                        "examples": [
                          40.9969
                        ],
                        "description": "Teslimat konumu (enlem). Önerilir."
                      },
                      "lng": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "minimum": -180,
                        "maximum": 180,
                        "examples": [
                          29.0342
                        ],
                        "description": "Teslimat konumu (boylam). Önerilir."
                      }
                    },
                    "description": "Teslimat adresi."
                  },
                  "payment": {
                    "type": "object",
                    "properties": {
                      "kind": {
                        "type": "string",
                        "enum": [
                          "cash",
                          "card",
                          "online",
                          "meal_card",
                          "other"
                        ],
                        "default": "cash",
                        "examples": [
                          "cash"
                        ],
                        "description": "Ödeme türü; bu türdeki ilk etkin ödeme tipi kullanılır."
                      },
                      "payment_type_id": {
                        "type": "integer",
                        "description": "Tür yerine doğrudan ödeme tipi ([Ödeme tiplerini listele](https://docs.kuryesoft.com,/api/odeme-tipleri)). Verilirse `kind` yok sayılır."
                      }
                    },
                    "description": "Ödeme. Hiçbiri verilmezse kapıda nakit kabul edilir."
                  },
                  "total_amount": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 9999999,
                    "default": 0,
                    "examples": [
                      285.5
                    ],
                    "description": "Sipariş tutarı (TL)."
                  },
                  "collect_amount": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 9999999,
                    "description": "Kuryenin kapıda tahsil edeceği tutar (TL). Verilmezse tahsilatlı ödeme tiplerinde `total_amount` kabul edilir. Önceden ödenmiş tiplerde her zaman `0`."
                  },
                  "package_count": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50,
                    "default": 1,
                    "description": "Paket sayısı."
                  },
                  "items": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200,
                          "examples": [
                            "Tavuk Dürüm"
                          ],
                          "description": "Ürün adı."
                        },
                        "quantity": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 1000,
                          "default": 1,
                          "examples": [
                            2
                          ],
                          "description": "Adet."
                        },
                        "price": {
                          "type": "number",
                          "minimum": 0,
                          "examples": [
                            120
                          ],
                          "description": "Birim fiyat (TL)."
                        },
                        "note": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "maxLength": 300,
                          "description": "Ürün notu."
                        },
                        "options": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Seçenekler (ör. \"Acısız\"). En çok 30, her biri en çok 200 karakter."
                        }
                      },
                      "required": [
                        "name"
                      ]
                    },
                    "description": "Ürünler. Kurye uygulamasında ve panelde gösterilir. En çok 100 kalem."
                  },
                  "note": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 1000,
                    "examples": [
                      "Zili çalmayın"
                    ],
                    "description": "Sipariş notu; kuryeye ve panele gösterilir."
                  },
                  "prep_minutes": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 600,
                    "examples": [
                      15
                    ],
                    "description": "Hazırlık süresi (dakika). Verilmezse firmanın varsayılanı (genellikle 15 dk) kullanılır."
                  },
                  "scheduled_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time",
                    "description": "İleri tarihli sipariş: hazırlığın başlayacağı an (ISO 8601, ör. `2026-11-21T19:30:00+03:00`). Kurye ataması bu anda başlar; sipariş `scheduled_at + prep_minutes` anında hazır kabul edilir."
                  }
                },
                "required": [
                  "external_id",
                  "address"
                ]
              },
              "example": {
                "external_id": "POS-10452",
                "external_code": "A-52",
                "customer": {
                  "name": "Ayşe Yılmaz",
                  "phone": "05321234567"
                },
                "address": {
                  "text": "Caferağa Mah. Moda Cad. No:12 Kadıköy",
                  "floor": "3",
                  "apartment": "7",
                  "directions": "Eczanenin yanındaki bina",
                  "lat": 40.9969,
                  "lng": 29.0342
                },
                "payment": {
                  "kind": "cash"
                },
                "total_amount": 285.5,
                "items": [
                  {
                    "name": "Tavuk Dürüm",
                    "quantity": 2,
                    "price": 120
                  },
                  {
                    "name": "Ayran",
                    "quantity": 1,
                    "price": 45.5,
                    "options": [
                      "Büyük"
                    ]
                  }
                ],
                "note": "Zili çalmayın",
                "prep_minutes": 15
              }
            }
          }
        }
      }
    },
    "/orders/{ref}": {
      "get": {
        "operationId": "getOrder",
        "tags": [
          "Siparişler"
        ],
        "summary": "Siparişi sorgula",
        "description": "Siparişin güncel durumu, kurye bilgisi, tahmini teslim zamanı ve takip bağlantısı.\n\nDurum değişikliklerini öğrenmenin asıl yolu [webhook'lar](https://docs.kuryesoft.com,/webhooklar)dır; bu çağrıyı webhook'u kaçırdığınızdan şüphelendiğinizde ya da kullanıcı ekranı açtığında son durumu almak için kullanın.\n\nPaket yoldayken (`picked_up`, `at_customer`) `courier.lat` ve `courier.lng` kuryenin son konumunu verir. Düzenli sorgulayacaksanız 30 saniyeden sık sorgulamayın ve sonuçlanan siparişleri (`delivered`, `cancelled`, `failed`) sorgulamayı bırakın.\n\nİşletmeye bağlı anahtar yalnızca kendi işletmesinin siparişlerini görür; diğerleri için `404` döner.\n\nBelge: https://docs.kuryesoft.com,/api/siparis-sorgula",
        "parameters": [
          {
            "name": "ref",
            "in": "path",
            "required": true,
            "description": "Sipariş başvurusu: sistemdeki sipariş kimliği (`1842`), sipariş numarası (`2611200042`) ya da gönderdiğiniz kimliğin başına `ext:` eklenmiş hali (`ext:POS-10452`). Bkz. [Temel kavramlar](https://docs.kuryesoft.com,/temel-kavramlar#siparis-basvurusu).",
            "schema": {
              "type": "string"
            },
            "example": "ext:POS-10452"
          }
        ],
        "responses": {
          "200": {
            "description": "Sipariş.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiOrder"
                },
                "example": {
                  "id": 1842,
                  "code": "2611200042",
                  "external_id": "POS-10452",
                  "status": "picked_up",
                  "status_label": "Yolda",
                  "restaurant_id": 1,
                  "tracking_url": "https://kurye.firmaniz.com/takip/oKe9xPqrlr7b_4jbNQiNCw",
                  "courier": {
                    "name": "Ahmet Yılmaz",
                    "phone": "05550000001",
                    "lat": 40.992,
                    "lng": 29.03
                  },
                  "distance_m": 1754,
                  "eta_at": "2026-11-20T18:31:28.000Z",
                  "delivery_fee": 70,
                  "total_amount": 285.5,
                  "collect_amount": 285.5,
                  "created_at": "2026-11-20T18:10:32.000Z",
                  "assigned_at": "2026-11-20T18:12:05.000Z",
                  "picked_up_at": "2026-11-20T18:24:40.000Z",
                  "delivered_at": null,
                  "cancelled_at": null,
                  "cancel_reason": null
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: İstekte API anahtarı yok ya da `ks_` ile başlamıyor. `API_KEY_INVALID`: Anahtar yanlış, silinmiş ya da pasif.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "API_KEY_REQUIRED",
                    "message": "İstekte API anahtarı yok ya da `ks_` ile başlamıyor."
                  }
                }
              }
            }
          },
          "404": {
            "description": "`NOT_FOUND`: Sipariş ya da işletme bulunamadı. Anahtarınızın göremediği bir işletmenin siparişi de böyle görünür.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "NOT_FOUND",
                    "message": "Sipariş ya da işletme bulunamadı. Anahtarınızın göremediği bir işletmenin siparişi de böyle görünür."
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Dakikalık istek sınırı aşıldı.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Dakikalık istek sınırı aşıldı."
                  }
                }
              }
            }
          },
          "500": {
            "description": "`INTERNAL`: Sunucuda beklenmeyen bir hata oluştu.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL",
                    "message": "Sunucuda beklenmeyen bir hata oluştu."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/orders/{ref}/ready": {
      "post": {
        "operationId": "markOrderReady",
        "tags": [
          "Siparişler"
        ],
        "summary": "Hazır işaretle",
        "description": "Paketin hazır olduğunu bildirir; atanmış kuryeye bildirim gider.\n\nMutfakta paket hazır olduğunda çağırın. Kurye atanmışsa telefonuna \"Sipariş hazır\" bildirimi gider; sipariş henüz bekliyorsa atama hemen yeniden denenir. Kurye firması \"hazır olunca ata\" senaryosunu kullanıyorsa otomatik atama ancak bu çağrıdan sonra başlar. Bkz. [Hazırlık süresi](https://docs.kuryesoft.com,/temel-kavramlar#hazirlik).\n\nGövde gerekmez. Zaten hazır işaretli siparişte tekrar çağırmak zararsızdır. Hazır işareti webhook olayı **üretmez**.\n\nBelge: https://docs.kuryesoft.com,/api/siparis-hazir",
        "parameters": [
          {
            "name": "ref",
            "in": "path",
            "required": true,
            "description": "Sipariş başvurusu: sistemdeki sipariş kimliği (`1842`), sipariş numarası (`2611200042`) ya da gönderdiğiniz kimliğin başına `ext:` eklenmiş hali (`ext:POS-10452`). Bkz. [Temel kavramlar](https://docs.kuryesoft.com,/temel-kavramlar#siparis-basvurusu).",
            "schema": {
              "type": "string"
            },
            "example": "ext:POS-10452"
          }
        ],
        "responses": {
          "200": {
            "description": "Sipariş (hazır işaretli).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiOrder"
                },
                "example": {
                  "id": 1842,
                  "code": "2611200042",
                  "external_id": "POS-10452",
                  "status": "pending",
                  "status_label": "Bekliyor",
                  "restaurant_id": 1,
                  "tracking_url": "https://kurye.firmaniz.com/takip/oKe9xPqrlr7b_4jbNQiNCw",
                  "courier": null,
                  "distance_m": 1754,
                  "eta_at": null,
                  "delivery_fee": 70,
                  "total_amount": 285.5,
                  "collect_amount": 285.5,
                  "created_at": "2026-11-20T18:10:32.000Z",
                  "assigned_at": null,
                  "picked_up_at": null,
                  "delivered_at": null,
                  "cancelled_at": null,
                  "cancel_reason": null
                }
              }
            }
          },
          "400": {
            "description": "`ORDER_FINAL`: Sipariş sonuçlanmış (teslim edildi, teslim edilemedi); değiştirilemez.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "ORDER_FINAL",
                    "message": "Sipariş sonuçlanmış (teslim edildi, teslim edilemedi); değiştirilemez."
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: İstekte API anahtarı yok ya da `ks_` ile başlamıyor. `API_KEY_INVALID`: Anahtar yanlış, silinmiş ya da pasif.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "API_KEY_REQUIRED",
                    "message": "İstekte API anahtarı yok ya da `ks_` ile başlamıyor."
                  }
                }
              }
            }
          },
          "404": {
            "description": "`NOT_FOUND`: Sipariş ya da işletme bulunamadı. Anahtarınızın göremediği bir işletmenin siparişi de böyle görünür.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "NOT_FOUND",
                    "message": "Sipariş ya da işletme bulunamadı. Anahtarınızın göremediği bir işletmenin siparişi de böyle görünür."
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Dakikalık istek sınırı aşıldı.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Dakikalık istek sınırı aşıldı."
                  }
                }
              }
            }
          },
          "500": {
            "description": "`INTERNAL`: Sunucuda beklenmeyen bir hata oluştu.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL",
                    "message": "Sunucuda beklenmeyen bir hata oluştu."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/orders/{ref}/cancel": {
      "post": {
        "operationId": "cancelOrder",
        "tags": [
          "Siparişler"
        ],
        "summary": "Siparişi iptal et",
        "description": "Siparişi iptal eder; atanmış kurye varsa siparişin iptal edildiği bildirilir.\n\nİşletme adına iptal yapılır; bu yüzden kurye firmasının işletmeler için belirlediği kurallar geçerlidir. Varsayılan olarak sipariş, kurye kabul edene kadar (`pending`, `assigned`, `accepted`) iptal edilebilir; kurye işletmeye vardıktan sonra `403 FORBIDDEN` döner ve iptal için kurye firmasıyla iletişime geçilmesi gerekir.\n\nİptal edilen siparişin ücretlendirilip ücretlendirilmeyeceği kurye firmasının ayarına bağlıdır (varsayılan: paket teslim alındıysa ücret alınır).\n\nİptal `order.cancelled` webhook olayını üretir.\n\nBelge: https://docs.kuryesoft.com,/api/siparis-iptal",
        "parameters": [
          {
            "name": "ref",
            "in": "path",
            "required": true,
            "description": "Sipariş başvurusu: sistemdeki sipariş kimliği (`1842`), sipariş numarası (`2611200042`) ya da gönderdiğiniz kimliğin başına `ext:` eklenmiş hali (`ext:POS-10452`). Bkz. [Temel kavramlar](https://docs.kuryesoft.com,/temel-kavramlar#siparis-basvurusu).",
            "schema": {
              "type": "string"
            },
            "example": "ext:POS-10452"
          }
        ],
        "responses": {
          "200": {
            "description": "Sipariş iptal edildi.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiOrder"
                },
                "example": {
                  "id": 1842,
                  "code": "2611200042",
                  "external_id": "POS-10452",
                  "status": "cancelled",
                  "status_label": "İptal edildi",
                  "restaurant_id": 1,
                  "tracking_url": "https://kurye.firmaniz.com/takip/oKe9xPqrlr7b_4jbNQiNCw",
                  "courier": null,
                  "distance_m": 1754,
                  "eta_at": null,
                  "delivery_fee": 70,
                  "total_amount": 285.5,
                  "collect_amount": 285.5,
                  "created_at": "2026-11-20T18:10:32.000Z",
                  "assigned_at": null,
                  "picked_up_at": null,
                  "delivered_at": null,
                  "cancelled_at": "2026-11-20T18:14:03.000Z",
                  "cancel_reason": "Müşteri vazgeçti"
                }
              }
            }
          },
          "400": {
            "description": "`ORDER_FINAL`: Sipariş sonuçlanmış (teslim edildi, teslim edilemedi); değiştirilemez.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "ORDER_FINAL",
                    "message": "Sipariş sonuçlanmış (teslim edildi, teslim edilemedi); değiştirilemez."
                  }
                }
              }
            }
          },
          "401": {
            "description": "`API_KEY_REQUIRED`: İstekte API anahtarı yok ya da `ks_` ile başlamıyor. `API_KEY_INVALID`: Anahtar yanlış, silinmiş ya da pasif.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "API_KEY_REQUIRED",
                    "message": "İstekte API anahtarı yok ya da `ks_` ile başlamıyor."
                  }
                }
              }
            }
          },
          "403": {
            "description": "`FORBIDDEN`: İşlem kurye firmasının ayarlarıyla kapalı (ör. sipariş bu aşamada işletme tarafından iptal edilemez).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "FORBIDDEN",
                    "message": "İşlem kurye firmasının ayarlarıyla kapalı (ör. sipariş bu aşamada işletme tarafından iptal edilemez)."
                  }
                }
              }
            }
          },
          "404": {
            "description": "`NOT_FOUND`: Sipariş ya da işletme bulunamadı. Anahtarınızın göremediği bir işletmenin siparişi de böyle görünür.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "NOT_FOUND",
                    "message": "Sipariş ya da işletme bulunamadı. Anahtarınızın göremediği bir işletmenin siparişi de böyle görünür."
                  }
                }
              }
            }
          },
          "409": {
            "description": "`ALREADY_CANCELLED`: Sipariş zaten iptal edilmiş.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "ALREADY_CANCELLED",
                    "message": "Sipariş zaten iptal edilmiş."
                  }
                }
              }
            }
          },
          "422": {
            "description": "`VALIDATION`: Eksik ya da hatalı alan. Hangi alanın neden reddedildiği `fields` içinde yazar.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "VALIDATION",
                    "message": "Eksik ya da hatalı alan. Hangi alanın neden reddedildiği `fields` içinde yazar."
                  }
                }
              }
            }
          },
          "429": {
            "description": "`RATE_LIMITED`: Dakikalık istek sınırı aşıldı.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "RATE_LIMITED",
                    "message": "Dakikalık istek sınırı aşıldı."
                  }
                }
              }
            }
          },
          "500": {
            "description": "`INTERNAL`: Sunucuda beklenmeyen bir hata oluştu.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "INTERNAL",
                    "message": "Sunucuda beklenmeyen bir hata oluştu."
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 255,
                    "default": "Dış sistem tarafından iptal edildi",
                    "examples": [
                      "Müşteri vazgeçti"
                    ],
                    "description": "İptal sebebi. Panelde ve raporlarda görünür. [İptal sebepleri](https://docs.kuryesoft.com,/api/iptal-sebepleri) listesinden seçilmesi önerilir."
                  }
                }
              },
              "example": {
                "reason": "Müşteri vazgeçti"
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "orderEvent": {
      "post": {
        "summary": "Sipariş olayı",
        "description": "Sipariş durumu değiştiğinde webhook adresinize gönderilir. `x-kurye-signature` başlığı ham gövdenin HMAC-SHA256 özetidir (hex, anahtar: `whsec_...`). Ayrıntı: [Webhook'lar](https://docs.kuryesoft.com,/webhooklar). Olaylar: `order.created`, `order.assigned`, `order.accepted`, `order.courier_arrived`, `order.picked_up`, `order.at_customer`, `order.delivered`, `order.failed`, `order.cancelled`, `order.unassigned`.",
        "parameters": [
          {
            "name": "x-kurye-event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "order.created",
                "order.assigned",
                "order.accepted",
                "order.courier_arrived",
                "order.picked_up",
                "order.at_customer",
                "order.delivered",
                "order.failed",
                "order.cancelled",
                "order.unassigned",
                "webhook.test"
              ]
            }
          },
          {
            "name": "x-kurye-signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookPayload"
              },
              "example": {
                "event": "order.delivered",
                "sent_at": "2026-11-20T18:33:07.512Z",
                "order": {
                  "id": 1842,
                  "code": "2611200042",
                  "status": "delivered",
                  "status_label": "Teslim edildi",
                  "source": "api",
                  "is_simulated": false,
                  "external_code": "A-52",
                  "restaurant": {
                    "id": 1,
                    "name": "Lezzet Dürüm",
                    "address": "Caferağa Mah. Moda Cad. No:3 Kadıköy",
                    "phone": "02165550101",
                    "lat": 40.9869,
                    "lng": 29.0262
                  },
                  "courier": {
                    "id": 7,
                    "name": "Ahmet Yılmaz",
                    "phone": "05550000001",
                    "vehicle_type": "motorcycle",
                    "photo_url": null
                  },
                  "customer_name": "Ayşe Yılmaz",
                  "customer_phone": "05321234567",
                  "address": "Caferağa Mah. Moda Cad. No:12 Kadıköy",
                  "address_detail": "Kat 3, Daire 7",
                  "directions": "Eczanenin yanındaki bina",
                  "lat": 40.9969,
                  "lng": 29.0342,
                  "payment_type": {
                    "id": 1,
                    "name": "Kapıda Nakit",
                    "kind": "cash",
                    "collect_from_customer": true
                  },
                  "total_amount": 285.5,
                  "collect_amount": 285.5,
                  "package_count": 1,
                  "items": [
                    {
                      "name": "Tavuk Dürüm",
                      "price": 120,
                      "quantity": 2
                    },
                    {
                      "name": "Ayran",
                      "price": 45.5,
                      "options": [
                        "Büyük"
                      ],
                      "quantity": 1
                    }
                  ],
                  "note": "Zili çalmayın",
                  "is_ready": true,
                  "prep_minutes": 15,
                  "ready_at": "2026-11-20T18:21:10.000Z",
                  "scheduled_at": null,
                  "distance_m": 1754,
                  "duration_s": 253,
                  "eta_at": null,
                  "route_seq": 1,
                  "business_date": "2026-11-20",
                  "created_at": "2026-11-20T18:10:32.000Z",
                  "assigned_at": "2026-11-20T18:12:05.000Z",
                  "accepted_at": "2026-11-20T18:12:05.000Z",
                  "arrived_restaurant_at": "2026-11-20T18:19:51.000Z",
                  "picked_up_at": "2026-11-20T18:24:40.000Z",
                  "arrived_customer_at": "2026-11-20T18:32:12.000Z",
                  "delivered_at": "2026-11-20T18:33:07.000Z",
                  "cancelled_at": null,
                  "cancel_reason": null,
                  "delivery_note": null,
                  "proof_photo_url": null,
                  "customer_id": 311,
                  "tracking_token": "oKe9xPqrlr7b_4jbNQiNCw",
                  "restaurant_fee": 70
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Alındı. 8 saniye içinde herhangi bir 2xx yanıtı başarılı sayılır."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key",
        "description": "`ks_` ile başlayan API anahtarı."
      },
      "Bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Aynı anahtar `Authorization: Bearer ks_...` biçiminde de gönderilebilir."
      }
    },
    "schemas": {
      "ApiOrder": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "examples": [
              1842
            ],
            "description": "Siparişin sistemdeki kimliği. Kendi kaydınızda saklayın: webhook gövdesinde `order.id` olarak gelir."
          },
          "code": {
            "type": "string",
            "examples": [
              "2611200001"
            ],
            "description": "Sipariş numarası. Panelde ve kurye uygulamasında görünen numaradır (ör. `2611200001`)."
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "POS-10452"
            ],
            "description": "Siparişi gönderirken verdiğiniz kendi kimliğiniz."
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "assigned",
              "accepted",
              "at_restaurant",
              "picked_up",
              "at_customer",
              "delivered",
              "cancelled",
              "failed"
            ],
            "examples": [
              "pending"
            ],
            "description": "Siparişin durumu. Bkz. [Sipariş yaşam döngüsü](https://docs.kuryesoft.com,/siparis-yasam-dongusu)."
          },
          "status_label": {
            "type": "string",
            "examples": [
              "Bekliyor"
            ],
            "description": "Durumun Türkçe adı; ekranda gösterebilirsiniz."
          },
          "restaurant_id": {
            "type": "integer",
            "examples": [
              1
            ],
            "description": "Siparişin yazıldığı işletmenin kimliği."
          },
          "tracking_url": {
            "type": "string",
            "format": "uri",
            "examples": [
              "https://kurye.firmaniz.com/takip/oKe9xPqrlr7b_4jbNQiNCw"
            ],
            "description": "Müşteriyle paylaşılabilen canlı takip sayfası. Bkz. [Müşteri takibi](https://docs.kuryesoft.com,/musteri-takibi)."
          },
          "courier": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "name": {
                "type": "string",
                "examples": [
                  "Ahmet Yılmaz"
                ],
                "description": "Kuryenin adı."
              },
              "phone": {
                "type": "string",
                "examples": [
                  "05550000001"
                ],
                "description": "Kuryenin telefonu (05XXXXXXXXX)."
              },
              "lat": {
                "type": [
                  "number",
                  "null"
                ],
                "examples": [
                  40.992
                ],
                "description": "Kuryenin son konumu. Yalnızca paket yoldayken (`picked_up`, `at_customer`) dolar."
              },
              "lng": {
                "type": [
                  "number",
                  "null"
                ],
                "examples": [
                  29.03
                ],
                "description": "Kuryenin son konumu (boylam)."
              }
            },
            "description": "Atanan kurye; kurye atanmadıysa `null`."
          },
          "distance_m": {
            "type": [
              "integer",
              "null"
            ],
            "examples": [
              1754
            ],
            "description": "İşletmeden teslimat adresine yol mesafesi (metre). Konum yoksa `null`."
          },
          "eta_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Tahmini teslim zamanı. Kurye atandıktan sonra hesaplanır; sipariş sonuçlanınca `null` olur."
          },
          "delivery_fee": {
            "type": "number",
            "examples": [
              70
            ],
            "description": "İşletmeye yansıyan teslimat ücreti (TL). Kurye firması işletmenin ücretleri görmesini kapattıysa bu alan yanıtta **hiç yer almaz**."
          },
          "total_amount": {
            "type": "number",
            "examples": [
              285.5
            ],
            "description": "Sipariş tutarı (TL)."
          },
          "collect_amount": {
            "type": "number",
            "examples": [
              285.5
            ],
            "description": "Kuryenin kapıda tahsil edeceği tutar (TL). Önceden ödenmiş siparişte `0`."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Siparişin alındığı an."
          },
          "assigned_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Kuryenin atandığı an."
          },
          "picked_up_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Paketin teslim alındığı an."
          },
          "delivered_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Teslim edildiği an."
          },
          "cancelled_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "İptal edildiği ya da teslim edilemediği an."
          },
          "cancel_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "İptal ya da teslim edilememe sebebi."
          }
        },
        "examples": [
          {
            "id": 1842,
            "code": "2611200042",
            "external_id": "POS-10452",
            "status": "pending",
            "status_label": "Bekliyor",
            "restaurant_id": 1,
            "tracking_url": "https://kurye.firmaniz.com/takip/oKe9xPqrlr7b_4jbNQiNCw",
            "courier": null,
            "distance_m": 1754,
            "eta_at": null,
            "delivery_fee": 70,
            "total_amount": 285.5,
            "collect_amount": 285.5,
            "created_at": "2026-11-20T18:10:32.000Z",
            "assigned_at": null,
            "picked_up_at": null,
            "delivered_at": null,
            "cancelled_at": null,
            "cancel_reason": null
          }
        ]
      },
      "WebhookOrder": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Siparişin sistemdeki kimliği (API yanıtındaki `id`). Webhook'u kendi siparişinizle bununla eşleştirin."
          },
          "code": {
            "type": "string",
            "description": "Sipariş numarası."
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "assigned",
              "accepted",
              "at_restaurant",
              "picked_up",
              "at_customer",
              "delivered",
              "cancelled",
              "failed"
            ],
            "description": "Siparişin olay anındaki durumu."
          },
          "status_label": {
            "type": "string",
            "description": "Durumun Türkçe adı."
          },
          "source": {
            "type": "string",
            "description": "Siparişin geldiği kanal: bu API ile gönderilenlerde `api`, panelden girilenlerde `manual`, hazır platform/POS entegrasyonlarında sağlayıcının adı."
          },
          "is_simulated": {
            "type": "boolean",
            "description": "Her zaman `false`: simülasyon (test modu) siparişleri webhook ile gönderilmez."
          },
          "external_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "Gönderirken verdiğiniz `external_code`."
          },
          "restaurant": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "description": "İşletme kimliği."
              },
              "name": {
                "type": "string",
                "description": "İşletme adı."
              },
              "address": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "İşletme adresi."
              },
              "phone": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "İşletme telefonu."
              },
              "lat": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "İşletme konumu."
              },
              "lng": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "İşletme konumu."
              }
            },
            "description": "Siparişin işletmesi."
          },
          "courier": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "integer",
                "description": "Kurye kimliği."
              },
              "name": {
                "type": "string",
                "description": "Kuryenin adı."
              },
              "phone": {
                "type": "string",
                "description": "Kuryenin telefonu."
              },
              "vehicle_type": {
                "type": "string",
                "enum": [
                  "motorcycle",
                  "car",
                  "bicycle",
                  "scooter",
                  "walk"
                ],
                "description": "Araç türü."
              },
              "photo_url": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Kurye fotoğrafı."
              }
            },
            "description": "Atanan kurye; yoksa `null`."
          },
          "customer_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Müşteri adı."
          },
          "customer_phone": {
            "type": [
              "string",
              "null"
            ],
            "description": "Müşteri telefonu (05XXXXXXXXX)."
          },
          "address": {
            "type": "string",
            "description": "Teslimat adresi."
          },
          "address_detail": {
            "type": [
              "string",
              "null"
            ],
            "description": "Bina, kat, daire."
          },
          "directions": {
            "type": [
              "string",
              "null"
            ],
            "description": "Adres tarifi."
          },
          "lat": {
            "type": [
              "number",
              "null"
            ],
            "description": "Teslimat konumu."
          },
          "lng": {
            "type": [
              "number",
              "null"
            ],
            "description": "Teslimat konumu."
          },
          "payment_type": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "integer",
                "description": "Ödeme tipi kimliği."
              },
              "name": {
                "type": "string",
                "description": "Ödeme tipinin adı."
              },
              "kind": {
                "type": "string",
                "enum": [
                  "cash",
                  "card",
                  "online",
                  "meal_card",
                  "other"
                ],
                "description": "Ödeme türü."
              },
              "collect_from_customer": {
                "type": "boolean",
                "description": "Kurye kapıda tahsilat yapar mı."
              }
            },
            "description": "Ödeme tipi."
          },
          "total_amount": {
            "type": "number",
            "description": "Sipariş tutarı (TL)."
          },
          "collect_amount": {
            "type": "number",
            "description": "Kapıda tahsil edilecek tutar (TL)."
          },
          "package_count": {
            "type": "integer",
            "description": "Paket sayısı."
          },
          "items": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Ürün adı."
                },
                "quantity": {
                  "type": "number",
                  "description": "Adet."
                },
                "price": {
                  "type": "number",
                  "description": "Birim fiyat."
                },
                "note": {
                  "type": "string",
                  "description": "Ürün notu."
                },
                "options": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "Seçenekler."
                }
              }
            },
            "description": "Ürünler (gönderdiyseniz)."
          },
          "note": {
            "type": [
              "string",
              "null"
            ],
            "description": "Sipariş notu."
          },
          "is_ready": {
            "type": "boolean",
            "description": "İşletme siparişi hazır işaretledi mi."
          },
          "prep_minutes": {
            "type": "integer",
            "description": "Hazırlık süresi (dakika)."
          },
          "ready_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Siparişin hazır olacağı (ya da hazır işaretlendiği) an."
          },
          "scheduled_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "İleri tarihli siparişte hazırlığın başlayacağı an."
          },
          "distance_m": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Yol mesafesi (metre)."
          },
          "duration_s": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Tahmini yol süresi (saniye)."
          },
          "eta_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Tahmini teslim zamanı."
          },
          "route_seq": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Kuryenin rotasındaki sırası (birden çok paket taşırken)."
          },
          "business_date": {
            "type": "string",
            "format": "date",
            "description": "Siparişin yazıldığı iş günü (YYYY-AA-GG). İş günü firmanın ayarındaki saatte başlar."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Siparişin alındığı an."
          },
          "assigned_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Kuryenin atandığı an."
          },
          "accepted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Kuryenin kabul ettiği an."
          },
          "arrived_restaurant_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Kuryenin işletmeye vardığı an."
          },
          "picked_up_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Paketin teslim alındığı an."
          },
          "arrived_customer_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Kuryenin adrese vardığı an."
          },
          "delivered_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Teslim edildiği an."
          },
          "cancelled_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "İptal edildiği ya da teslim edilemediği an."
          },
          "cancel_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "İptal ya da teslim edilememe sebebi."
          },
          "delivery_note": {
            "type": [
              "string",
              "null"
            ],
            "description": "Kuryenin teslimatta yazdığı not."
          },
          "proof_photo_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Teslimat fotoğrafı (firma bu özelliği kullanıyorsa)."
          },
          "customer_id": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Müşteri kaydının kimliği (telefon numarasına göre)."
          },
          "tracking_token": {
            "type": "string",
            "description": "Takip sayfası anahtarı: takip adresi `{sunucu}/takip/{tracking_token}` biçimindedir."
          },
          "restaurant_fee": {
            "type": "number",
            "description": "İşletmeye yansıyan teslimat ücreti (TL)."
          }
        }
      },
      "WebhookPayload": {
        "type": "object",
        "required": [
          "event",
          "sent_at",
          "order"
        ],
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "order.created",
              "order.assigned",
              "order.accepted",
              "order.courier_arrived",
              "order.picked_up",
              "order.at_customer",
              "order.delivered",
              "order.failed",
              "order.cancelled",
              "order.unassigned"
            ]
          },
          "sent_at": {
            "type": "string",
            "format": "date-time"
          },
          "order": {
            "$ref": "#/components/schemas/WebhookOrder"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "API_KEY_REQUIRED",
                  "API_KEY_INVALID",
                  "FORBIDDEN",
                  "NOT_FOUND",
                  "ALREADY_CANCELLED",
                  "ORDER_FINAL",
                  "OUT_OF_RANGE",
                  "OUT_OF_ZONE",
                  "PAYMENT_TYPE_NOT_FOUND",
                  "RESTAURANT_INACTIVE",
                  "OPEN_ORDER_LIMIT",
                  "CREDIT_LIMIT",
                  "VALIDATION",
                  "INVALID_JSON",
                  "BODY_TOO_LARGE",
                  "RATE_LIMITED",
                  "INTERNAL"
                ],
                "description": "Makine tarafından okunacak hata kodu."
              },
              "message": {
                "type": "string",
                "description": "Türkçe, kullanıcıya gösterilebilir açıklama."
              },
              "fields": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Yalnızca `VALIDATION`: alan yolu (ör. `address.text`) → hata iletisi."
              }
            }
          }
        }
      }
    }
  }
}