LOGO

DARKROOM / API文档

当前版本:0.2

Darkroom的API接口,适合具体独立技术开发团队的专业级摄影机构。

比如,有一家叫做【ABC123】的摄影机构,拥有自己的独立官网和预约系统(假设网址是 abc123.com ),那么,当ABC123的客户访问 abc123.com 完成在线预约后,API接口可以实时地、自动地把该订单传输到Darkroom系统,从而使工作人员可以直接在Darkroom里对该订单进行在线管理,无需再自行搭建一个后期管理平台。

如果有这个需要,请联系客服生成一对API秘钥,即可通过调用我们的API接口来实现数据的传输。

本API按照REST 风格进行设计。如果您对REST不太了解,可以参考 RESTful API 设计指南

对于缺乏技术开发能力的小型机构,我们建议您登陆后一键启用Darkroom的在线预约模块 ,可以大幅降低技术成本。

POST /orders/create

新建一个订单

示例代码(PHP):

<?php
    //Set your API keys here:
    define('DARKROOM_API_KEY','.....');
    define('DARKROOM_API_SECRET','.....');
    define('DARKROOM_API_URL','https://api.darkroom.net/0.2');

    //下载curl函数库: https://api.darkroom.net/assets/api/0.2/darkroom.phpinc 
    require "*****/path/to/darkroom.phpinc"; 
    

    $api_res = curlPOST("/orders/create", array(
        //以下为必要的订单参数:
        "order_id"=>"123456", //必填:唯一的订单编号
        "order_plan"=>"BASIC_PACK", //必填:拍摄服务的唯一编号(见【门店】->【服务/套餐】页面)
        "order_date"=>"2016-02-12", //必填:拍摄日期。如果拍摄日期未确定,就填2099-09-09
        "order_hour"=>"14:30:00", //必填:当天的拍摄开始时间
     
        //以下为必要的客户参数:
        "customer_name"=>"董小姐", //必填:客户的名字(称呼)
        "customer_mobile"=>"13800001234", //必填:客户的手机号

        //以下均为可选项:
        "store_id"=>"123456",  //可选:门店的编号(见【账户】->【门店设置】页面),如果只有一家店则可以留空
        "customer_pass"=>"1234ABCD", //可选:设置一个客户登录Darkroom的密码(如果留空,则由系统自动生成)
        "customer_gender"=>"male", //可选:客户的性别(male或者female)
        "customer_email"=>"abc@gmail.com", //可选:客户的Email
        "customer_addr"=>"上海市光明路18号", //可选:客户的地址
        "customer_remark"=>"我会自己化妆过来,不需要化妆师", //可选:客户写的备注
        "team_remark"=>"这是一个重要客户", //可选:团队的内部备注(对客户不可见)
        
        "order_coupon"=>"ABC123", //可选:优惠码
        "created_at"=>"2015-08-18 21:12:00", //可选:订单的生成时间(如果留空,则自动设置为API发起时间)

        "prepay_amount"=>"10.00", //可选:预约时支付的订金金额
        "prepay_method"=>"weixin", //可选:订金的支付方式代码(比如:alipay 或者 weixin)
        "prepay_trans_id"=>"ABC1234567890XZY", //可选:支付订金时所对应的唯一交易号(这个交易号由支付宝或者微信等支付网关生成)


        //如果是儿童摄影(或者拍摄主体是孩子):
        "customer_babyname"=>"董小妹", //可选:孩子的名字
        "customer_babybirth"=>"2013-02-12", //可选:孩子的生日
        "customer_babygender"=>"girl", //可选:孩子的性别(boy,girl,如果是多个孩子,就设置为:other)
        

    ));  

    if ($api_res==false) 
        die("Curl ERROR");
    else
        $arr=json_decode($api_res,true);
?>
        

服务器响应示例(JSON):

{
    "response": "ok",
    "error_code": "0",
    "error_msg": "",
    "order_id": "123456",
    "order_status": "created",
    "customer_pass": "wtey32kxexlwk",
    "order_url": "https:\/\/www.darkroom.net\/i\/xxxxxxxyyyyyyzzzzz",
    "order_files": []
}
        
如果没有提交customer_pass这个参数,则系统会自动生成一个客户登录密码,并通过api返回customer_pass

GET /orders/{id}

通过订单号查询到该订单的详情(以及照片下载链接)

示例代码(PHP):

<?php
    //Set your API keys here:
    define('DARKROOM_API_KEY','.....');
    define('DARKROOM_API_SECRET','.....');
    define('DARKROOM_API_URL','https://api.darkroom.net/0.2');

    //下载curl函数库: https://api.darkroom.net/assets/api/0.2/darkroom.phpinc 
    require "*****/path/to/darkroom.phpinc"; 
    
    $order_id="123456";//订单编号
    $api_res = curlGET("/orders/".$order_id);  

    if ($api_res==false) 
        die("Curl ERROR");
    else
        $arr=json_decode($api_res,true);
?>
        

