openapi: 3.1.0
info:
  title: NarPOS Partner API
  version: 1.0.0
  description: Şubeye özel katalog, sipariş, ödeme ve durum API’si. Para değerleri TRY kuruştur.
servers:
  - url: https://bxvwuasaytgdqnsiinni.supabase.co/functions/v1/narpos/v1
    description: NarPOS sandbox
security:
  - BranchKey: []
paths:
  /connections/redeem:
    post:
      operationId: redeemConnection
      security:
        - PartnerSecret: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code]
              properties:
                code: { $ref: '#/components/schemas/ActivationCode' }
      responses:
        '200':
          description: Kod kullanıldı ve şube anahtarı üretildi.
          content:
            application/json:
              schema:
                type: object
                required: [connection_id, branch_id, connection_state, api_key]
                properties:
                  connection_id: { $ref: '#/components/schemas/UUID' }
                  branch_id: { $ref: '#/components/schemas/UUID' }
                  connection_state: { $ref: '#/components/schemas/ConnectionState' }
                  api_key: { $ref: '#/components/schemas/Token' }
        default: { $ref: '#/components/responses/APIError' }
  /branch:
    get:
      operationId: getConnectionBranch
      responses:
        '200':
          description: Bağlantının ait olduğu şube.
          content:
            application/json:
              schema:
                type: object
                required: [id, name, connection_id, connection_state]
                properties:
                  id: { $ref: '#/components/schemas/UUID' }
                  name: { type: string }
                  connection_id: { $ref: '#/components/schemas/UUID' }
                  connection_state: { $ref: '#/components/schemas/ConnectionState' }
        default: { $ref: '#/components/responses/APIError' }
  /catalog/revisions/{revision}/parts/{part}:
    parameters:
      - $ref: '#/components/parameters/Revision'
      - name: part
        in: path
        required: true
        schema: { type: integer, minimum: 1, maximum: 100 }
    put:
      operationId: uploadCatalogPart
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [items]
              properties:
                items:
                  type: array
                  maxItems: 500
                  items: { $ref: '#/components/schemas/CatalogItem' }
      responses:
        '200':
          description: Parça kaydedildi.
          content:
            application/json:
              schema:
                type: object
                properties:
                  revision: { $ref: '#/components/schemas/Revision' }
                  part: { type: integer }
        default: { $ref: '#/components/responses/APIError' }
  /catalog/revisions/{revision}/commit:
    parameters:
      - $ref: '#/components/parameters/Revision'
    post:
      operationId: commitCatalog
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [part_count]
              properties:
                part_count: { type: integer, minimum: 1, maximum: 100 }
      responses:
        '200':
          description: Tam katalog doğrulandı ve kabul edildi.
          content:
            application/json:
              schema:
                type: object
                properties:
                  revision: { $ref: '#/components/schemas/Revision' }
                  status: { const: accepted }
        default: { $ref: '#/components/responses/APIError' }
  /catalog/revisions/{revision}:
    parameters:
      - $ref: '#/components/parameters/Revision'
    get:
      operationId: getCatalogRevision
      responses:
        '200':
          description: Gelen parçalar ve uygulanan katalog sürümü.
          content:
            application/json:
              schema:
                type: object
                properties:
                  revision: { $ref: '#/components/schemas/Revision' }
                  applied_revision: { type: string, pattern: '^[0-9]+$' }
                  status: { enum: [staging, accepted] }
                  parts: { type: array, items: { type: integer } }
        default: { $ref: '#/components/responses/APIError' }
  /catalog/availability:
    post:
      operationId: setAvailability
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [kind, id, available, source_revision]
              properties:
                kind: { enum: [product, variant, option] }
                id: { $ref: '#/components/schemas/ExternalID' }
                available: { type: boolean }
                source_revision: { $ref: '#/components/schemas/Revision' }
      responses:
        '200': { description: Satış değişikliği işlendi veya daha yeni bir sürüm zaten kayıtlı. }
        default: { $ref: '#/components/responses/APIError' }
  /orders/{order_id}:
    parameters:
      - $ref: '#/components/parameters/OrderID'
    get:
      operationId: getOrder
      responses:
        '200':
          description: Kesinleşen sipariş.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        default: { $ref: '#/components/responses/APIError' }
  /orders/{order_id}/ack:
    parameters:
      - $ref: '#/components/parameters/OrderID'
      - $ref: '#/components/parameters/Idempotency'
    put:
      operationId: acknowledgeOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [version, external_id]
              properties:
                version: { $ref: '#/components/schemas/Version' }
                external_id: { $ref: '#/components/schemas/ExternalID' }
      responses:
        '200': { $ref: '#/components/responses/OrderWriteResult' }
        default: { $ref: '#/components/responses/APIError' }
  /orders/{order_id}/updates:
    parameters:
      - $ref: '#/components/parameters/OrderID'
      - $ref: '#/components/parameters/Idempotency'
    post:
      operationId: updateOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [version]
              anyOf:
                - required: [status]
                - required: [collection]
              properties:
                version: { $ref: '#/components/schemas/Version' }
                status: { enum: [preparing, ready, delivered, cancelled] }
                reason: { type: string, minLength: 1, maxLength: 300 }
                collection: { $ref: '#/components/schemas/Collection' }
      responses:
        '200': { $ref: '#/components/responses/OrderWriteResult' }
        default: { $ref: '#/components/responses/APIError' }
  /orders:
    get:
      operationId: listOrders
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - name: after
          in: query
          schema: { $ref: '#/components/schemas/UUID' }
      responses:
        '200':
          description: Açık ve son 30 günde değişen siparişler.
          content:
            application/json:
              schema:
                type: object
                required: [items, has_more, next_cursor, event_cursor]
                properties:
                  items: { type: array, items: { $ref: '#/components/schemas/OrderSummary' } }
                  has_more: { type: boolean }
                  next_cursor: { type: [string, 'null'], format: uuid }
                  event_cursor: { type: string, pattern: '^[0-9]+$' }
        default: { $ref: '#/components/responses/APIError' }
  /events:
    get:
      operationId: listEvents
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - name: after
          in: query
          schema: { type: string, pattern: '^[0-9]+$', default: '0' }
      responses:
        '200':
          description: Son 30 gündeki olaylar.
          content:
            application/json:
              schema:
                type: object
                required: [items, has_more, next_cursor]
                properties:
                  items: { type: array, items: { $ref: '#/components/schemas/Event' } }
                  has_more: { type: boolean }
                  next_cursor: { type: string }
        '410': { $ref: '#/components/responses/APIError' }
        default: { $ref: '#/components/responses/APIError' }
  /sandbox/scenarios:
    post:
      operationId: createSandboxOrder
      description: Ayrı sandbox ortamında sentetik bir sipariş oluşturur.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [payment]
              properties:
                payment: { enum: [cash, card, wallet, online, free] }
      responses:
        '201':
          description: Sentetik sipariş kimliği.
          content:
            application/json:
              schema:
                type: object
                properties:
                  order_id: { $ref: '#/components/schemas/UUID' }
                  version: { $ref: '#/components/schemas/Version' }
                  payment: { enum: [cash, card, wallet, online, free] }
        default: { $ref: '#/components/responses/APIError' }
  /sandbox/scenarios/{order_id}/refunds:
    parameters:
      - $ref: '#/components/parameters/OrderID'
    post:
      operationId: createSandboxRefund
      description: Sentetik online siparişe kısmi veya tam iade sonucu ekler.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount_minor, status]
              properties:
                amount_minor: { $ref: '#/components/schemas/Money', minimum: 1 }
                status: { enum: [pending, succeeded, failed] }
      responses:
        '201':
          description: Oluşturulan iade sonucu.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Refund' }
        default: { $ref: '#/components/responses/APIError' }
