鹧应科技 鹧应证件照 API
返回资讯列表

如何开展在线照片回执业务？回执 API 接入流程与 PHP 示例

办理社保卡、驾驶证等业务时，部分地区和办理渠道会要求提供相应的数码相片回执。用户按要求提交照片和资料，取得回执后，才能继续办理对应业务。

对于准备开展回执业务的商家来说，自行对接办理渠道，需要先了解相应的资质和接入要求，还要具备判断照片是否符合要求、处理照片问题的能力。遇到照片审核不通过的情况，也需要跟进原因，安排调整或重新提交。

选择有经验的合作平台，可以把照片检测处理和回执办理接入现成的服务流程，让商家集中精力开发自己的业务入口、订单系统和用户服务。

本文介绍鹧应证件照 API 平台的回执接口，以及如何通过 PHP 完成对接。网站、小程序、App 和商家业务系统，都可以通过服务端调用接口开展在线回执办理。

为什么选择鹧应回执 API？

鹧应有多年的回执业务服务经验，提供从照片检测处理、提交办理到结果通知的回执服务流程。商家通过 API 提交照片和办理资料，平台处理订单，再将审核进度和办理结果通知商家系统。

平台提供 PHP、Python、Java、Go、Node.js、C# 多种语言的接口示例，可以按自己熟悉的开发语言选择。下面以PHP语言为例，介绍主要接入步骤。

接入准备：注册账号，创建应用

先进入鹧应证件照 API 官网注册账号，登录后创建应用，获取应用 key。接着确认准备办理的回执类型、对应的规格 ID，以及该规格需要提交的资料。

开发前准备好以下内容：

  • 应用 key：用于服务端调用接口。

  • 回执规格 item_id：对应实际办理的回执类型。

  • 用户照片和办理资料：资料字段根据所选规格填写。

  • 回调地址 notice_url：用于接收审核和办理结果，需要能够被平台访问。

PHP 环境需要启用 cURL 扩展。下面的代码均在服务端运行，应用 key 使用占位值，正式接入时替换为自己的配置。

第一步：回执检测与制作

调用 /receipt/make，提交应用 key、回执规格 ID 和照片的 Base64 内容。平台按回执规格检测、处理照片，成功后返回 pic_id、证件照片，证件照片可以展示再制作完成的页面，用户确认没有问题就可以下一步提交订单。

先封装一个公共请求函数，后续提交订单也会用到。接口采用 POST 表单请求，图片的 Base64 内容由 http_build_query 统一编码。

<?php

function receipt_request($action, $form)
{
    $curl = curl_init('https://api.zjzapi.com/receipt/' . $action);
    curl_setopt_array($curl, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($form),
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/x-www-form-urlencoded',
        ],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_TIMEOUT => 60,
    ]);

    $body = curl_exec($curl);
    curl_close($curl);

    return json_decode($body, true);
}

$app_key = 'YOUR_APP_KEY';
$item_id = 'YOUR_RECEIPT_ITEM_ID';
$image_path = __DIR__ . '/photo.jpg';
$notice_url = 'https://your-domain.example/receipt/notice';

$image_content = file_get_contents($image_path);

$make_result = receipt_request('make', [
    'key' => $app_key,
    'item_id' => $item_id,
    'image' => base64_encode($image_content),
]);

$pic_id = $make_result['data']['pic_id'];

将 YOUR_APP_KEY、YOUR_RECEIPT_ITEM_ID 和照片路径替换为实际值。pic_id 是提交订单前的照片标识，拿到它后，还需要继续提交办理申请。

示例按接口成功返回的流程展示，直接读取返回数据；实际业务可根据返回的 code 和 msg 展示处理结果。

第二步：提交回执订单

拿到 pic_id 后，调用 /receipt/submit，提交照片标识、回调地址和办理资料。下面的代码接在第一步之后运行，复用前面的请求函数和变量。

