openapi: 3.1.0
info:
  title: nestIP API
  description: |
    API Đánh giá Rủi ro IP & Chống Gian lận / IP Risk Scoring & Anti-Fraud API
    
    nestIP giúp bạn phát hiện VPN, Proxy, Tor, Datacenter và các IP rủi ro khác.
    Được tối ưu đặc biệt cho thị trường Việt Nam.
    
    ## Xác thực / Authentication
    
    Tất cả các endpoint API đều yêu cầu API key. Gửi key trong header:
    
    ```
    X-API-Key: your-api-key-here
    ```
    
    ## Rate Limiting
    
    - Giới hạn theo phút (tùy thuộc vào gói)
    - Headers trả về: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
    
    ## Lỗi / Errors
    
    API trả về JSON với cấu trúc:
    ```json
    {
      "error": "error_code",
      "message": "Human readable message"
    }
    ```
    
  version: 1.0.0
  contact:
    email: support@nestip.net
  license:
    name: Proprietary
    
servers:
  - url: https://api.nestip.net
    description: Production
  - url: http://localhost:8080
    description: Development

tags:
  - name: IP Lookup
    description: Tra cứu và đánh giá rủi ro IP
  - name: Authentication
    description: Xác thực người dùng
  - name: Account
    description: Quản lý tài khoản

paths:
  /v1/ip/{ip}:
    get:
      tags:
        - IP Lookup
      summary: Tra cứu một IP
      description: |
        Trả về điểm rủi ro và thông tin chi tiết cho một địa chỉ IP.
        Hỗ trợ cả IPv4 và IPv6.
      operationId: lookupIP
      security:
        - ApiKeyAuth: []
      parameters:
        - name: ip
          in: path
          required: true
          description: Địa chỉ IP cần tra cứu
          schema:
            type: string
          examples:
            ipv4:
              value: "8.8.8.8"
              summary: Google DNS IPv4
            ipv6:
              value: "2001:4860:4860::8888"
              summary: Google DNS IPv6
            vietnamese:
              value: "113.160.15.1"
              summary: VNPT IP
      responses:
        '200':
          description: Thành công
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IPLookupResult'
              examples:
                cleanIP:
                  summary: IP sạch
                  value:
                    ip: "113.160.15.1"
                    score: 5
                    risk_level: "minimal"
                    is_vpn: false
                    is_proxy: false
                    is_residential_proxy_suspect: false
                    is_datacenter: false
                    is_tor: false
                    is_blacklisted: false
                    is_bogon: false
                    asn: 45899
                    asn_org: "VNPT"
                    isp: "VNPT"
                    connection_type: "residential"
                    country: "Vietnam"
                    country_code: "VN"
                    region: "Ho Chi Minh"
                    city: "Ho Chi Minh City"
                    reasons:
                      - "No risk factors detected"
                torExit:
                  summary: Tor exit node
                  value:
                    ip: "185.220.101.1"
                    score: 85
                    risk_level: "critical"
                    is_tor: true
                    is_blacklisted: true
                    reasons:
                      - "IP is a known Tor exit node"
                      - "IP is on abuse/spam blacklist"
        '400':
          description: IP không hợp lệ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: API key không hợp lệ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Vượt quá rate limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /v1/ip/batch:
    post:
      tags:
        - IP Lookup
      summary: Tra cứu nhiều IP
      description: |
        Tra cứu tối đa 100 IP trong một request.
        Mỗi IP được tính là một lượt gọi API.
      operationId: batchLookup
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
            example:
              ips:
                - "8.8.8.8"
                - "1.1.1.1"
                - "113.160.15.1"
      responses:
        '200':
          description: Thành công
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          description: Request không hợp lệ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: API key không hợp lệ
        '429':
          description: Vượt quá rate limit

  /health:
    get:
      tags:
        - System
      summary: Health check
      description: Kiểm tra trạng thái hệ thống
      responses:
        '200':
          description: Hệ thống hoạt động bình thường
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "healthy"
                  app:
                    type: string
                    example: "nestIP"
                  version:
                    type: string
                    example: "1.0.0"

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key được cấp từ dashboard

  schemas:
    IPLookupResult:
      type: object
      properties:
        ip:
          type: string
          description: Địa chỉ IP đã tra cứu
          example: "8.8.8.8"
        score:
          type: integer
          minimum: 0
          maximum: 100
          description: Điểm rủi ro (0-100, càng cao càng rủi ro)
          example: 15
        risk_level:
          type: string
          enum: [minimal, low, medium, high, critical]
          description: Mức độ rủi ro
          example: "low"
        is_vpn:
          type: boolean
          description: IP thuộc VPN provider
        is_proxy:
          type: boolean
          description: IP là proxy server
        is_residential_proxy_suspect:
          type: boolean
          description: Nghi ngờ residential proxy
        is_datacenter:
          type: boolean
          description: IP thuộc datacenter/hosting
        is_tor:
          type: boolean
          description: IP là Tor exit node
        is_blacklisted:
          type: boolean
          description: IP có trong blacklist
        is_bogon:
          type: boolean
          description: IP là bogon (private/reserved)
        asn:
          type: integer
          description: Autonomous System Number
          example: 15169
        asn_org:
          type: string
          description: Tên tổ chức ASN
          example: "Google LLC"
        isp:
          type: string
          description: Nhà cung cấp dịch vụ Internet
          example: "Google LLC"
        connection_type:
          type: string
          enum: [residential, mobile, datacenter, corporate, education, unknown]
          description: Loại kết nối
          example: "datacenter"
        country:
          type: string
          description: Tên quốc gia
          example: "United States"
        country_code:
          type: string
          description: Mã quốc gia ISO 3166-1 alpha-2
          example: "US"
        region:
          type: string
          description: Vùng/Tỉnh
          example: "California"
        city:
          type: string
          description: Thành phố
          example: "Mountain View"
        reasons:
          type: array
          description: Từng tín hiệu cộng điểm, kèm trọng số và nguồn.
          items:
            type: object
            required: [signal, weight, source, text]
            properties:
              signal:
                type: string
                examples: ["tor"]
              weight:
                type: integer
                examples: [70]
              source:
                type: string
                examples: ["tor_exit_list"]
              text:
                type: string
                examples: ["IP is a known Tor exit node"]
        data_freshness:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              status:
                type: string
              updated_at:
                type: string
        cached_at:
          type: string
          format: date-time
          description: Thời điểm cache (nếu từ cache)
          
    BatchRequest:
      type: object
      required:
        - ips
      properties:
        ips:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 100
          description: Danh sách IP cần tra cứu (tối đa 100)
          example:
            - "8.8.8.8"
            - "1.1.1.1"
            
    BatchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/IPLookupResult'
        count:
          type: integer
          description: Số lượng kết quả
          example: 2
          
    Error:
      type: object
      properties:
        error:
          type: string
          description: Mã lỗi
          example: "invalid_ip"
        message:
          type: string
          description: Mô tả lỗi
          example: "Invalid IP address format"