多语言招聘网站API接口文档

geluli@qq.com (geluli) — Thu, 24 Sep 2026 08:45:57 +0800

多语言招聘网站API接口文档

1. 接口设计概述

1.1 多语言支持机制

1.1.1 语言指定方式

方式	示例	优先级
URL参数	`/api/jobs?lang=en`	最高
HTTP头	`Accept-Language: zh-CN`	中等
用户偏好	登录用户设置的默认语言	低
系统默认	配置的默认语言	最低

1.1.2 多语言数据返回格式

        
        
        
    
{
  "success": true,
  "data": {
    "id": 1,
    "title": "Software Engineer",
    "description": "We are looking for a talented software engineer...",
    // 其他字段
  },
  "i18n": {
    "messages": {
      "common.success": "操作成功",
      "job.apply.success": "申请提交成功"
    }
  }
}

1.2 认证与授权

1.2.1 JWT认证

登录成功后返回JWT token
所有需要认证的接口需在请求头中携带 Authorization: Bearer
token有效期：24小时

1.2.2 角色权限

角色	权限范围
`candidate`	应聘者功能
`company_admin`	企业管理功能
`super_admin`	系统管理功能

2. 公共接口

2.1 获取支持的语言列表

GET /api/languages

响应示例

        
        
        
    
{
  "success": true,
  "data": [
    {
      "id": 1,
      "code": "en",
      "name": "English",
      "is_default": true
    },
    {
      "id": 2,
      "code": "zh-CN",
      "name": "简体中文",
      "is_default": false
    }
  ]
}

2.2 获取国家列表

GET /api/countries

响应示例

        
        
        
    
{
  "success": true,
  "data": [
    {
      "id": 1,
      "code": "CN",
      "name": "China",
      "currency": "CNY"
    },
    {
      "id": 2,
      "code": "US",
      "name": "United States",
      "currency": "USD"
    }
  ]
}

2.3 获取地区列表

GET /api/regions?country_id=1

响应示例

        
        
        
    
{
  "success": true,
  "data": [
    {
      "id": 1,
      "country_id": 1,
      "name": "Beijing"
    },
    {
      "id": 2,
      "country_id": 1,
      "name": "Shanghai"
    }
  ]
}

3. 用户认证接口

3.1 用户注册

POST /api/auth/register

请求体

        
        
        
    
{
  "email": "user@example.com",
  "password": "password123",
  "role": "candidate",
  "language_id": 1
}

响应示例

        
        
        
    
