前提

所有的请求和响应 必须都使用 utf-8 字符编码

喔噻平台的功能图

喔噻开票平台, 提供3种接口,分别为

1. 开票接口
2. 开票状态被动查询接口

以及 1 种, 主动推送的 Callback (webhook)

1. 开票结果主动通知 Callback

接入说明

• 第1步: 商户准备卖家纳税人识别号、开票卖家抬头、税率、商户简称、商户门店列表(商户门店唯一标识、商户简称、门店开票卖家抬头)；
• 第2步: 根据对接前准备开通自己的 开票应用,并获得 app_id
• 第3步: 提交商户资料，获取商户平台登录账号和密码,在对接前准备 通过 激活接口 签到接口

  进行获取 terminal_sn 和 terminal_key

• 第4步:

 如果是接口开票, 直接阅读 开票接口, 不需要阅读 二维码生成规范

 如果需要通过生成二维码进行开票
 应在开票前先基于 <发票二维码生成规范> 生成存有开票预确认 http 网页地址的<二维码>, 然后将二维码打印在收银票据上；
 用户可以使用移动终端, 访问扫描这个二维码, 访问商户应用网页, 进行开票前确认或补完信息, 然后再通过页面的按钮，发起开票请求，<商户应用后端>收到<商户应用前端(H5)>的开票请求后，整合必要的其他必要参数，再由应用后端向<喔噻电子发票平台>发起开票请求
 (二维码中的 "开票预确认" 的网页, 由商户应用层自行开发, 收钱吧仅提供 二维码生成规范)

• 第5步: 开发接收通知的接口，订阅收钱吧推送的开票结果信息。

开票

开票的时序图

开票接口

• 接口地址：{api_domain}/api/invoice/apply/v2
• 访问方式：post
• 签名校验：参照2.1.4
• 参数说明：

• 开票商品明细信息(invoice_items 中的每个 item)

• 折扣行相关说明：

  1.折扣行只能对应一行被折扣行，且折扣行必须在被折扣行下一行 2.折扣行与被折扣行“货物劳务名称”、“商品税收编码”、“商品规格型号”、“税率”需保持一致 3.冲红时，只需要将正常行和对应的折扣行金额相加取负值即可

• 蓝票参数示例：

{
    "client_sn": "testhyb",
    "client_task_sn": "testhyb001",
    "client_time": "1526011200000",
    "invoice_amount": "1044",
    "invoice_time": "2018-05-11 12:00:00",
    "invoice_type": "0",
    "notify_url": "http://uinvoice-alipay-morkserver.test.shouqianba.com/v2/push",
    "payer_email": "[email protected]",
    "payer_name": "feixiang",
    "payer_phone": "18014891021",
    "payer_register_no": "91500000747150346A",
    "sum_price": "900",
    "sum_tax": "144",
    "terminal_sn": "2100216260002212407",
    "apply_from": "0",
    "user_from": "2",
    "user_uid": "5e0bce11894311e7bcb0d0a637ea2ec3",
    "user_phone": "12323244323",
    "invoice_items": [{
        "amount": "1160",
        "item_name": "礼品卡",
        "item_no": "1040201080000000000",
        "price": "100",
        "quantity": "10",
        "row_type": "2",
        "specification": "Z",
        "sum_price": "1000",
        "tax": "160",
        "tax_rate": "0.16",
        "unit": "件"
    }, {
        "amount": "116",
        "item_name": "礼品卡",
        "item_no": "1040201080000000000",
        "row_type": "1",
        "sum_price": "100",
        "specification": "Z",
        "tax": "16",
        "tax_rate": "0.16"
    }]
}

• 红冲参数示例

  {
    "client_sn": "testhyb",
    "client_task_sn": "testhyb056",
    "client_time": "1526011200000",
    "invoice_amount": "-1044",
    "invoice_items": [
        {
            "amount": "-1160",
            "item_name": "礼品卡",
            "item_no": "1040201080000000000",
            "price": "100",
            "quantity": "-10",
            "row_type": "2",
            "specification": "Z",
            "sum_price": "-1000",
            "tax": "-160",
            "tax_rate": "0.16",
            "unit": "件"
        }, {
            "amount": "-116",
            "item_name": "礼品卡",
            "item_no": "1040201080000000000",
            "row_type": "1",
            "sum_price": "-100",
            "tax": "-16",
            "tax_rate": "0.16"
        }
    ],
    "invoice_time": "2018-05-11 12:00:00",
    "invoice_type": "1",
    "notify_url": "http://uinvoice-alipay-morkserver.test.shouqianba.com/v2/push",
    "payer_email": "[email protected]",
    "payer_name": "feixiang",
    "payer_phone": "18014891021",
    "payer_register_no": "91500000747150346A",
    "normal_invoice_code": "150003533340",
    "normal_invoice_no": "42018793",
    "sum_price": "-900",
    "sum_tax": "-144",
    "terminal_sn": "2100216260002212407",
    "apply_from": "0",
    "user_from": "2",
    "user_uid": "5e0bce11894311e7bcb0d0a637ea2ec3",
    "user_phone": "12323244323"
  }
  

  • 返回说明：

