• 用户按照当当的规范拼装一个正确的URL,通过HTTP请求,就能够拿到用户自己需要的数据。

  • 当当API (接口) 采用 REST 风格,只需将所需参数拼装成http请求,即可调用。故支持 http 协议请求的程序语言,均可调用当当API,例如php、C#、asp、java、delphi 等。


  • 环境地址,即调用接口(API)时,都通过访问该地址,来获取该接口需要获取的数据

    正式环境:https://gw-api.dangdang.com/openapi/rest?v=1.0 

    http://api.open.dangdang.com/openapi/rest?v=1.0  (已弃用)

  • 调用API ,必须传入系统参数和应用参数。系统参数是调用每个api时默认的必填参数;应用参数由于不同 API 各自不同,这里以dangdang.item.itemid.get为例说明,更多请参考API文档。

    1. 系统级调用参数


    名称 类型 是否必须 描述

     method

     string

     Y

     API接口名称

     timestamp

     string

     Y

     时间戳,格式为yyyy-MM-dd HH:mm:ss,例如:2013-05-06 13:52:03

     format

     string

    Y

     可选,指定响应格式。默认xml,目前支持格式为xml

     app_key

     string

     Y

     分配给应用的AppKey,创建应用时可获得

     v

     string

     Y

     API协议版本,可选值:1.0

     sign

     string

     Y

     对API输入参数进行md5加密获得,详细参考签名sign

     sign_method

     string

     Y

     参数的加密方法选择,可选值是:md5

     session

     string

     Y


     分配给用户的SessionKey(或 Access Token),通过登陆授权获取,方法参考用户授权介绍。
         API文档上“API用户授权类型”标识为“需要”的,调用时均要传该参数



    2. 应用参数

    此处以dangdang.item.itemid.get接口为例,查看其他接口的应用参数请参照对应页面。

    名称  类型 是否必须 描述 

     oit

     string

     Y

     企业商品标识符


    3. 签名sign

    调用API时需要对请求参数进行签名验证,服务器也会对该请求参数进行验证是否合法的。方法如下:

    (1)根据参数名称(除签名和图片)将所有系统级参数按照字母先后顺序排序:key + value .... key + value

    例如:将method=dangdang.item.itemid.get,timestamp=2013-06-20 19:33:00,format=xml,app_key=21000000515,v=1.0,sign_method=md5,session=4ECBED3068CB782DC287FACCD52E06AB6E6F1CB4C63EF3372AC7CD88FE34C063排序为app_key=21000000515,format=xml,method=dangdang.item.itemid.get,session=4ECBED3068CB782DC287FACCD52E06AB6E6F1CB4C63EF3372AC7CD88FE34C063,sign_method=md5,timestamp=2013-06-20 19:33:00,v=1.0,参数名和参数值链接后,得到拼装字符串app_key2100000826formatxmlmethoddangdang.item.itemid.getsession4ECBED3068CB782DC287FACCD52E06AB6E6F1CB4C63EF3372AC7CD88FE34C063sign_methodmd5timestamp2013-06-20 19:33:00v1.0

    (2)系统支持MD5加密方式

    md5:将secret(App Secret)拼接到参数字符串头、尾(以上参数拼接后为5FDD35D3A94D73514CD6F1A5B58AED53app_key2100000826formatxmlmethoddangdang.item.itemid.getsession4ECBED3068CB782DC287FACCD52E06AB6E6F1CB4C63EF3372AC7CD88FE34C063sign_methodmd5timestamp2013-06-20 19:33:00v1.05FDD35D3A94D73514CD6F1A5B58AED53)进行md5加密后,再转化成大写,格式是:md5(secretkey1value1key2value2...secret)

    注:我们需要的是32位的大写字符串

    4. 调用实例

    调用API:dangdang.item.itemid.get,使用系统默认MD5加密,因为各语言语法不一致,以下实例只体现逻辑。

    (1)输入参数为:

    method=dangdang.item.itemid.get

    timestamp=2013-05-06 13:52:03

    format=xml

    app_key=2100000826

    v=1.0

    sign_method=md5

    session=4ECBED3068CB782DC287FACCD52E06AB6E6F1CB4C63EF3372AC7CD88FE34C063

    oit=123abcde

    (2)系统级参数按照参数名称升序排列:

    app_key=2100000826

    format=xml

    method=dangdang.item.itemid.get

    session=4ECBED3068CB782DC287FACCD52E06AB6E6F1CB4C63EF3372AC7CD88FE34C063

    sign_method=md5

    timestamp=2013-05-06 13:52:03 (时间必须是当前+8区北京时间)

    v=1.0

    (3)连接字符串

    连接参数名与参数值,并在首尾加上secret,如下:

    5FDD35D3A94D73514CD6F1A5B58AED53app_key2100000826formatxmlmethoddangdang.item.itemid.getsession4ECBED3068CB782DC287FACCD52E06AB6E6F1CB4C63EF3372AC7CD88FE34C063sign_methodmd5timestamp2013-05-06 13:52:03v1.05FDD35D3A94D73514CD6F1A5B58AED53 (请注意参加签名的参数为:app_key、format、method、session、sign_method、timestamp、secret、v。其它参数不参加签名)

    (4)生成签名:

    32位大写MD5值->2D81422E364C783AA2998E0E612F82AA

    (5)拼装HTTP请求

    参数URLEncoding为UTF-8编码,然后拼装,通过浏览器访问该地址,即成功调用一次接口,如下:

    https://gw-api.dangdang.com/openapi/rest?v=1.0&sign=2D81422E364C783AA2998E0E612F82AA&sign_method=md5&timestamp=2013-05-06+13%3A52%3A03&app_key=2100000826&method=dangdang.item.itemid.get&format=xml&session=4ECBED3068CB782DC287FACCD52E06AB6E6F1CB4C63EF3372AC7CD88FE34C063&oit=123abcde

    5. 注意事项

    (1)所有的请求数据编码皆为UTF-8格式

    (2)所有的响应数据编码以实际content-type返回的编码集为准(一般为gbk)

    (3)请求成功时,由于各api返回节点不同,详细请参考具体api说明。

    (4)系统级请求失败时,返回格式为:

    <errorResponse>

    <errorCode>XXX</errorCode>

    <errorMessage>XXX</errorMessage>

    </errorResponse>

    参考错误码一览