证件照回执API接口文档 - 社保/居住证/身份证回执办理

可立图 ClipImg 证件照回执自动化办理 API 服务

接口概述 #

本接口专为第三方开发者和企业用户设计，提供全流程的证件照回执自动化办理服务。通过对接本接口，您的应用可以快速具备为用户办理各类官方证件照回执（如身份证、居住证、驾驶证等）的能力。

系统底层对接了官方认证的检测机构，确保办理的回执真实有效，并能返回官方认证的图像号（Image Code）及回执单文件。

推荐接入流程：

调用 /types 获取目标回执类型的 required_fields、parameter_guide 和 processing_time。
按目标回执类型要求组装 custom_fields，至少满足 required_fields 中列出的字段。
调用 /submit 提交申请，拿到 application_no。
通过 /query 或 /batch_query 轮询状态，或配置 callback_url 接收完成通知。
在 status=completed 时读取 result_url、image_code 等结果字段。

核心功能：

全品类支持：支持身份证、居住证、社保卡、驾驶证、护照等多种证件类型的回执办理。
自动化流程：从提交照片、信息录入到获取回执，全流程自动化处理，无需人工干预。
状态实时追踪：提供详细的订单状态流转（待处理、处理中、已完成、失败），支持主动查询与回调通知。
模拟测试模式：提供模拟参数（simulate），方便开发者在不产生实际费用的情况下完成接口联调。

典型使用场景 #

照相馆/图文店管理系统：为线下门店提供增值服务，店员拍摄照片后，通过系统直接为顾客办理回执，提升客单价。
自助证件照设备：集成在无人值守的自助照相亭中，用户拍摄满意后，直接在设备上完成回执办理并打印。
在线证件照小程序/APP：为C端用户提供“拍照+回执”的一站式服务，用户足不出户即可获取办证所需的回执单。
企业/学校批量采集：在员工入职或学生入学时，批量采集照片并统一办理回执，简化行政流程。
政务服务平台：集成到地方政务APP或公众号中，作为便民服务的一部分，方便市民在线办理业务。

基础URL: https://www.clipimg.com/app/receipt_api.php

认证方式: 使用API密钥进行认证，在请求参数中包含 apikey 字段。

计费与扣点说明 #

办理成功扣除 500 点；
办理不成功不扣点。

错误码说明 #

错误码	说明
0	成功
1001	无效的API密钥
1002	回执类型ID不能为空
1003	证件照URL不能为空
1004	自定义字段不能为空
1005	必填字段不能为空
1006	手机号格式不正确
1007	身份证号格式不正确
1008	无效的回执类型
1009	申请单号不能为空
1010	申请记录不存在
1011	申请单号数组不能为空
1012	单次查询申请单号不能超过100个
1013	账户余额不足
2001	申请提交失败，请稍后重试
2002	系统异常，请稍后重试

支持的回执类型清单 #

ID	回执名称	描述	必填字段	支持地区
1	第二代居民身份证数字相片	第二代居民身份证数字相片回执办理	办证地区	广东省 (全省21市) 青海省 (青海)
2	护照及港澳通行证数字相片	护照及港澳通行证数字相片回执办理	办证地区	广东省 (仅限深圳市)
3	社会保障卡数字相片	社会保障卡数字相片回执办理	办证地区	广东省 (全省21市)
4	居住证相片	居住证相片回执办理	办证地区	广东省 (仅限深圳市)
5	机动车驾驶证数字相片	机动车驾驶证数字相片回执办理	办证地区身份证号	广东省 (全省21市)
6	深圳市网约车驾驶员数码相片	深圳市网约车驾驶员数码相片回执办理	办证地区	广东省 (仅限深圳市)
7	婴儿社保卡数字相片	婴儿社保卡数字相片回执办理	办证地区	广东省 (仅限深圳市)
8	会计人员相片采集	会计人员相片采集回执办理	办证地区	广东省 (仅限深圳市)
9	退役军人优待证	退役军人优待证回执办理	办证地区	广东省 (仅限深圳市)
10	深圳市敬老优待证	深圳市敬老优待证回执办理	办证地区	广东省 (仅限深圳市)
11	港澳台居民居住证数字相片	港澳台居民居住证数字相片回执办理	办证地区	广东省 (全省21市)
12	深圳市暂住老人免费乘车证	深圳市暂住老人免费乘车证回执办理	办证地区	广东省 (仅限深圳市)
13	健美操项目年度备案专用相片	健美操项目年度备案专用相片回执办理	办证地区	广东省 (仅限深圳市)
14	律师资格证数字相片	律师资格证数字相片回执办理	办证地区	广东省 (仅限深圳市)
15	保安管理人员/保安员证相片	保安管理人员/保安员证相片回执办理	办证地区	广东省 (全省21市)

