openapi: "3.1.0"
info:
  title: EmlakIQ Veri API
  version: "1.0"
  description: |
    Türkiye gayrimenkul veri altyapısı — parsel, imar, yapı, risk, piyasa aktivitesi
    ve makro göstergeleri tekil varlık kimliği altında birleştirir.
  contact:
    email: info@emlakiq.com
    url: https://emlakiq.com
  license:
    name: Proprietary
    url: https://emlakiq.com/kullanim-sartlari/

servers:
  - url: https://api.emlakiq.com/v1
    description: Production

security:
  - bearerAuth: []

paths:
  /resolve:
    post:
      summary: Gayrimenkul kimlik çözümleme
      description: Ham adres, ada/parsel veya koordinatı EmlakIQ kanonik kimliğine çözer.
      operationId: resolveProperty
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResolveRequest"
            example:
              raw_input: "Bağdat Caddesi No:412 Kadıköy/İstanbul"
              input_type: address
      responses:
        "200":
          description: Çözümleme başarılı
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResolveResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /dossier/{emlakiq_id}:
    get:
      summary: Varlık dosyası getir
      description: |
        EmlakIQ kimliği için tam kanıt dosyasını döndürür. Dossier; kimlik,
        imar, yapı, risk bağlamı, piyasa bağlamı, eksik alanlar ve kaynak
        manifest referansları içerir.
      operationId: getDossier
      parameters:
        - name: emlakiq_id
          in: path
          required: true
          schema:
            type: string
            pattern: "^tr_[0-9]{2}_[a-z0-9_]+$"
          example: tr_34_kadikoy_bagdat_0412
        - name: fields
          in: query
          description: Döndürülecek alan grupları (virgülle ayrılmış)
          schema:
            type: string
            example: "identity,zoning,risk_context"
      responses:
        "200":
          description: Dossier döndürüldü
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Dossier"
        "404":
          $ref: "#/components/responses/NotFound"

  /coverage:
    get:
      summary: Kapsam durumu sorgula
      description: Belirtilen ilçe ve alan türü için güncel kapsam durumunu döndürür.
      operationId: getCoverage
      parameters:
        - name: district_code
          in: query
          schema:
            type: string
          example: "34_kadikoy"
        - name: field_type
          in: query
          schema:
            type: string
            enum: [identity, zoning, building, risk, market, macro]
      responses:
        "200":
          description: Kapsam durumu
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CoverageStatus"

  /batch/resolve:
    post:
      summary: Toplu kimlik çözümleme
      description: 100'e kadar kaydı tek seferde çözer. EmlakIQ 100 pilot denetimi için kullanılır.
      operationId: batchResolve
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BatchResolveRequest"
      responses:
        "202":
          description: Batch kabul edildi
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchStatus"
        "400":
          $ref: "#/components/responses/BadRequest"

  /batch/{batch_id}:
    get:
      summary: Batch sonuçlarını getir
      operationId: getBatchResults
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Batch tamamlandı
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchResult"
        "202":
          description: Batch hâlâ işleniyor
        "404":
          $ref: "#/components/responses/NotFound"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    ResolveRequest:
      type: object
      required: [raw_input]
      properties:
        raw_input:
          type: string
          description: Ham adres, ada/parsel numarası veya koordinat
        input_type:
          type: string
          enum: [address, parcel_id, coordinate, project_name]
          default: address
        city_hint:
          type: string
          description: Opsiyonel şehir ipucu — çözümleme doğruluğunu artırır

    ResolveResponse:
      type: object
      properties:
        emlakiq_id:
          type: string
          example: "tr_34_kadikoy_bagdat_0412"
        identity_status:
          type: string
          enum: [exact_match, bounded_match, unresolved]
        confidence:
          $ref: "#/components/schemas/Confidence"
        resolved_scope:
          type: string
          enum: [parcel, building, unit, project]

    Dossier:
      type: object
      properties:
        emlakiq_id:
          type: string
        resolved_scope:
          type: string
          enum: [parcel, building, unit, project]
        identity_status:
          type: string
          enum: [exact_match, bounded_match, unresolved]
        confidence:
          $ref: "#/components/schemas/Confidence"
        identity:
          $ref: "#/components/schemas/Identity"
        zoning:
          $ref: "#/components/schemas/Zoning"
        risk_context:
          $ref: "#/components/schemas/RiskContext"
        market_context:
          $ref: "#/components/schemas/MarketContext"
        missing_fields:
          type: array
          items:
            type: string
        provenance_refs:
          type: array
          items:
            type: string
        snapshot_id:
          type: string

    Confidence:
      type: object
      properties:
        score:
          type: number
          format: float
          minimum: 0
          maximum: 1
        code:
          type: string
          enum: [exact, bounded, inferred, low]

    Identity:
      type: object
      properties:
        canonical_address:
          type: string
        district:
          type: string
        province:
          type: string
        parcel_id:
          type: string
        building_id:
          type: string

    Zoning:
      type: object
      properties:
        status:
          type: string
          enum: [known, partial, unknown]
        zone_type:
          type: string
        emsal:
          type: number
        floor_limit:
          type: integer
        source:
          type: string
        freshness:
          type: string
          format: date

    RiskContext:
      type: object
      properties:
        seismic_zone:
          type: string
        soil_class:
          type: string
          enum: [ZA, ZB, ZC, ZD, ZE]
        liquefaction_risk:
          type: string
          enum: [low, moderate, high, unknown]
        source:
          type: string

    MarketContext:
      type: object
      properties:
        grain:
          type: string
          enum: [district_month, neighborhood_quarter]
        listing_velocity_index:
          type: number
        supply_pipeline_units:
          type: integer
        reference_period:
          type: string

    CoverageStatus:
      type: object
      properties:
        district_code:
          type: string
        field_type:
          type: string
        status:
          type: string
          enum: [supported, partial, unsupported, stale_warning, unknown]
        freshness_days:
          type: integer
        note:
          type: string

    BatchResolveRequest:
      type: object
      required: [records]
      properties:
        records:
          type: array
          maxItems: 100
          items:
            type: object
            required: [property_ref, raw_input]
            properties:
              property_ref:
                type: string
              raw_input:
                type: string
              input_type:
                type: string
                enum: [address, parcel_id, coordinate]

    BatchStatus:
      type: object
      properties:
        batch_id:
          type: string
        status:
          type: string
          enum: [accepted, processing, complete, failed]
        submitted_at:
          type: string
          format: date-time

    BatchResult:
      type: object
      properties:
        batch_id:
          type: string
        total_submitted:
          type: integer
        resolved:
          type: integer
        partial:
          type: integer
        unresolved:
          type: integer
        resolution_rate:
          type: number
        results:
          type: array
          items:
            type: object

    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        field:
          type: string

  responses:
    BadRequest:
      description: Geçersiz istek
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: Kimlik doğrulama başarısız
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: Kaynak bulunamadı
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    UnprocessableEntity:
      description: İşlenemeyen varlık
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"