服务器响应示例(JSON):

{
    "response": "ok",
    "error_code": "0",
    "error_msg": "",
    "order_id": "123456",
    "order_status": "downloading",
    "order_url": "https:\/\/www.darkroom.net\/i\/xxxxxxxyyyyyyzzzzz",
    "order_files": [
        {
            "thumb": "https:\/\/qincocdn.darkroom.net\/cdn\/darkroom\/big\/9fc6f1\/8062253160D4.jpg!small.jpg",
            "origin": "http:\/\/api.darkroom.net\/down\/123456\/xxxxxx"
        },
        {
            "thumb": "https:\/\/qincocdn.darkroom.net\/cdn\/darkroom\/big\/9fc6f1\/176AAACD3139.jpg!small.jpg",
            "origin": "http:\/\/api.darkroom.net\/down\/123456\/xxxxxx"
        }
    ]
}
        
提示:订单的状态有以下几种类型:
  • uploading: 拍摄已完成,原片还没上传
  • choosing: 拍摄已完成,客户正在选片(如果需要选片的话)
  • processing: 设计师正在对照片进行精修处理
  • downloading: 精修已完成,客户可以下载精修片了
  • closed: 下载已完成且过去了10天,自动设置订单结束(3个月内依然可以下载,超过3个月可能无法下载)
  • canceled: 因为某些原因,订单已被取消
  • absent: 客户爽约了,没按时来拍摄

POST /customers/login

验证客户的账号(手机号或Email)和密码,验证后则返回一个自动登录darkroom的网址

示例代码(PHP):

<?php
    //Set your API keys here:
    define('DARKROOM_API_KEY','.....');
    define('DARKROOM_API_SECRET','.....');
    define('DARKROOM_API_URL','https://api.darkroom.net/0.2');

    //下载curl函数库: https://api.darkroom.net/assets/api/0.2/darkroom.phpinc 
    require "*****/path/to/darkroom.phpinc"; 
    
    $account="13800001234";//手机号或者Email
    $password="12345678";//客户在darkroom的密码
    $api_res = curlPOST("/customers/login", array("account"=>$account,"password"=>$password) );  

    if ($api_res==false) 
        die("Curl ERROR");
    else
        $arr=json_decode($api_res,true);
?>
        

服务器响应示例(JSON):

{
    "response": "ok",
    "error_code": "0",
    "error_msg": "",
    "customer_uid": "123456",
    "redirect_url": "https:\/\/www.darkroom.net\/xxxx\/yyyy"
}
        

POST /customers/quicklogin

免密码登录:通过客户手机号或者Email,生成一个快速登录darkroom的网址,客户点击该网址后即可自动登录darkroom,无需输入用户名或密码

示例代码(PHP):

<?php
    //Set your API keys here:
    define('DARKROOM_API_KEY','.....');
    define('DARKROOM_API_SECRET','.....');
    define('DARKROOM_API_URL','https://api.darkroom.net/0.2');

    //下载curl函数库: https://api.darkroom.net/assets/api/0.2/darkroom.phpinc 
    require "*****/path/to/darkroom.phpinc"; 
    
    $account="13800001234";//手机号或者Email
    $api_res = curlPOST("/customer/quicklogin", array("account"=>$account) );  

    if ($api_res==false) 
        die("Curl ERROR");
    else
        $arr=json_decode($api_res,true);
?>
        

服务器响应示例(JSON):

{
    "response": "ok",
    "error_code": "0",
    "error_msg": "",
    "customer_uid": "123456",
    "redirect_url": "https:\/\/www.darkroom.net\/xxxx\/yyyy"
}
        

GET /coupons/{coupon_code}

查询某个优惠码的详细信息

示例代码(PHP):

<?php
    //Set your API keys here:
    define('DARKROOM_API_KEY','.....');
    define('DARKROOM_API_SECRET','.....');
    define('DARKROOM_API_URL','https://api.darkroom.net/0.2');

    //下载curl函数库: https://api.darkroom.net/assets/api/0.2/darkroom.phpinc 
    require "*****/path/to/darkroom.phpinc"; 
    
    $coupon_code="XYZ123456";//优惠码
    $api_res = curlGET("/coupon/".$coupon_code);  

    if ($api_res==false) 
        die("Curl ERROR");
    else
        $arr=json_decode($api_res,true);
?>
        

服务器响应示例(JSON):

{
    "response": "ok",
    "error_code": "0",
    "error_msg": "",
    "coupon_code": "XYZ123456",
    "coupon_discount": "8.5",
    "coupon_expire": "2016-02-02 12:00:00",
    "coupon_used": "1"
}
        
优惠码的属性:
  • coupon_discount: 优惠码的折扣(比如:8.5表示85折 )
  • coupon_expire: 优惠码的失效时间
  • coupon_used: 优惠码是否已经被使用,如果coupon_used=1,则表示已被人使用,无法再次使用

微信公众号

微信服务号

  • Made with
  • 杭州 滨江区