注：

全省21市 包括：深圳市、广州市、韶关市、珠海市、汕头市、佛山市、江门市、湛江市、茂名市、肇庆市、惠州市、梅州市、汕尾市、河源市、阳江市、清远市、东莞市、中山市

API接口 #

1. 提交证件照回执办理申请 #

接口地址: POST /submit

请求参数:

参数名	类型	必填	说明
apikey	string	是	API密钥
receipt_type_id	integer	是	回执类型ID
id_photo_url	string	是	证件照URL
custom_fields	object	是	客户信息和自定义字段
callback_url	string	否	回调URL
simulate	boolean	否	是否为模拟测试，默认 false；仅用于联调/测试，不会真实办理
simulate_result	string	否	需要模拟的结果：pending/processing/submitted/completed/failed；当 simulate=true 时可设置，默认 completed

custom_fields 规则说明:

提交申请时，业务相关字段统一放在 custom_fields 对象中；实际必填项以 /types 接口返回的 required_fields 为准。

常见字段说明：

字段	说明
`city`	办证地区字段，放在 `custom_fields.city` 中传递；建议按 `省,市` 格式填写，例如 `广东省,深圳市`。
`customer_id_card`	非通用必填字段；仅当对应回执类型的 `required_fields` 包含该字段时才必须提供。如传入，必须为合法的 18 位身份证号。
其他扩展字段	当前已上线回执类型暂未要求传入；如后续新增业务字段，以 `/types` 返回结果和业务通知为准。

最小可用示例（以身份证类回执为例，仅演示必填字段）:

{
  "city": "广东省,深圳市"
}

条件字段示例（以驾驶证类回执为例）:

{
  "city": "广东省,深圳市",
  "customer_id_card": "110101199001011234"
}

请求示例（以驾驶证类回执为例）:

curl -X POST https://www.clipimg.com/app/receipt_api.php/submit \
  -H "Content-Type: application/json" \
  -d '{
    "apikey": "your-api-key",
    "receipt_type_id": 5,
    "id_photo_url": "http://example.com/photo.jpg",
    "custom_fields": {
      "city": "广东省,深圳市",
      "customer_id_card": "110101199001011234"
    },
    "callback_url": "http://your-domain.com/callback",
    "simulate": true,
    "simulate_result": "completed"
  }'

成功响应:

{
  "code": 0,
  "data": {
    "application_no": "RA20231201143059001",
    "message": "申请提交成功，请等待处理"
  }
}

说明：常规情况下，申请提交后通常会在 10 分钟内处理完成；如提交时传入了 callback_url，系统会在处理完成后主动发送回调通知。

失败响应:

{
  "code": 1006,
  "message": "手机号格式不正确"
}

2. 查询回执办理结果 #

接口地址: GET /query

请求参数:

参数名	类型	必填	说明
apikey	string	是	API密钥
application_no	string	是	申请单号

请求示例:

curl "https://www.clipimg.com/app/receipt_api.php/query?apikey=your-api-key&application_no=RA20231201143059001"

成功响应:

{
  "code": 0,
  "data": {
    "application_no": "RA20231201143059001",
    "receipt_type_name": "机动车驾驶证数字相片",
    "custom_fields": {
      "city": "广东省,深圳市",
      "customer_id_card": "110101199001011234"
    },
    "status": "completed",
    "standard_photo_url": "http://example.com/standard_photo.jpg",
    "result_url": "http://example.com/result.pdf",
    "result_message": "办理完成",
    "image_code": "IMG20231201001",
    "submit_time": "2023-12-01 14:30:59",
    "process_time": "2023-12-01 14:32:10",
    "complete_time": "2023-12-01 14:38:26"
  }
}

响应字段说明:

application_no: 申请单号
receipt_type_name: 回执类型名称
custom_fields: 完整的自定义字段数据
status: 处理状态
standard_photo_url: 回执办理系统返回的标准照片链接（完成时提供）
result_url: 结果文件下载URL（完成时提供）
result_message: 处理结果说明
image_code: 检测机构系统的图像号码（完成时提供）
submit_time: 申请提交时间
process_time: 开始处理时间
complete_time: 完成处理时间