以下以广东驾驶证的资料字段举例，其他规格需要按各自要求填写，不能直接套用同一份资料。

$param = [
    'text_mobile' => 'YOUR_MOBILE',
    'text_city' => '深圳',
    'text_name' => 'YOUR_NAME',
    'text_idcard' => 'YOUR_IDCARD_NUMBER',
];

$submit_result = receipt_request('submit', [
    'key' => $app_key,
    'pic_id' => $pic_id,
    'notice_url' => $notice_url,
    'param' => json_encode($param, JSON_UNESCAPED_UNICODE),
    'is_print' => 0,
]);

$order_no = $submit_result['data']['order_no'];

// 将 $order_no 保存到自己的业务订单中，用于匹配后续通知。

pic_id 有效期为 50 分钟，需要在有效期内提交。 接口返回 order_no 表示订单提交成功，接下来等待平台审核和办理结果。

示例中 is_print=0 表示不选择打印邮寄。如需打印邮寄，将其设为 1，同时提交 print_param，内容为包含收件人姓名 name、电话 phone、省市区 province、city、district 和详细地址 address 的 JSON 字符串。

第三步：接收审核结果，获取回执单

平台通过前面填写的 notice_url，以 POST 表单方式通知订单状态。商家系统按订单号找到对应记录，更新进度，并在办理完成后向用户提供回执下载入口。

主要状态如下：

  • status=2：审核中。

  • status=3：办理完成，image_receipt 为回执单图片地址。

  • status=-1：审核驳回，reject_msg 为驳回原因。

  • status=4：打印发货，logistics_info 为物流信息。

  • status=-2：订单已取消。

下面是回调处理函数，可以放进自己的服务端项目，由回调路由传入 $_POST、应用 key 和业务保存函数。

<?php

function handle_receipt_notice($form, $app_key, $save_notice)
{
    if (!hash_equals(md5($app_key), $form['sign'] ?? '')) {
        return ['code' => -1, 'msg' => '通知校验失败'];
    }

    unset($form['sign']);

    // 按 order_no 保存订单状态，完成时保存 image_receipt。
    $save_notice($form);

    return ['data' => new stdClass(), 'code' => 0, 'msg' => '同步完成'];
}

$save_notice 由商家接入自己的订单数据库，负责检查订单归属、保存状态和回执地址，并处理重复通知。保存失败时抛出异常，由回调路由返回错误响应。回调中的 sign 按应用 key 的 MD5 小写十六进制结果校验。

业务数据处理成功后，将函数返回值编码为 JSON 响应给平台；失败时返回错误响应，避免尚未保存订单结果就确认同步完成。成功响应格式为：

{"data": {}, "code": 0, "msg": "同步完成"}

收到 status=3 后，保存回执单地址 image_receipt，用户即可通过商家自己的订单页面获取办理结果。

如果审核未通过，可以根据驳回原因重新提交照片，通过检测与制作接口获取新的 pic_id，再调用提交接口，携带原 order_no 继续办理。仍处于待处理状态的订单，也可通过 /receipt/cancel 提交应用 key 和订单号申请取消。

办理费用和服务时间

商家开展回执业务前，可以先按接口成本评估自己的服务定价：

  • 回执检测与制作接口调用免费。

  • 回执订单办理完成后扣费，7 元／单。

  • 选择打印邮寄服务，再增加 7 元。

办理时段为 8:30—20:30，节假日正常办理，预计审核时长为 15 分钟。预计时长可用于页面提示，具体是否办理完成，以收到的订单通知为准。

上传照片支持 JPG、JPEG、PNG，文件不超过 5MB，分辨率小于 6000 × 6000 像素。把这些要求提前放在上传页面，方便用户准备照片。

对于准备开展在线回执业务的商家，鹧应回执 API 提供了可以接入自有产品的办理流程。先确认需要办理的回执类型，注册账号、创建应用，再完成照片提交、订单申请和结果接收，就可以围绕自己的品牌搭建回执服务入口。