• 正常返回示例

{
    "biz_response": {
        "data": {
            "client_sn": "22000000012",
            "client_task_sn": "22000009989",
            "status": "SUCCESS",
            "task_sn": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "task_status": "CREATED"
        },
        "result_code": "INVOICE_SUCCESS"
    },
    "result_code": "200"
}

开票结果查询接口

• 接口地址：{api_domain}/api/invoice/query/v2
• 访问方式：post
• 签名校验：参照2.1.4
• 参数说明：

• 参数示例

{
    "terminal_sn": "2200000001",
    "client_sn": "22000000012",
    "client_task_sn": "22000009989",
    "task_sn":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

}

• 返回结果 进行中

{
    "result_code": "200",
    "biz_response": {
        "result_code": "INVOICE_IN_PROGRESS",
        "data": {
            "task_sn":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "client_sn": "22000000012",
            "client_task_sn": "22000009989",
            "terminal_sn":"2200000001"
        }
    }
}

• 返回结果 成功

{
    "result_code": "200",
    "biz_response": {
        "result_code": "SUCCESS",
        "data": {
            "terminal_sn":"2200000001",
            "task_sn":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "client_sn": "22000000012",
            "client_task_sn": "22000009989",
            "finish_time": "1492506702864",
            "invoice_date": "2017-01-12",
            "invoice_code": "150003528888",
            "invoice_no": "50877603",
            "anti_fake_code": "CF6B2F6168420008",
            "invoice_amount": "117000",
            "file_path":"demo",
            "payer_name": "发票抬头",
            "payer_mobile": "0512-55553333",
            "payer_phone": "0512-55553333",
            "user_phone:": "18268888888"
            "payer_email":"[email protected]",
            "payer_register_no": "9133010060913454XP",
            "invoice_type":"0",
            "reflect":reflect_struct
        }
    }
}

开票结果主动通知, 回调(web hook)规范, (被回调的接口由商户实现并提供)

这里的地址 , 已在 开票接口的 notify_url 中传入

商户提供接口接收 -> 收钱吧 开票成功（发票信息）或开票失败的通知信息。
开票完成后，收钱吧调用商户的接口推送开票结果信息，推送 1 次 商户返回带有 SUCCESS 的响应参数视为成功

• 回调接口地址：{user_callback_api_domain}/v2
• 回调请求类型：post
• 回调请求参数说明：

目前北京地区暂未开放对企业开具电子发票，若北京地区放开后，对于向企业开具的情况，付款方税务登记证号和名称也不能为空,注：根据国家税务总局公告2017年第16号公告，2017年7月1日起，增值税普通发票必须填写纳税人识别号，否则无法作为企业内部报销凭证。|varchar(20)|N|支持15、17、18、20位数字及字母，字母需小写。| |payer_name|发票抬头名称|string(100)|N|开票成功必传| |user_phone|消费者手机号|string(20)|Y| | |payer_phone|购买方电话|string(16)|N| | |payer_mobile|购买方电话(兼容旧接入系统，与payer_phone值相同)|string(16)|N| | |reflect|反射参数|string(64)|N|任何调用者希望原样返回的信息，可以用于关联商户ERP系统的订单或记录附加订单内容, 比如 { "tips": "200" }|

• 回调参数示例：

{
    "terminal_sn":"2200000001",
    "task_sn":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "client_sn": "22000000012",
    "client_task_sn": "22000009989",
    "finish_time": "1492506702864",
    "invoice_date": "2017-01-12",
    "invoice_code": "150003528888",
    "invoice_no": "50877603",
    "anti_fake_code": "CF6B2F6168420008",
    "invoice_amount": "117000",
    "file_path":"demo",
    "payer_name": "发票抬头",
    "payer_mobile": "0512-55553333",
    "payer_phone": "0512-55553333",
    "user_phone:": "18268888888"
    "payer_email":"[email protected]",
    "payer_register_no": "9133010060913454XP",
    "invoice_type":"0",
    "reflect":reflect_struct
}

• 回调返回说明：

  商户收到通知后应返回如下结果; 如果收钱吧未收到"成功"结果，或者没有调通回调接口。 不会重试，但开发者可以通过调用 query 接口进行自行补偿

• 回调返回示例：

{
    "result_code": "200",
    "biz_response": {
        "result_code": "SUCCESS",
        "data": "接收开票信息成功"
    }
}