{
  "success": true,
  "data": {
    "id": 1,
    "email": "user@example.com",
    "role": "candidate",
    "language_id": 1
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

3.2 用户登录

POST /api/auth/login

请求体

        
{
  "email": "user@example.com",
  "password": "password123"
}

响应示例

        
        
        
    
{
  "success": true,
  "data": {
    "id": 1,
    "email": "user@example.com",
    "role": "candidate",
    "language_id": 1
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "i18n": {
    "messages": {
      "auth.login.success": "登录成功"
    }
  }
}

3.3 忘记密码

POST /api/auth/forgot-password

请求体

        
{
  "email": "user@example.com"
}

4. 应聘者接口

4.1 简历管理

4.1.1 获取简历列表

GET /api/candidates/resumes

响应示例

        
        
        
    
{
  "success": true,
  "data": [
    {
      "id": 1,
      "file_name": "resume.pdf",
      "file_type": "pdf",
      "size": 1024000,
      "is_default": true,
      "status": "approved"
    }
  ]
}

4.1.2 上传简历

        
POST /api/candidates/resumes/upload
Content-Type: multipart/form-data

请求体

file: 简历文件
is_default: 是否设为默认简历

4.1.3 设置默认简历

PUT /api/candidates/resumes/{id}/default

4.2 职位搜索

GET /api/jobs

查询参数

参数	类型	描述
keyword	string	搜索关键词
job_type	string	职位类型（full_time, part_time）
job_category	string	职位类别（tech, marketing）
country_id	integer	国家ID
region_id	integer	地区ID
salary_min	number	最低工资
salary_max	number	最高工资
experience_min	integer	最低经验（年）
page	integer	页码
page_size	integer	每页数量
lang	string	语言代码

响应示例

        
        
        
    
{
  "success": true,
  "data": {
    "jobs": [
      {
        "id": 1,
        "title": "Software Engineer",
        "company": {
          "id": 1,
          "name": "Tech Company",
          "logo": "https://example.com/logo.png"
        },
        "job_type": "full_time",
        "job_category": "tech",
        "location": "Beijing, China",
        "salary": "15K-25K CNY",
        "experience": "3-5 years"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 10,
      "total": 100,
      "total_pages": 10
    }
  }
}

4.3 职位详情

GET /api/jobs/{id}

响应示例

        
        
        
    
{
  "success": true,
  "data": {
    "id": 1,
    "title": "Software Engineer",
    "description": "We are looking for a talented software engineer...",
    "requirements": "- Bachelor's degree in Computer Science\n- 3+ years of experience...",
    "responsibilities": "- Develop and maintain web applications\n- Collaborate with cross-functional teams...",
    "benefits": "- Competitive salary\n- Flexible working hours...",
    "company": {
      "id": 1,
      "name": "Tech Company",
      "description": "A leading tech company specializing in...",
      "website": "https://example.com",
      "logo": "https://example.com/logo.png"
    },
    "job_type": "full_time",
    "job_category": "tech",
    "country": "China",
    "region": "Beijing",
    "salary_min": 15000,
    "salary_max": 25000,
    "currency": "CNY",
    "experience_min": 3,
    "experience_max": 5,
    "education_level": "bachelor"
  }
}

4.4 投递申请

POST /api/jobs/{id}/apply

请求体

        
{
  "resume_id": 1,
  "cover_letter": "I am very interested in this position..."
}

4.5 我的申请

GET /api/candidates/applications

查询参数

status: 申请状态（pending, reviewed, accepted, rejected）
page: 页码
page_size: 每页数量

4.6 我的收藏

GET /api/candidates/favorites

4.6.1 添加收藏

POST /api/candidates/favorites

请求体

        
{
  "entity_type": "job",
  "entity_id": 1
}

4.6.2 取消收藏

DELETE /api/candidates/favorites/{id}

5. 企业接口

5.1 企业信息管理

5.1.1 获取企业信息

GET /api/companies/me

5.1.2 更新企业信息

PUT /api/companies/me

请求体

        
        
        
    
{
  "name": "Tech Company",
  "description": "A leading tech company...",
  "website": "https://example.com",
  "country_id": 1,
  "region_id": 1,
  "logo": "https://example.com/logo.png"
}

5.2 职位管理

5.2.1 发布职位

POST /api/companies/jobs

请求体

        
        
        
    
{
  "title": "Software Engineer",
  "description": "We are looking for a talented software engineer...",
  "requirements": "- Bachelor's degree in Computer Science...",
  "responsibilities": "- Develop and maintain web applications...",
  "benefits": "- Competitive salary...",
  "job_type_id": 1,
  "job_category_id": 1,
  "country_id": 1,
  "region_id": 1,
  "salary_min": 15000,
  "salary_max": 25000,
  "currency": "CNY",
  "experience_min": 3,
  "experience_max": 5,
  "education_level": "bachelor"
}

5.2.2 获取企业职位列表

GET /api/companies/jobs

查询参数

status: 职位状态（active, inactive）
page: 页码
page_size: 每页数量

5.2.3 更新职位

PUT /api/companies/jobs/{id}

5.2.4 下架职位

PUT /api/companies/jobs/{id}/deactivate

5.3 简历管理

5.3.1 获取收到的简历

GET /api/companies/applications

查询参数

job_id: 职位ID
status: 申请状态
page: 页码
page_size: 每页数量

5.3.2 查看简历详情

GET /api/companies/applications/{id}/resume

5.3.3 更新申请状态

PUT /api/companies/applications/{id}/status

请求体

        
{
  "status": "reviewed",
  "notes": "Good candidate, schedule an interview"
}

5.4 面试管理

5.4.1 发起面试

POST /api/companies/interviews

请求体

        
        
        
    
{
  "application_id": 1,
  "interview_date": "2024-01-15T14:00:00Z",
  "interview_type": "online",
  "location": "https://meeting.example.com/123",
  "notes": "Please prepare for technical interview"
}

5.4.2 获取面试列表

GET /api/companies/interviews

6. 多语言内容管理接口

6.1 动态内容翻译

6.1.1 获取实体翻译

GET /api/i18n/translations/{entity_type}/{entity_id}

6.1.2 添加/更新翻译

POST /api/i18n/translations

请求体

        
        
        
    
{
  "language_id": 2,
  "entity_type": "job",
  "entity_id": 1,
  "field_name": "title",
  "translation": "软件工程师"
}

6.2 静态内容翻译

6.2.1 获取静态内容翻译

GET /api/i18n/content/{content_key}

6.2.2 添加/更新静态内容翻译

POST /api/i18n/content

请求体

        
{
  "language_id": 2,
  "content_key": "home.title",
  "content_value": "欢迎来到招聘网站"
}

7. 管理员接口

7.1 语言管理

7.1.1 添加语言

POST /api/admin/languages

请求体

        
{
  "code": "fr",
  "name": "Français",
  "is_default": false
}

7.1.2 设置默认语言

PUT /api/admin/languages/{id}/default

7.2 国家/地区管理

7.2.1 添加国家

POST /api/admin/countries

请求体

        
{
  "code": "JP",
  "name": "Japan",
  "currency": "JPY"
}

7.2.2 添加地区

POST /api/admin/regions

请求体

        
{
  "country_id": 3,
  "name": "Tokyo"
}

7.3 用户管理

7.3.1 获取用户列表

GET /api/admin/users

查询参数

role: 用户角色
status: 用户状态
page: 页码
page_size: 每页数量

7.3.2 更新用户状态

PUT /api/admin/users/{id}/status

请求体

        
{
  "status": "active"
}

8. WebSocket实时通知接口

8.1 连接WebSocket

ws://example.com/ws?token={jwt_token}

8.2 通知类型

类型	描述
application_status_change	申请状态变更
interview_scheduled	面试安排
new_application	新的职位申请
message_received	收到新消息

8.3 通知数据格式

        
        
        
    
{
  "type": "application_status_change",
  "data": {
    "application_id": 1,
    "job_title": "Software Engineer",
    "status": "reviewed",
    "notes": "Good candidate"
  },
  "i18n": {
    "message": "您的申请状态已更新为：已查看"
  }
}

9. 错误码规范

错误码	描述	HTTP状态码
20000	操作成功	200
40000	请求参数错误	400
40100	未授权	401
40300	权限不足	403
40400	资源不存在	404
40900	资源冲突	409
50000	服务器内部错误	500
50001	数据库错误	500
50002	第三方服务错误	500

10. 示例请求响应

10.1 职位详情请求（中文）

        
GET /api/jobs/1?lang=zh-CN
Authorization: Bearer

10.2 职位详情响应（中文）

        
        
        
    
{
  "success": true,
  "data": {
    "id": 1,
    "title": "软件工程师",
    "description": "我们正在寻找一位才华横溢的软件工程师...",
    "requirements": "- 计算机科学学士学位...",
    "responsibilities": "- 开发和维护Web应用...",
    "benefits": "- 有竞争力的薪资...",
    "company": {
      "id": 1,
      "name": "科技公司",
      "logo": "https://example.com/logo.png"
    },
    "job_type": "全职",
    "job_category": "技术",
    "location": "中国，北京",
    "salary": "15K-25K CNY",
    "experience": "3-5年"
  },
  "i18n": {
    "messages": {
      "job.detail.view": "查看职位详情",
      "job.apply": "立即申请",
      "job.favorite": "收藏职位"
    }
  }
}

11. API版本控制

API版本通过URL前缀控制，如 /api/v1/jobs
支持多版本并存，便于平滑升级
新版本API需保持向后兼容

12. 安全规范

HTTPS：所有API请求必须使用HTTPS
输入验证：所有请求参数必须严格验证
输出过滤：所有响应数据必须过滤敏感信息
速率限制：防止API滥用，每个IP或用户设置请求频率限制
SQL注入防护：使用参数化查询，防止SQL注入
XSS防护：对输出内容进行HTML转义
CSRF防护：对非GET请求进行CSRF验证

13. 性能优化

缓存策略：

接口文档 - 分类 - 我的技术博客

招聘平台 API 接口文档

招聘平台 API 接口文档

文档说明

文档版本

更新日志

多语言招聘网站API接口文档

多语言招聘网站API接口文档

1. 接口设计概述

1.1 多语言支持机制

1.1.1 语言指定方式

1.1.2 多语言数据返回格式

1.2 认证与授权

1.2.1 JWT认证

1.2.2 角色权限

2. 公共接口

2.1 获取支持的语言列表

响应示例

2.2 获取国家列表

响应示例

2.3 获取地区列表

响应示例

3. 用户认证接口

3.1 用户注册

请求体

响应示例

3.2 用户登录

请求体

响应示例

3.3 忘记密码

请求体

4. 应聘者接口

4.1 简历管理

4.1.1 获取简历列表

响应示例

4.1.2 上传简历

请求体

4.1.3 设置默认简历

4.2 职位搜索

查询参数

响应示例

4.3 职位详情

响应示例

4.4 投递申请

请求体

4.5 我的申请

查询参数

4.6 我的收藏

4.6.1 添加收藏

请求体

4.6.2 取消收藏

5. 企业接口

5.1 企业信息管理

5.1.1 获取企业信息

5.1.2 更新企业信息

请求体

5.2 职位管理

5.2.1 发布职位

请求体

5.2.2 获取企业职位列表

查询参数

5.2.3 更新职位

5.2.4 下架职位

5.3 简历管理

5.3.1 获取收到的简历

查询参数

5.3.2 查看简历详情

5.3.3 更新申请状态

请求体

5.4 面试管理

5.4.1 发起面试

请求体

5.4.2 获取面试列表

6. 多语言内容管理接口

6.1 动态内容翻译

6.1.1 获取实体翻译

6.1.2 添加/更新翻译

请求体

6.2 静态内容翻译

6.2.1 获取静态内容翻译