tyapi-server/docs/发票API接口文档.md

发票API接口文档

概述

本文档描述了发票管理相关的API接口，包括用户申请开票和管理员处理开票申请的功能。

基础信息

• Base URL: http://localhost:8080
• 认证方式: Bearer Token (JWT)
• Content-Type: application/json

用户接口

1. 申请开票

接口地址: POST /api/v1/invoices/apply

请求参数:

{
  "invoice_type": "general",  // 发票类型: general(普票) | special(专票)
  "amount": "1000.00",        // 开票金额
  "invoice_info": {
    "company_name": "海南省学宇思网络科技有限公司",
    "taxpayer_id": "91460108MADNY3F43W",
    "bank_name": "中国银行海口分行",           // 专票必填
    "bank_account": "1234567890123456",      // 专票必填
    "company_address": "海南省海口市",        // 专票必填
    "company_phone": "0898-12345678",        // 专票必填
    "receiving_email": "ilirnax@gmail.com"
  }
}

响应示例:

{
  "success": true,
  "message": "申请开票成功",
  "data": {
    "id": "uuid",
    "user_id": "user_uuid",
    "invoice_type": "general",
    "amount": "1000.00",
    "status": "pending",
    "invoice_info": {
      "company_name": "海南省学宇思网络科技有限公司",
      "taxpayer_id": "91460108MADNY3F43W",
      "receiving_email": "ilirnax@gmail.com"
    },
    "created_at": "2024-01-01T12:00:00Z"
  }
}

2. 获取用户发票信息

接口地址: GET /api/v1/invoices/info

响应示例:

{
  "success": true,
  "message": "获取发票信息成功",
  "data": {
    "company_name": "海南省学宇思网络科技有限公司",
    "taxpayer_id": "91460108MADNY3F43W",
    "bank_name": "",
    "bank_account": "",
    "company_address": "",
    "company_phone": "",
    "receiving_email": "ilirnax@gmail.com",
    "is_complete": false,
    "missing_fields": ["基本开户银行", "基本开户账号", "企业注册地址", "企业注册电话"]
  }
}

3. 更新用户发票信息

接口地址: PUT /api/v1/invoices/info

请求参数:

{
  "company_name": "海南省学宇思网络科技有限公司",
  "taxpayer_id": "91460108MADNY3F43W",
  "bank_name": "中国银行海口分行",
  "bank_account": "1234567890123456",
  "company_address": "海南省海口市",
  "company_phone": "0898-12345678",
  "receiving_email": "ilirnax@gmail.com"
}

4. 获取用户开票记录

接口地址: GET /api/v1/invoices/records?page=1&page_size=10&status=completed

查询参数:

• page: 页码 (默认: 1)
• page_size: 每页数量 (默认: 10, 最大: 100)
• status: 状态筛选 (可选: pending, completed, rejected)

响应示例:

{
  "success": true,
  "message": "获取开票记录成功",
  "data": {
    "records": [
      {
        "id": "uuid",
        "user_id": "user_uuid",
        "invoice_type": "general",
        "amount": "1000.00",
        "status": "completed",
        "company_name": "海南省学宇思网络科技有限公司",
        "file_name": "invoice_20240101.pdf",
        "file_size": 1024000,
        "file_url": "https://example.com/invoice.pdf",
        "processed_at": "2024-01-01T14:00:00Z",
        "created_at": "2024-01-01T12:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10,
    "total_pages": 1
  }
}

5. 获取可开票金额

接口地址: GET /api/v1/invoices/available-amount

响应示例:

{
  "success": true,
  "message": "获取可开票金额成功",
  "data": {
    "available_amount": "5000.00",
    "total_recharged": "10000.00",
    "total_gifted": "1000.00",
    "total_invoiced": "4000.00"
  }
}

6. 下载发票文件

接口地址: GET /api/v1/invoices/{application_id}/download

响应示例:

{
  "success": true,
  "message": "获取下载信息成功",
  "data": {
    "file_id": "file_uuid",
    "file_name": "invoice_20240101.pdf",
    "file_size": 1024000,
    "file_url": "https://example.com/invoice.pdf"
  }
}

管理员接口

1. 获取待处理的发票申请列表

接口地址: GET /api/v1/admin/invoices/pending?page=1&page_size=10

响应示例:

{
  "success": true,
  "message": "获取待处理申请列表成功",
  "data": {
    "applications": [
      {
        "id": "uuid",
        "user_id": "user_uuid",
        "invoice_type": "general",
        "amount": "1000.00",
        "status": "pending",
        "company_name": "海南省学宇思网络科技有限公司",
        "receiving_email": "ilirnax@gmail.com",
        "created_at": "2024-01-01T12:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10,
    "total_pages": 1
  }
}

2. 通过发票申请（上传发票）

接口地址: POST /api/v1/admin/invoices/{application_id}/approve

请求方式: multipart/form-data

请求参数:

• file: 发票文件 (PDF格式)
• admin_notes: 管理员备注 (可选)

响应示例:

{
  "success": true,
  "message": "通过发票申请成功",
  "data": null
}

3. 拒绝发票申请

接口地址: POST /api/v1/admin/invoices/{application_id}/reject

请求参数:

{
  "reason": "发票信息不完整，请补充企业注册地址和电话"
}

响应示例:

{
  "success": true,
  "message": "拒绝发票申请成功",
  "data": null
}

错误码说明

状态码	说明
200	请求成功
400	请求参数错误
401	用户未登录或认证已过期
403	权限不足
404	资源不存在
500	服务器内部错误

业务规则

开票金额限制

• 用户只能申请充值金额（除去赠送）减去已开票金额
• 开票金额必须大于0

发票信息验证

• 普票: 至少需要公司名称、纳税人识别号、接收邮箱
• 专票: 需要完整的企业信息（包括银行信息、地址、电话）

状态流转

• pending (待处理) → completed (已完成) 或 rejected (已拒绝)

文件要求

• 发票文件格式：PDF
• 文件大小限制：10MB
• 文件命名：invoice_{application_id}.pdf

注意事项

1. 所有接口都需要JWT认证
2. 管理员接口需要管理员权限
3. 文件上传接口使用 multipart/form-data 格式
4. 金额字段使用字符串格式，精确到分
5. 时间字段使用ISO 8601格式