> ## Documentation Index
> Fetch the complete documentation index at: https://docs-zns.adflex.vn/llms.txt
> Use this file to discover all available pages before exploring further.

# Liệt kê và lọc tin

> Tin của workspace, mới nhất trước.

Scope: `messages:read`



## OpenAPI

````yaml https://business.adflex.vn/openapi.json get /api/v1/messages
openapi: 3.1.0
info:
  title: AdFlex ZNS API
  version: 1.0.0
  description: >-
    API gửi tin Zalo ZNS của AdFlex.


    API vận hành ở chế độ production, không có môi trường sandbox. Mỗi request
    thành công tạo một tin thật và trừ phí theo giá template.
  contact:
    name: AdFlex for Business
    url: https://business.adflex.vn
servers:
  - url: https://business.adflex.vn
    description: Production
security:
  - bearerAuth: []
  - apiKeyAuth: []
tags:
  - name: Template
    description: Khám phá template và OA khả dụng
  - name: Gửi tin
    description: Gửi một tin, gửi lô, gửi mã hoá đầu-cuối
  - name: Tra cứu
    description: Trạng thái tin và huỷ tin chưa gửi
paths:
  /api/v1/messages:
    get:
      tags:
        - Tra cứu
      summary: Liệt kê và lọc tin
      description: |-
        Tin của workspace, mới nhất trước.

        Scope: `messages:read`
      operationId: listMessages
      parameters:
        - name: tracking_id
          in: query
          schema:
            type: string
          description: Khớp chính xác mã đối soát của bạn
        - name: phone
          in: query
          schema:
            type: string
          description: Khớp chính xác số đã lưu. Không tìm được tin RSA.
        - name: status
          in: query
          schema:
            type: string
            enum:
              - queued
              - sending
              - sent
              - delivered
              - failed
        - name: from
          in: query
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 200
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Danh sách tin
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
                  limit:
                    type: integer
                  offset:
                    type: integer
                  count:
                    type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    Message:
      type: object
      properties:
        msg_id:
          type: string
          example: m_a1b2c3d4e5f6g7h8
        tracking_id:
          type: string
          example: otp-login-8842
          description: >-
            Mã đối soát do hệ thống của bạn định nghĩa. Không truyền thì AdFlex
            dùng msg_id.


            Tối đa 48 ký tự; chỉ chấp nhận chữ, số, dấu chấm, gạch ngang, gạch
            dưới. Vi phạm trả lỗi 400.
          maxLength: 48
          pattern: ^[A-Za-z0-9._-]+$
        status:
          type: string
          enum:
            - queued
            - sending
            - sent
            - delivered
            - failed
        phone:
          type:
            - string
            - 'null'
          description: null với tin gửi qua đường RSA
        carrier:
          type:
            - string
            - 'null'
          description: null với tin gửi qua đường RSA
        source:
          type: string
          example: api
        template_id:
          type:
            - string
            - 'null'
        oa_id:
          type:
            - string
            - 'null'
        zalo_msg_id:
          type:
            - string
            - 'null'
        error_code:
          type:
            - integer
            - 'null'
          example: null
        error_message:
          type:
            - string
            - 'null'
        error_reason:
          type:
            - string
            - 'null'
          description: Diễn giải tiếng Việt, chỉ có khi status=failed
        scheduled_at:
          type:
            - string
            - 'null'
          format: date-time
        sent_at:
          type:
            - string
            - 'null'
          format: date-time
        delivered_at:
          type:
            - string
            - 'null'
          format: date-time
        failed_at:
          type:
            - string
            - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              example: 401
            message:
              type: string
              example: API key không hợp lệ hoặc đã bị thu hồi
  responses:
    BadRequest:
      description: Body sai hoặc thiếu trường bắt buộc
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Thiếu API key, key sai hoặc đã bị thu hồi
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Key thiếu scope, hoặc workspace đang tạm dừng
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer ak_live_…'
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Cách thay thế cho Bearer. Dùng một trong hai là đủ.

````