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

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

接口概述 #

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

系统底层对接了官方认证的检测机构，确保办理的回执真实有效，并能返回官方认证的图像号（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市) 青海省 (青海)	3-5个工作日
2	护照及港澳通行证数字相片	护照及港澳通行证数字相片回执办理	办证地区	广东省 (仅限深圳市)	3-5个工作日
3	社会保障卡数字相片	社会保障卡数字相片回执办理	办证地区	广东省 (全省21市)	3-5个工作日
4	居住证相片	居住证相片回执办理	办证地区	广东省 (仅限深圳市)	3-5个工作日
5	机动车驾驶证数字相片	机动车驾驶证数字相片回执办理	办证地区身份证号	广东省 (全省21市)	3-5个工作日
6	深圳市网约车驾驶员数码相片	深圳市网约车驾驶员数码相片回执办理	办证地区	广东省 (仅限深圳市)	3-5个工作日
7	婴儿社保卡数字相片	婴儿社保卡数字相片回执办理	办证地区	广东省 (仅限深圳市)	3-5个工作日
8	会计人员相片采集	会计人员相片采集回执办理	办证地区	广东省 (仅限深圳市)	3-5个工作日
9	退役军人优待证	退役军人优待证回执办理	办证地区	广东省 (仅限深圳市)	3-5个工作日
10	深圳市敬老优待证	深圳市敬老优待证回执办理	办证地区	广东省 (仅限深圳市)	3-5个工作日
11	港澳台居民居住证数字相片	港澳台居民居住证数字相片回执办理	办证地区	广东省 (全省21市)	3-5个工作日
12	深圳市暂住老人免费乘车证	深圳市暂住老人免费乘车证回执办理	办证地区	广东省 (仅限深圳市)	3-5个工作日
13	健美操项目年度备案专用相片	健美操项目年度备案专用相片回执办理	办证地区	广东省 (仅限深圳市)	3-5个工作日
14	律师资格证数字相片	律师资格证数字相片回执办理	办证地区	广东省 (仅限深圳市)	3-5个工作日
15	保安管理人员/保安员证相片	保安管理人员/保安员证相片回执办理	办证地区	广东省 (全省21市)	3-5个工作日

注：

全省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

客户信息和自定义字段示例:

{
  "customer_name": "张三",
  "customer_phone": "13812345678", 
  "customer_id_card": "110101199001011234",
  "address": "北京市朝阳区",
  "birth_date": "1990-01-01",
  "emergency_contact": "13812345678"
}

请求示例:

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": 1,
    "id_photo_url": "http://example.com/photo.jpg",
    "custom_fields": {
      "customer_name": "张三",
      "customer_phone": "13812345678",
      "customer_id_card": "110101199001011234",
      "address": "北京市朝阳区某某街道"
    },
    "callback_url": "http://your-domain.com/callback",
    "simulate": true,
    "simulate_result": "completed"
  }'

成功响应:

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

失败响应:

{
  "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": {
      "customer_name": "张三",
      "customer_phone": "13812345678",
      "customer_id_card": "110101199001011234",
      "address": "北京市朝阳区某某街道"
    },
    "customer_name": "张三",
    "customer_phone": "13812345678",
    "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:35:12",
    "complete_time": "2023-12-08 10:20:30"
  }
}

响应字段说明:

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

状态说明:

pending: 待处理
processing: 处理中
submitted: 已提交到回执系统
completed: 已完成
failed: 处理失败

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": {
        "customer_name": "张三",
        "customer_phone": "13812345678",
        "customer_id_card": "110101199001011234",
        "address": "北京市朝阳区某某街道"
      },
      "customer_name": "张三",
      "customer_phone": "13812345678",
      "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:35:12",
      "complete_time": "2023-12-08 10:20:30"
    },
    {
      "application_no": "RA20231201143059002", 
      "receipt_type_name": "护照申请",
      "custom_fields": {
        "customer_name": "李四",
        "customer_phone": "13987654321",
        "customer_id_card": "220101199001011234",
        "birth_date": "1990-01-01"
      },
      "customer_name": "李四",
      "customer_phone": "13987654321",
      "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 为省市映射数组
processing_time	string	预计处理时间
sort_order	integer	排序值

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

成功响应示例:

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "name": "第二代居民身份证数字相片",
      "description": "第二代居民身份证数字相片回执办理",
      "required_fields": ["city"],
      "parameter_guide": {
        "custom_fields": {
          "city": {
            "label": "办证地区",
            "description": "请选择办证地区；提交时以省,市格式（逗号分隔）传入，例如：广东省,深圳市。",
            "allowed_values": [
              {"province": "广东省", "cities": ["深圳市","广州市","韶关市","珠海市","汕头市","佛山市","江门市","湛江市","茂名市","肇庆市","惠州市","梅州市","汕尾市","河源市","阳江市","清远市","东莞市","中山市","潮州市","揭阳市","云浮市"]},
              {"province": "青海省", "cities": ["青海市"]}
            ]
          }
        }
      },
      "processing_time": "3-5个工作日",
      "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": "接相关部门要求，该回执需要如实登记办证人身份证号，请准确无误填写，否则将无法办证。"
          }
        }
      },
      "processing_time": "3-5个工作日",
      "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": {
          "customer_name": "张三",
          "customer_phone": "13812345678",
          "customer_id_card": "110101199001011234",
          "address": "北京市朝阳区某某街道"
        },
        "customer_name": "张三",
        "customer_phone": "13812345678",
        "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-08 10:20:30"
      }
    ],
    "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' => 1,
    'id_photo_url' => 'http://example.com/photo.jpg',
    'custom_fields' => [
        'customer_name' => '张三',
        'customer_phone' => '13812345678',
        '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': 1,
    'id_photo_url': 'http://example.com/photo.jpg',
    'custom_fields': {
        'customer_name': '张三',
        'customer_phone': '13812345678',
        '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 包含完整的自定义字段数据，customer_name 和 customer_phone 是为了兼容性而提取的常用字段
模拟测试说明: 当 simulate=true 时，该申请仅用于联调/演示，内部自动化系统会在获取任务时返回与 simulate_result 一致的模拟数据（不会真实办理，也不会扣费）。

技术支持 #

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

可立图API文档

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

接口概述 #

典型使用场景 #

计费与扣点说明 #

错误码说明 #

支持的回执类型清单 #

API接口 #

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

2. 查询回执办理结果 #

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

4. 获取回执类型列表 #

5. 获取申请记录列表 #

回调通知 #

SDK示例 #

PHP示例 #

Python示例 #

注意事项 #

技术支持 #

相关推荐 #