webhooks:
  orderEvent:
    post:
      operationId: receiveOrderEvent
      security: []
      parameters:
        - name: X-NarPOS-Timestamp
          in: header
          required: true
          schema: { type: string, pattern: '^[0-9]+$' }
        - name: X-NarPOS-Signature
          in: header
          required: true
          schema: { type: string, pattern: '^v1=[0-9a-f]{64}$' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Event' }
      responses:
        '2XX': { description: Olay teslim alındı. }
components:
  securitySchemes:
    BranchKey: { type: http, scheme: bearer }
    PartnerSecret: { type: http, scheme: bearer }
  parameters:
    OrderID:
      name: order_id
      in: path
      required: true
      schema: { $ref: '#/components/schemas/UUID' }
    Revision:
      name: revision
      in: path
      required: true
      schema: { $ref: '#/components/schemas/Revision' }
    PageSize:
      name: limit
      in: query
      schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
    Idempotency:
      name: Idempotency-Key
      in: header
      required: true
      schema: { $ref: '#/components/schemas/ExternalID' }
  responses:
    APIError:
      description: İstek tamamlanamadı.
      content:
        application/json:
          schema:
            type: object
            required: [error]
            properties:
              error: { type: string }
    OrderWriteResult:
      description: Siparişin geçerli sürümü ve durumu.
      content:
        application/json:
          schema:
            type: object
            required: [id, version, external_id, status]
            properties:
              id: { $ref: '#/components/schemas/UUID' }
              version: { $ref: '#/components/schemas/Version' }
              external_id: { type: [string, 'null'] }
              status: { $ref: '#/components/schemas/OrderStatus' }
  schemas:
    UUID: { type: string, format: uuid }
    ActivationCode:
      type: string
      pattern: '^(?:[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{4}[- ]?[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{4}|[0-9a-f]{64})$'
      description: Tek kullanımlık sekiz karakterli şube kodu. Büyük/küçük harf fark etmez, aradaki tire veya boşluk isteğe bağlıdır. Önceden üretilen uzun kodlar süreleri dolana kadar kabul edilir.
      examples: ['7K3M-9X2C']
    Token: { type: string, pattern: '^[0-9a-f]{64}$' }
    ExternalID: { type: string, minLength: 1, maxLength: 128 }
    Revision: { type: string, pattern: '^[1-9][0-9]{0,14}$' }
    Version: { type: integer, minimum: 1, maximum: 2147483647 }
    Money: { type: integer, minimum: 0, description: TRY kuruş. }
    ConnectionState: { enum: [active, draining, revoked, null] }
    Prices:
      type: object
      anyOf:
        - required: [default]
        - required: [pickup, delivery, dine_in]
      additionalProperties: false
      properties:
        default: { $ref: '#/components/schemas/Money', maximum: 999999999 }
        pickup: { $ref: '#/components/schemas/Money', maximum: 999999999 }
        delivery: { $ref: '#/components/schemas/Money', maximum: 999999999 }
        dine_in: { $ref: '#/components/schemas/Money', maximum: 999999999 }
    CatalogItem:
      type: object
      required: [kind, id, name, available]
      properties:
        kind: { enum: [category, product, group, variant, option] }
        id: { $ref: '#/components/schemas/ExternalID' }
        name: { type: string, minLength: 1, maxLength: 200 }
        available: { type: boolean }
        sort: { type: integer, minimum: 0, maximum: 100000, default: 0 }
        category_id: { $ref: '#/components/schemas/ExternalID' }
        description: { type: [string, 'null'], maxLength: 2000 }
        prices: { $ref: '#/components/schemas/Prices' }
        selection: { enum: [single, multiple] }
        product_id: { $ref: '#/components/schemas/ExternalID' }
        group_id: { $ref: '#/components/schemas/ExternalID' }
        required: { type: boolean, default: false }
        min_select: { type: integer, minimum: 1, maximum: 100, default: 1 }
        max_select: { type: [integer, 'null'], minimum: 1, maximum: 100 }
        free_count: { type: integer, minimum: 0, maximum: 100, default: 0 }
        price_mode: { enum: [set, add] }
        allow_quantity: { type: boolean, default: false }
        max_per_option: { type: integer, minimum: 1, maximum: 20, default: 1 }
        default: { type: boolean, default: false }
      allOf:
        - if: { properties: { kind: { const: product } } }
          then: { required: [category_id, prices] }
        - if: { properties: { kind: { const: group } } }
          then: { required: [selection, price_mode, product_id] }
        - if: { properties: { kind: { enum: [variant, option] } } }
          then: { required: [group_id, prices] }
        - if: { required: [price_mode], properties: { price_mode: { const: set } } }
          then: { required: [required], properties: { required: { const: true }, selection: { const: single } } }
    Event:
      type: object
      required: [event_id, cursor, type, branch_id, connection_id, order_id, version, occurred_at]
      properties:
        event_id: { $ref: '#/components/schemas/UUID' }
        cursor: { type: string }
        type: { enum: [order.created, order.status_changed, order.cancelled, order.payment_changed] }
        branch_id: { $ref: '#/components/schemas/UUID' }
        connection_id: { $ref: '#/components/schemas/UUID' }
        order_id: { $ref: '#/components/schemas/UUID' }
        version: { $ref: '#/components/schemas/Version' }
        occurred_at: { type: string, format: date-time }
    Collection:
      type: object
      required: [method, amount_minor, reference]
      properties:
        method: { enum: [cash, card] }
        amount_minor: { $ref: '#/components/schemas/Money', minimum: 1 }
        reference: { $ref: '#/components/schemas/ExternalID' }
    OrderStatus: { enum: [received, preparing, ready, delivered, cancelled] }
    OrderSummary:
      type: object
      required: [id, version, status, order_no]
      properties:
        id: { $ref: '#/components/schemas/UUID' }
        version: { $ref: '#/components/schemas/Version' }
        status: { $ref: '#/components/schemas/OrderStatus' }
        order_no: { type: integer }
    Order:
      allOf:
        - $ref: '#/components/schemas/OrderSummary'
        - type: object
          required: [branch_id, connection_id, fulfillment, amounts, payment, items]
          properties:
            branch_id: { $ref: '#/components/schemas/UUID' }
            connection_id: { $ref: '#/components/schemas/UUID' }
            external_id: { type: [string, 'null'] }
            fulfillment: { enum: [pickup, delivery, dine_in] }
            created_at: { type: string, format: date-time }
            received_at: { type: [string, 'null'], format: date-time }
            preparing_at: { type: [string, 'null'], format: date-time }
            ready_at: { type: [string, 'null'], format: date-time }
            delivered_at: { type: [string, 'null'], format: date-time }
            cancelled_at: { type: [string, 'null'], format: date-time }
            cancel_reason: { type: [string, 'null'] }
            note: { type: [string, 'null'] }
            customer:
              type: object
              properties:
                name: { type: [string, 'null'] }
                phone: { type: [string, 'null'] }
            delivery:
              type: [object, 'null']
              description: Siparişteki teslimat adresi kaydı. Gel-al ve restoranda servis için null.
              properties:
                line: { type: [string, 'null'] }
                area: { type: [string, 'null'] }
                details: { type: [string, 'null'] }
                phone: { type: [string, 'null'] }
                notes: { type: [string, 'null'] }
                lat: { type: [number, 'null'] }
                lng: { type: [number, 'null'] }
            amounts: { $ref: '#/components/schemas/Amounts' }
            payment: { $ref: '#/components/schemas/Payment' }
            items: { type: array, items: { $ref: '#/components/schemas/Line' } }
    Amounts:
      type: object
      properties:
        currency: { const: TRY }
        subtotal_minor: { $ref: '#/components/schemas/Money' }
        delivery_minor: { $ref: '#/components/schemas/Money' }
        total_minor: { $ref: '#/components/schemas/Money' }
        coupon_minor: { $ref: '#/components/schemas/Money' }
        coupon_code: { type: [string, 'null'] }
        campaign_minor: { $ref: '#/components/schemas/Money' }
        campaign_name: { type: [string, 'null'] }
        points_minor: { $ref: '#/components/schemas/Money' }
        points_used: { type: integer, minimum: 0 }
        points_earned: { type: integer, minimum: 0 }
    Refund:
      type: object
      properties:
        id: { $ref: '#/components/schemas/UUID' }
        amount_minor: { $ref: '#/components/schemas/Money' }
        status: { enum: [pending, processing, succeeded, failed] }
        at: { type: string, format: date-time }
    Payment:
      type: object
      properties:
        method: { enum: [wallet, online, cash, card] }
        status: { enum: [pending, paid, refunded, failed] }
        collected_minor: { $ref: '#/components/schemas/Money' }
        due_minor: { $ref: '#/components/schemas/Money' }
        collection:
          oneOf:
            - $ref: '#/components/schemas/Collection'
            - type: 'null'
        refunds:
          type: array
          items: { $ref: '#/components/schemas/Refund' }
    Line:
      type: object
      properties:
        id: { $ref: '#/components/schemas/UUID' }
        app_product_id: { type: [string, 'null'], format: uuid }
        product_id: { $ref: '#/components/schemas/ExternalID' }
        name: { type: string }
        qty: { type: integer, minimum: 1 }
        unit_minor: { $ref: '#/components/schemas/Money' }
        base_minor: { $ref: '#/components/schemas/Money' }
        total_minor: { $ref: '#/components/schemas/Money' }
        note: { type: [string, 'null'] }
        selections:
          type: array
          items:
            type: object
            properties:
              kind: { enum: [variant, option] }
              narpos_id: { $ref: '#/components/schemas/ExternalID' }
              narpos_group_id: { $ref: '#/components/schemas/ExternalID' }
              group: { type: string }
              group_id: { $ref: '#/components/schemas/UUID' }
              option_id: { $ref: '#/components/schemas/UUID' }
              name: { type: string }
              qty: { type: integer, minimum: 1 }
              price_minor: { $ref: '#/components/schemas/Money' }
              charged_minor: { $ref: '#/components/schemas/Money' }
