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

# Xác minh danh tính Zalo

> Mini App gửi Zalo access token tới backend để nhận token phiên Taho.

Không gửi số điện thoại trong body này. Kết quả xác minh hiện có `verifiedPhone` rỗng. Xem [cấu hình môi trường](https://docs.taho.com.vn/engineering/environment-setup.md) cho các biến verifier.

Endpoint có `OPTIONS` trả 204. Header CORS chỉ được thêm cho origin Zalo được source cho phép; không suy rằng mọi frontend ở origin khác đều được phép gọi từ trình duyệt.


## OpenAPI

````yaml openapi.json POST /api/resident/auth/zalo
openapi: 3.0.3
info:
  title: 'Taho: Mini App và AI'
  version: source-review-2026-10-07
  description: >-
    Đặc tả biên soạn trong docs từ handler và service hiện tại. Không phải
    endpoint Swagger do application phục vụ; không xác nhận kết nối provider
    hoặc UAT.
servers: []
security: []
tags:
  - name: Mini App
  - name: Admin Mini App
  - name: AI
paths:
  /api/resident/auth/zalo:
    post:
      tags:
        - Mini App
      summary: Xác minh danh tính Zalo
      description: >-
        Gửi Zalo access token tới backend; backend gọi verifier rồi ký token
        phiên Taho. Không xin quyền số điện thoại; verifiedPhone hiện rỗng.
      operationId: authenticateResident
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                accessToken:
                  type: string
                  minLength: 1
                  maxLength: 4096
                  description: Access token từ Zalo SDK; không công bố token thật.
              required:
                - accessToken
              additionalProperties: true
      responses:
        '200':
          description: Nhận token phiên Taho.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      token:
                        type: string
                      expiresIn:
                        type: integer
                        enum:
                          - 43200
                        description: Thời hạn theo source, tính bằng giây.
                    required:
                      - token
                      - expiresIn
                    additionalProperties: true
                required:
                  - success
                  - data
                additionalProperties: true
        '400':
          description: invalid-json hoặc invalid-zalo-proof cho đầu vào không hợp lệ.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: invalid-zalo-proof khi verifier từ chối danh tính.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: resident-auth-failed cho lỗi ngoài nhóm nghiệp vụ.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: zalo-unavailable khi gọi verifier thất bại.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: zalo-not-configured hoặc zalo-verifier-not-configured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security: []
components:
  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details: {}
          required:
            - code
            - message
          additionalProperties: true
      required:
        - success
        - error
      additionalProperties: true

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.