状态说明:

pending: 已创建申请，等待系统开始处理。
processing: 系统已开始办理，结果尚未产出。
submitted: 已提交到回执/检测系统，等待最终结果返回。
completed: 办理成功完成，可读取 result_url、standard_photo_url、image_code 等结果字段。
failed: 办理失败，建议结合 result_message 定位原因。

3. 批量查询回执办理结果 #

接口地址: POST /batch_query

请求参数:

参数名	类型	必填	说明
apikey	string	是	API密钥
application_nos	array	是	申请单号数组(最多100个)

请求示例:

curl -X POST https://www.clipimg.com/app/receipt_api.php/batch_query \
  -H "Content-Type: application/json" \
  -d '{
    "apikey": "your-api-key",
    "application_nos": [
      "RA20231201143059001",
      "RA20231201143059002",
      "RA20231201143059003"
    ]
  }'

成功响应:

{
  "code": 0,
  "data": [
    {
      "application_no": "RA20231201143059001",
      "receipt_type_name": "机动车驾驶证数字相片",
      "custom_fields": {
        "city": "广东省,深圳市",
        "customer_id_card": "110101199001011234"
      },
      "status": "completed",
      "standard_photo_url": "http://example.com/standard_photo1.jpg",
      "result_url": "http://example.com/result1.pdf",
      "result_message": "办理完成",
      "image_code": "IMG20231201001",
      "submit_time": "2023-12-01 14:30:59",
      "process_time": "2023-12-01 14:32:10",
      "complete_time": "2023-12-01 14:38:26"
    },
    {
      "application_no": "RA20231201143059002", 
      "receipt_type_name": "第二代居民身份证数字相片",
      "custom_fields": {
        "city": "广东省,广州市"
      },
      "status": "processing",
      "standard_photo_url": null,
      "result_url": null,
      "result_message": null,
      "image_code": null,
      "submit_time": "2023-12-01 15:20:30",
      "process_time": "2023-12-01 15:25:15",
      "complete_time": null
    }
  ]
}

4. 获取回执类型列表 #

接口地址: GET /types

请求参数:

参数名	类型	必填	说明
apikey	string	是	API密钥

请求示例:

curl "https://www.clipimg.com/app/receipt_api.php/types?apikey=your-api-key"

响应字段说明:

字段	类型	说明
id	integer	回执类型ID
name	string	名称
description	string	描述
required_fields	array	申请时 custom_fields 中必须提供的字段列表
parameter_guide	object	各自定义字段的填写指南。结构：{ “custom_fields”: { 字段名: { label, description, allowed_values } } }；allowed_values 为省市映射数组
sort_order	integer	排序值

提示：city 传值规范——从 allowed_values 中选择办证地区；提交时以省,市格式（逗号分隔）传入，例如：广东省,深圳市。

提示：required_fields 仅表示该回执类型提交时 custom_fields 中必须提供的字段，并不代表其他字段不能传。除 required_fields 的非空校验外，当前接口会对 customer_id_card 执行格式校验；如后续扩展字段包含 customer_phone，提交时也会校验格式。

建议：客户接入时，先调用 /types 获取目标回执类型的 required_fields 和 parameter_guide，再按该类型要求组装 custom_fields，不要直接把文档中的扩展示例当作所有类型的固定请求模板。

成功响应示例:

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "name": "第二代居民身份证数字相片",
      "description": "第二代居民身份证数字相片回执办理",
      "required_fields": ["city"],
      "parameter_guide": {
        "custom_fields": {
          "city": {
            "label": "办证地区",
            "description": "请选择办证地区；提交时以省,市格式（逗号分隔）传入，例如：广东省,深圳市。",
            "allowed_values": [
              {"province": "广东省", "cities": ["深圳市","广州市","韶关市","珠海市","汕头市","佛山市","江门市","湛江市","茂名市","肇庆市","惠州市","梅州市","汕尾市","河源市","阳江市","清远市","东莞市","中山市","潮州市","揭阳市","云浮市"]},
              {"province": "青海省", "cities": ["青海市"]}
            ]
          }
        }
      },
      "sort_order": 1
    },
    {
      "id": 5,
      "name": "机动车驾驶证数字相片",
      "description": "机动车驾驶证数字相片回执办理",
      "required_fields": ["city", "customer_id_card"],
      "parameter_guide": {
        "custom_fields": {
          "city": {
            "label": "办证地区",
            "description": "请选择办证地区；提交时以省,市格式（逗号分隔）传入，例如：广东省,深圳市。",
            "allowed_values": [
              {"province": "广东省", "cities": ["韶关市","珠海市","汕头市","佛山市","江门市","湛江市","茂名市","肇庆市","惠州市","梅州市","汕尾市","河源市","阳江市","清远市","东莞市","中山市","潮州市","揭阳市","云浮市","深圳市","广州市"]}
            ]
          },
          "customer_id_card": {
            "label": "身份证号",
            "description": "接相关部门要求，该回执需要如实登记办证人身份证号，请准确无误填写，否则将无法办证。"
          }
        }
      },
      "sort_order": 5
    }
  ]
}

