View Categories

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

概述 #

证件照回执自动化办理系统为第三方项目提供证件照回执办理服务，支持提交申请、查询结果、获取类型列表等功能。

基础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个
2001申请提交失败，请稍后重试
2002系统异常，请稍后重试

API接口 #

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

接口地址: POST /submit

请求参数:

参数名类型必填说明
apikeystring是API密钥
receipt_type_idinteger是回执类型ID
id_photo_urlstring是证件照URL
custom_fieldsobject是客户信息和自定义字段
callback_urlstring否回调URL

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

{
  "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"
  }'

成功响应:

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

失败响应:

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

2. 查询回执办理结果 #

接口地址: GET /query

请求参数:

参数名类型必填说明
apikeystring是API密钥
application_nostring是申请单号

请求示例:

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

请求参数:

参数名类型必填说明
apikeystring是API密钥
application_nosarray是申请单号数组(最多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

请求参数:

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

请求示例:

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

响应字段说明:

字段类型说明
idinteger回执类型ID
namestring名称
descriptionstring描述
required_fieldsarray申请时 custom_fields 中必须提供的字段列表
parameter_guideobject各自定义字段的填写指南。结构：{ “custom_fields”: { 字段名: { label, description, allowed_values } } }；allowed_values 为省市映射数组
processing_timestring预计处理时间
sort_orderinteger排序值

提示：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

请求参数:

参数名类型必填说明
apikeystring是API密钥
pageinteger否页码，默认1
sizeinteger否每页数量，默认20，最大100
statusstring否状态筛选

请求示例:

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')

注意事项 #

  1. API密钥安全: 请妥善保管API密钥，不要在客户端代码中暴露
  2. 图片要求: 证件照需要是标准的证件照格式，建议使用JPG或PNG格式
  3. 回调URL: 确保回调URL可以正常访问，并能够处理POST请求
  4. 请求频率: 建议控制请求频率，避免过于频繁的API调用
  5. 错误处理: 请妥善处理API返回的错误信息，并进行相应的重试机制
  6. 字段验证: 系统会根据回执类型的 required_fields 验证必填字段
  7. 图像号码: image_code 字段仅在任务完成时返回，用于标识检测机构系统的图像记录
  8. 数据结构: 响应中的 custom_fields 包含完整的自定义字段数据，customer_name 和 customer_phone 是为了兼容性而提取的常用字段

技术支持 #

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

在线客服
谢谢您的关注，您的请求我们将24小时内回复。
12:01
您好，有任何疑问请与我们联系！
kris

选择聊天工具：