openapi: 3.2.0
info:
  title: Hasfiyat Altın & Döviz Fiyat Fiyatlar API
  version: 1.0.0
  summary: Türkiye serbest piyasa altın, gümüş ve döviz fiyatları için canlı REST + WebSocket API.
  description: Hasfiyat API; kuyumcular, döviz büroları, sarraflar ve e-ticaret siteleri için gram altın, çeyrek, yarım, tam, ATA, 22/18/14 ayar bilezik, has altın, ons (XAU), gümüş ve döviz kurlarını birden fazla canlı kaynaktan tek standart şemada sunar. Kaynak önceliklendirme ve otomatik yük devretme desteklenir.
  termsOfService: https://altinapi.hasfiyat.com/kullanim-kosullari
  contact:
    name: Hasfiyat
    url: https://altinapi.hasfiyat.com/iletisim
  license:
    name: Ticari lisans
    url: https://altinapi.hasfiyat.com/kullanim-kosullari
servers:
- url: https://api.hasfiyat.com
  description: Üretim
security:
- BearerAuth: []
- ApiKeyHeader: []
tags:
- name: Fiyatlar
  description: Canlı altın, gümüş ve döviz fiyatları
paths:
  /api/prices:
    get:
      tags:
      - Fiyatlar
      operationId: getPrices
      summary: Canlı altın, gümüş ve döviz fiyatlarını döndürür
      description: Seçilen veri kaynağının o anki alış/satış fiyatlarını standart şemada döndürür. Kaynak belirtilmezse hesabınızda tanımlı öncelik sırası kullanılır.
      parameters:
      - name: source
        in: query
        required: false
        description: Veri kaynağı. Belirtilmezse hesabın öncelik sırası uygulanır.
        schema:
          type: string
          enum:
          - harem
          - hakan
          - mayda
          - myakche
          - metal
          - nadir
          - anlik
          - saglamoglu
          - fikrisahin
          - doviz
          - sahap
      - name: symbols
        in: query
        required: false
        description: Virgülle ayrılmış kalem listesi (ör. HAS,GRAM,CEYREK,YARIM,TAM,USD,EUR). Boş bırakılırsa kaynağın tüm kalemleri döner.
        schema:
          type: string
      - name: birim
        in: query
        required: false
        description: 1 verilirse her kaleme unit ve currency alanları eklenir.
        schema:
          type: string
          enum:
          - '1'
      responses:
        '200':
          description: Başarılı
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FiyatCevabi'
              example:
                source: harem
                count: 3
                data:
                - title: HAS ALTIN
                  buy: 6.584,13
                  sell: 6.600,42
                - title: YENİ ÇEYREK
                  buy: 10.774,00
                  sell: 10.958,00
                - title: USD/TL
                  buy: 42,3100
                  sell: 42,3600
                dataAgeMs: 1200
                stale: false
                lastUpdate: '2026-10-05T07:00:00.000Z'
        '401':
          description: API anahtarı gönderilmedi veya geçersiz
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hata'
        '403':
          description: Erişim reddedildi (IP bağlama sınırı; varsayılan olarak etkin değildir)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hata'
        '429':
          description: İstek limiti aşıldı
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hata'
components:
  schemas:
    Hata:
      type: object
      properties:
        error:
          type: string
          description: Hata açıklaması
        reason:
          type: string
          description: Makine tarafından okunabilir hata kodu
    FiyatKalemi:
      type: object
      required:
      - title
      - buy
      - sell
      properties:
        title:
          type: string
          description: Kalem adı (kaynağın kullandığı başlık)
          examples:
          - HAS ALTIN
          - 22 AYAR
          - YENİ ÇEYREK
          - ONS
          - USD/TL
        buy:
          type: string
          description: Alış fiyatı; Türkçe sayı biçiminde metin (binlik ayırıcı nokta, ondalık virgül)
        sell:
          type: string
          description: Satış fiyatı; Türkçe sayı biçiminde metin
        unit:
          type: string
          description: 'Yalnız birim=1 ile: birim'
        currency:
          type: string
          description: 'Yalnız birim=1 ile: para birimi'
    FiyatCevabi:
      type: object
      required:
      - source
      - data
      properties:
        source:
          type: string
          description: Fiyatın alındığı veri kaynağı
        count:
          type: integer
          description: Dönen kalem sayısı
        data:
          type: array
          items:
            $ref: '#/components/schemas/FiyatKalemi'
        dataAgeMs:
          type:
          - integer
          - 'null'
          description: Verinin göreli yaşı (dataAge)
        stale:
          type:
          - boolean
          - 'null'
          description: Veri bayatsa true
        lastUpdate:
          type:
          - string
          - 'null'
          format: date-time
          description: Verinin önbelleğe yazıldığı an (ISO 8601, UTC)
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer <api-anahtari>'
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: 'x-api-key: <api-anahtari>'
externalDocs:
  description: API dokümantasyonu
  url: https://altinapi.hasfiyat.com/docs