5. 获取申请记录列表 #

接口地址: GET /applications

请求参数:

参数名	类型	必填	说明
apikey	string	是	API密钥
page	integer	否	页码，默认1
size	integer	否	每页数量，默认20，最大100
status	string	否	状态筛选

请求示例:

curl "https://www.clipimg.com/app/receipt_api.php/applications?apikey=your-api-key&page=1&size=10&status=completed"

成功响应:

{
  "code": 0,
  "data": {
    "list": [
      {
        "application_no": "RA20231201143059001",
        "receipt_type_name": "机动车驾驶证数字相片",
        "custom_fields": {
          "city": "广东省,深圳市",
          "customer_id_card": "110101199001011234"
        },
        "status": "completed",
        "standard_photo_url": "http://example.com/standard_photo.jpg",
        "result_url": "http://example.com/result.pdf",
        "image_code": "IMG20231201001",
        "submit_time": "2023-12-01 14:30:59",
        "complete_time": "2023-12-01 14:38:26"
      }
    ],
    "total": 50,
    "page": 1,
    "size": 10,
    "totalPages": 5
  }
}

回调通知 #

当申请处理完成时，系统会向提交申请时指定的 callback_url 发送POST请求通知。

回调请求格式:

{
  "application_no": "RA20231201143059001",
  "status": "completed",
  "standard_photo_url": "http://example.com/standard_photo.jpg",
  "result_url": "http://example.com/result.pdf",
  "result_message": "办理完成",
  "image_code": "IMG20231201001",
  "complete_time": "2023-12-08 10:20:30",
  "timestamp": "2023-12-08T10:21:00.000Z"
}

回调字段说明:

application_no: 申请单号
status: 最终状态（completed 或 failed）
standard_photo_url: 回执办理系统返回的标准照片链接（成功时提供）
result_url: 结果文件下载URL（成功时提供）
result_message: 处理结果说明
image_code: 检测机构系统的图像号码（成功时提供）
complete_time: 完成处理时间
timestamp: 回调发送时间（ISO 8601格式）

回调响应要求:

返回HTTP状态码200表示接收成功
系统会重试失败的回调，最多重试3次

SDK示例 #

PHP示例 #

<?php
class ReceiptApiClient {
    private $baseUrl;
    private $apiKey;
    
    public function __construct($baseUrl, $apiKey) {
        $this->baseUrl = rtrim($baseUrl, '/');
        $this->apiKey = $apiKey;
    }
    
    public function submitApplication($data) {
        $data['apikey'] = $this->apiKey;
        return $this->post('/submit', $data);
    }
    
    public function queryResult($applicationNo) {
        return $this->get('/query', [
            'apikey' => $this->apiKey,
            'application_no' => $applicationNo
        ]);
    }
    
    public function batchQueryResult($applicationNos) {
        return $this->post('/batch_query', [
            'apikey' => $this->apiKey,
            'application_nos' => $applicationNos
        ]);
    }
    
    public function getReceiptTypes() {
        return $this->get('/types', [
            'apikey' => $this->apiKey
        ]);
    }
    
    public function getApplications($page = 1, $size = 20, $status = '') {
        $params = [
            'apikey' => $this->apiKey,
            'page' => $page,
            'size' => $size
        ];
        if (!empty($status)) {
            $params['status'] = $status;
        }
        return $this->get('/applications', $params);
    }
    
    private function post($endpoint, $data) {
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $this->baseUrl . $endpoint);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json'
        ]);
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        return json_decode($response, true);
    }
    
    private function get($endpoint, $params = []) {
        $url = $this->baseUrl . $endpoint;
        if (!empty($params)) {
            $url .= '?' . http_build_query($params);
        }
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        return json_decode($response, true);
    }
}

