# Truy xuất dữ liệu chuyển đổi

> Truy xuất dữ liệu chuyển đổi để phân tích hành động của người dùng và đo lường hiệu quả của các nỗ lực marketing theo thời gian.
>
> Giới hạn tốc độ: 2 yêu cầu mỗi giây.

## OpenAPI

```yaml
/api-specs/export-analytics-api.yaml post /api/v1/client-api/metrics/conversion/
openapi: 3.1.0
info:
  title: Adapty Export Analytics API
  version: 1.0.0
  description: |
    Adapty Export Analytics API cho phép bạn xuất dữ liệu phân tích sang định dạng CSV hoặc JSON,
    giúp bạn linh hoạt khám phá sâu hơn các chỉ số hiệu suất của ứng dụng, tùy chỉnh báo cáo
    và phân tích xu hướng theo thời gian. Với API này, bạn có thể dễ dàng truy xuất dữ liệu phân tích
    chi tiết, thuận tiện cho việc theo dõi, chia sẻ và tinh chỉnh thông tin dữ liệu khi cần.
servers:
  - url: https://api-admin.adapty.io
    description: Production server
security:
  - apikeyAuth: []
paths:
  /api/v1/client-api/metrics/conversion/:
    post:
      summary: Truy xuất dữ liệu chuyển đổi
      description: |-
        Truy xuất dữ liệu chuyển đổi để phân tích hành động của người dùng và đo lường hiệu quả của các nỗ lực marketing theo thời gian.

        Giới hạn tốc độ: 2 yêu cầu mỗi giây.
      operationId: retrieveConversionData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConversionDataRequest"
            examples:
              basic:
                summary: Yêu cầu dữ liệu chuyển đổi cơ bản
                value:
                  filters:
                    date:
                      - "2024-01-01"
                      - "2024-12-31"
                  from_period: 1
                  to_period: 6+
                  period_unit: month
                  date_type: purchase_date
                  segmentation: country
                  format: json
      responses:
        "200":
          description: Đã truy xuất dữ liệu chuyển đổi thành công
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversionDataResponse"
              example:
                data: []
                value: 0
                value_from: 0
                value_to: 0
                compare_value_from: null
                compare_value_to: null
                title: Conversion rate from Paid to more than 6 months
                type: multi
                default_aggregation: sum
                description: If Х - the number of the 1st payments taken during the selected date, and Y - the amount of the renewals that happened after the 6 months since the selected date from those 1st payments, then Conversion = (Y / X) * 100%. For example, we had 100 1st subscriptions of various products on the 1st of January and among them 20 renewed on the 1st week of July (the 25th payment). On the 8th of July, we open the chart and see the conversion of the 1st of January = (20 / 100) * 100% = 20%. Then 30 more subscribers of the 1st of January renewed by the start of August (the 8th payment). We open the chart on the 1st of August and see that the conversion of the 1st of January = ((20+30) / 100) * 100% = 50%. This number shows which part of those who had their 1st payment on the 1st of January converted to the period > 6 months with any number of payments by the current moment.
                metric_name: from_paid_to_6_months_conversion
                is_json: true
                unit: percent
                recommended_period:
                  date_from: "2018-04-29"
                  date_to: "2024-12-31"
                  period_unit: month
            text/csv:
              schema:
                type: string
                description: Dữ liệu chuyển đổi ở định dạng CSV
        "400":
          description: Yêu cầu không hợp lệ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Không được phép
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedError"
        "429":
          description: Đã vượt quá giới hạn tốc độ. Tối đa 2 yêu cầu mỗi giây cho mỗi API key.
components:
  schemas:
    ConversionDataRequest:
      type: object
      required:
        - filters
        - from_period
        - to_period
      properties:
        filters:
          $ref: "#/components/schemas/MetricsFilters"
        from_period:
          oneOf:
            - type: string
            - type: "null"
          description: Trạng thái gói đăng ký ban đầu của người dùng trong quá trình chuyển đổi
        to_period:
          type: string
          description: Trạng thái gói đăng ký mới của người dùng sau khi chuyển đổi
        period_unit:
          type: string
          enum:
            - day
            - week
            - month
            - quarter
            - year
          description: Chỉ định khoảng thời gian để tổng hợp dữ liệu phân tích
          default: month
        date_type:
          type: string
          enum:
            - purchase_date
            - profile_install_date
          description: Chỉ định ngày nào sẽ được coi là ngày người dùng tham gia
          default: purchase_date
        segmentation:
          type: string
          description: Đặt cơ sở để phân khúc
        format:
          type: string
          enum:
            - json
            - csv
          description: Chỉ định định dạng tệp xuất
          default: json
    ConversionDataResponse:
      type: object
      description: Phản hồi chứa dữ liệu chuyển đổi hiển thị hành trình của người dùng giữa các trạng thái gói đăng ký
      properties:
        data:
          type: array
          description: Mảng các điểm dữ liệu chuyển đổi (có thể rỗng đối với các chỉ số tổng hợp)
          items:
            type: object
        value:
          type: number
          description: Giá trị tỷ lệ chuyển đổi
        value_from:
          type: integer
          description: Trạng thái gói đăng ký ban đầu cho quá trình chuyển đổi
        value_to:
          type: integer
          description: Trạng thái gói đăng ký mục tiêu cho quá trình chuyển đổi
        compare_value_from:
          type: number
          nullable: true
          description: Giá trị bắt đầu cho kỳ so sánh
        compare_value_to:
          type: number
          nullable: true
          description: Giá trị kết thúc cho kỳ so sánh
        title:
          type: string
          description: Tiêu đề hiển thị mô tả loại chuyển đổi
        type:
          type: string
          description: Loại chỉ số chuyển đổi
        default_aggregation:
          type: string
          description: Phương pháp tổng hợp mặc định cho chỉ số này
        description:
          type: string
          description: Giải thích chi tiết về cách tính tỷ lệ chuyển đổi
        metric_name:
          type: string
          description: Tên nội bộ của chỉ số chuyển đổi
        is_json:
          type: boolean
          description: Dữ liệu có ở định dạng JSON hay không
        unit:
          type: string
          description: Đơn vị đo lường (thường là 'percent' cho tỷ lệ chuyển đổi)
        recommended_period:
          type: object
          description: Khoảng ngày được đề xuất cho chỉ số chuyển đổi này
          properties:
            date_from:
              type: string
              description: Ngày bắt đầu của kỳ được đề xuất
            date_to:
              type: string
              description: Ngày kết thúc của kỳ được đề xuất
            period_unit:
              type: string
              description: Đơn vị kỳ được đề xuất
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              errors:
                type: array
                items:
                  type: string
        error_code:
          type: string
        status_code:
          type: integer
    UnauthorizedError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              errors:
                type: array
                items:
                  type: string
        error_code:
          type: string
        status_code:
          type: integer
    MetricsFilters:
      type: object
      required:
        - date
      properties:
        date:
          type: array
          items:
            type: string
          description: Nhập ngày hoặc khoảng thời gian bạn muốn truy xuất dữ liệu biểu đồ
        compare_date:
          type: array
          items:
            type: string
          description: Nhập ngày hoặc khoảng thời gian để so sánh
        store:
          type: array
          items:
            type: string
          description: Lọc theo cửa hàng ứng dụng nơi thực hiện giao dịch mua
        country:
          type: array
          items:
            type: string
          description: Lọc theo mã quốc gia 2 chữ cái nơi thực hiện giao dịch mua
        store_product_id:
          type: array
          items:
            type: string
          description: Mã định danh duy nhất của sản phẩm từ cửa hàng ứng dụng
        duration:
          type: array
          items:
            type: string
          description: Chỉ định thời hạn gói đăng ký
        attribution_source:
          type: array
          items:
            type: string
          description: Nguồn tích hợp cho attribution
        attribution_status:
          type: array
          items:
            type: string
          description: Cho biết attribution là organic hay non-organic
        attribution_channel:
          type: array
          items:
            type: string
          description: Kênh marketing dẫn đến giao dịch
        attribution_campaign:
          type: array
          items:
            type: string
          description: Chiến dịch marketing mang lại giao dịch
        attribution_adgroup:
          type: array
          items:
            type: string
          description: Nhóm quảng cáo attribution mang lại giao dịch
        attribution_adset:
          type: array
          items:
            type: string
          description: Bộ quảng cáo attribution dẫn đến giao dịch
        attribution_creative:
          type: array
          items:
            type: string
          description: Các yếu tố hình ảnh hoặc văn bản cụ thể trong quảng cáo hoặc chiến dịch được theo dõi để đo lường hiệu quả
        offer_category:
          type: array
          items:
            type: string
          description: Chỉ định các danh mục ưu đãi bạn muốn truy xuất dữ liệu
        offer_type:
          type: array
          items:
            type: string
          description: Chỉ định các loại ưu đãi bạn muốn truy xuất dữ liệu
        offer_id:
          type: array
          items:
            type: string
          description: Chỉ định các ưu đãi cụ thể bạn muốn truy xuất dữ liệu
  securitySchemes:
    apikeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Bạn cần xác thực các yêu cầu API bằng secret API key của mình trong header Authorization.
        Bạn có thể tìm thấy key này trong App Settings. Định dạng là `Api-Key {YOUR_SECRET_API_KEY}`,
        ví dụ: `Api-Key secret_live_...`.
```