// 使用示例
$client = new ReceiptApiClient('https://www.clipimg.com/app/receipt_api.php', 'your-api-key');

// 提交申请
$result = $client->submitApplication([
  'receipt_type_id' => 5,
    'id_photo_url' => 'http://example.com/photo.jpg',
    'custom_fields' => [
        'city' => '广东省,深圳市',
        'customer_id_card' => '110101199001011234'
    ],
    'callback_url' => 'http://your-domain.com/callback'
]);

// 查询结果
$result = $client->queryResult('RA20231201143059001');

// 批量查询
$result = $client->batchQueryResult([
    'RA20231201143059001',
    'RA20231201143059002'
]);

// 获取回执类型列表
$types = $client->getReceiptTypes();

// 获取申请记录列表
$applications = $client->getApplications(1, 10, 'completed');
?>

Python示例 #

import requests
import json

class ReceiptApiClient:
    def __init__(self, base_url, api_key):
        self.base_url = base_url.rstrip('/')
        self.api_key = api_key
    
    def submit_application(self, data):
        data['apikey'] = self.api_key
        response = requests.post(f"{self.base_url}/submit", json=data)
        return response.json()
    
    def query_result(self, application_no):
        params = {
            'apikey': self.api_key,
            'application_no': application_no
        }
        response = requests.get(f"{self.base_url}/query", params=params)
        return response.json()
    
    def batch_query_result(self, application_nos):
        data = {
            'apikey': self.api_key,
            'application_nos': application_nos
        }
        response = requests.post(f"{self.base_url}/batch_query", json=data)
        return response.json()
    
    def get_receipt_types(self):
        params = {
            'apikey': self.api_key
        }
        response = requests.get(f"{self.base_url}/types", params=params)
        return response.json()
    
    def get_applications(self, page=1, size=20, status=''):
        params = {
            'apikey': self.api_key,
            'page': page,
            'size': size
        }
        if status:
            params['status'] = status
        response = requests.get(f"{self.base_url}/applications", params=params)
        return response.json()

# 使用示例
client = ReceiptApiClient('https://www.clipimg.com/app/receipt_api.php', 'your-api-key')

# 提交申请
result = client.submit_application({
  'receipt_type_id': 5,
    'id_photo_url': 'http://example.com/photo.jpg',
    'custom_fields': {
        'city': '广东省,深圳市',
        'customer_id_card': '110101199001011234'
    },
    'callback_url': 'http://your-domain.com/callback'
})

# 查询结果
result = client.query_result('RA20231201143059001')

# 批量查询
result = client.batch_query_result([
    'RA20231201143059001',
    'RA20231201143059002'
])

# 获取回执类型列表
types = client.get_receipt_types()

# 获取申请记录列表
applications = client.get_applications(page=1, size=10, status='completed')

注意事项 #

API密钥安全: 请妥善保管API密钥，不要在客户端代码中暴露
图片要求: 证件照需要是标准的证件照格式，建议使用JPG或PNG格式
回调URL: 确保回调URL可以正常访问，并能够处理POST请求
请求频率: 建议控制请求频率，避免过于频繁的API调用
错误处理: 请妥善处理API返回的错误信息，并进行相应的重试机制
字段验证: 系统会根据回执类型的 required_fields 验证必填字段
图像号码: image_code 字段仅在任务完成时返回，用于标识检测机构系统的图像记录
数据结构: 响应中的 custom_fields 包含完整的自定义字段数据
模拟测试说明: 当 simulate=true 时，该申请仅用于联调/演示，内部自动化系统会在获取任务时返回与 simulate_result 一致的模拟数据（不会真实办理，也不会扣费）。

技术支持 #

如有技术问题或需要帮助，请联系技术支持。

可立图API文档

证件照回执自动化办理API文档

接口概述 #

典型使用场景 #

计费与扣点说明 #

错误码说明 #

支持的回执类型清单 #

API接口 #

1. 提交证件照回执办理申请 #

2. 查询回执办理结果 #

3. 批量查询回执办理结果 #

4. 获取回执类型列表 #

5. 获取申请记录列表 #

回调通知 #

SDK示例 #

PHP示例 #

Python示例 #

注意事项 #

技术支持 #

相关推荐 #