# 电子发票 API（航信乐企版 v5.1）

## 1. 调用方式

- 正式环境：`https://erp.huapiaoer.com`
- 通信协议：HTTPS
- 请求方法：`POST`
- Content-Type：`application/json`
- 编码：UTF-8

---

## 2. 公共约定

### 2.1 公共请求参数

以下参数在多个接口中出现，此处统一说明。

| 参数名称 | 类型 | 必填 | 描述 | 适用接口 |
|---|---|---|---|---|
| `appsecret` | String | 是 | 票慧通提供 | 全部接口 |

> 注意：发票开具和生成开票二维码接口中，`b2cshopid` 位于 `head` 对象内（`head.b2cshopid`）。

---

### 2.2 公共响应格式

除授权订单号接口外，统一返回：

```json
{
  "code": "200",
  "data": {}
}
```

| 字段 | 类型 | 说明 |
|---|---|---|
| `code` | String | `"200"` 成功，`"400"` 失败 |
| `data` | String / Object | 业务数据 |

---

### 2.3 商品明细（details）结构

适用接口：

- 发票开具
- 生成开票二维码

| 参数名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| `details.goodscategory` | String | 否 | 商品大类（传值时不填 `taxcode`、`tax`） |
| `details.taxcode` | String | 否 | 税目编码（传值时不填 `goodscategory`） |
| `details.tax` | String | 否 | 税率（传值时不填 `goodscategory`） |
| `details.goodsname` | String | 是 | 商品名称 |
| `details.price` | Double | 是 | 商品单价（元） |
| `details.sl` | Double | 是 | 商品数量 |
| `details.attributes` | String | 否 | 商品规格型号 |
| `details.unitname` | String | 否 | 商品单位 |
| `details.discount` | Double | 否 | 折扣金额（元） |

> 生成开票二维码接口暂不支持 `discount`

---

### 2.4 发票类型编码

| 编码 | 发票类型 |
|---|---|
| `081` | 数电专票 |
| `082` | 数电普票 |

---

### 2.5 支付渠道编码

| 编码 | 支付渠道 |
|---|---|
| `01` | 现金 |
| `02` | 银行转账 |
| `03` | 票据 |
| `04` | 借记卡 |
| `05` | 信用卡 |
| `06` | 购物卡/券 |
| `07` | 优惠券 |
| `08` | 商场积分 |
| `09` | 支付宝 |
| `10` | 微信支付 |
| `11` | 云闪付 |
| `12` | Apple Pay |
| `13` | Samsung Pay |
| `99` | 其他 |

---

### 2.6 业务状态码汇总

| 接口 | code=200 | code=400 |
|---|---|---|
| 发票开具 | 开票中请稍等 | 开票失败 |
| 发票红冲 | 红冲中请稍等 | 红冲失败 |
| 发票通知、查询 | 订单查询成功 | 未查询到对应订单信息 |
| 发送邮件 | 发送成功 | 发送失败 |
| 生成开票二维码 | 成功 | 失败 |
| 企业搜索 | 成功 | 失败 |
| 查询开票人列表 | 成功 | 失败 |

> 授权订单号接口响应格式不同，不包含 `code` 字段。

---

# 3. 开票核心

## 3.1 查询开票人列表

### 接口地址

```text
/ewy_weberp/api/huapiaoer/outopenapis/getDrawerIdList
```

### 说明

查询当前企业下所有开票人列表。

### 请求参数

| 参数名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| `nsrsbh` | String | 是 | 开票方税号（商家税号） |

### 请求示例

```json
{
  "nsrsbh": "915001*******460R"
}
```

### 响应示例

```json
{
  "code": "200",
  "data": [
    {
      "issuerid": "186891*******4946",
      "name": "游* 2921"
    },
    {
      "issuerid": "186891*******5074",
      "name": "袁** 3713"
    }
  ]
}
```

---

## 3.2 授权订单号

### 接口地址

```text
/ewy_weberp/api/wechatPay/getWechatShopAuthorizeOrderId
```

### 说明

微信支付商户授权接口，在发起开票前调用。

> 注意：该接口响应格式不同于其他接口。

### 请求参数

| 参数名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| `omsoutputorderid` | String | 是 | 订单号（企业号 + 流水号） |
| `source` | String | 否 | 来源：`WEB` / `MINIPROGRAM` |
| `appid` | String | 是 | 商户 AppID |
| `openid` | String | 是 | 微信 OpenID |

### 请求示例

```json
{
  "omsoutputorderid": "1019000000000001",
  "appid": "wxa889d1c7e87524bd",
  "openid": "ozjEW5X1T2h9QK9omRUKD7Ij9X4Y"
}
```

### 响应示例

```json
{
  "wechatshop": true,
  "miniprogram_user_name": "gh_3610de7f9728",
  "miniprogram_appid": "wx1af4f6aa3a537c1a"
}
```

---

## 3.3 发票开具

### 接口地址

```text
/ewy_weberp/api/huapiaoer/outopenapis/openBlueInvoice
```

### 说明

开具蓝字发票。

### 核心请求参数

| 参数名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| `issuerid` | String | 否 | 开票人 ID |
| `tradeinfo.payType` | String | 是 | 支付渠道编码 |
| `tradeinfo.outTradeNo` | String | 是 | 支付流水号 |
| `head.companyid` | String | 否 | 企业号 |
| `head.kpje` | String | 是 | 开票总金额 |
| `head.orderId` | String | 是 | 开票订单号 |
| `head.b2cshopid` | String | 是 | 商家税号 |
| `head.invoicetitle` | String | 是 | 购方抬头 |
| `head.registrationnumber` | String | 否 | 购方税号 |
| `head.companyaddress` | String | 否 | 购方地址 |
| `head.mobilenumber` | String | 否 | 购方手机号 |
| `head.openaccountbank` | String | 否 | 银行名称 |
| `head.bankaccount` | String | 否 | 银行账号 |
| `head.remark` | String | 否 | 发票备注 |
| `head.recmail` | String | 否 | 接收邮箱 |
| `head.invoiceTypeCode` | String | 是 | 发票类型 |
| `details` | List | 是 | 商品明细 |

### 请求示例

```json
{
  "appsecret": "123456789",
  "issuerid": "1868914789939154946",
  "head": {
    "orderId": "1019000000000001",
    "b2cshopid": "914403008888888888",
    "invoicetitle": "深圳柯适科技有限公司",
    "registrationnumber": "91440300MA5FB8A214",
    "companyaddress": "深圳市 xxx 区 xxx 街道 xxx",
    "mobilenumber": "18888888888",
    "openaccountbank": "招商银行 xxx 支行",
    "bankaccount": "755944788888888",
    "remark": "结算方式 xxxxxx，合同编号 xxxxxx",
    "recmail": "1888888888@qq.com",
    "invoiceTypeCode": "082"
  },
  "details": [
    {
      "taxcode": "1030302000000000xxx",
      "tax": "0.13",
      "goodsname": "电子发票",
      "price": "1",
      "sl": 1,
      "attributes": "标准版",
      "unitname": "年"
    }
  ]
}
```

### 响应示例

```json
{
  "code": "200",
  "data": "订单生成成功！请让用户授权。",
  "orderId": "1019000000000001",
  "authorizeQRCode": "https://image.huapiaoer.com/xxx.png"
}
```

---

## 3.4 发票红冲

### 接口地址

```text
/ewy_weberp/api/huapiaoer/outopenapis/openRedInvoice
```

### 请求参数

| 参数名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| `orderId` | String | 是 | 发票订单号 |

### 请求示例

```json
{
  "appsecret": "123456789",
  "orderId": "1019000000000001"
}
```

### 响应示例

```json
{
  "code": "200",
  "data": "红冲中请稍等"
}
```

---

## 3.5 发票通知、查询

### 接口地址

```text
/ewy_weberp/api/huapiaoer/outopenapis/getInvoice
```

### 请求参数

| 参数名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| `orderId` | String | 是 | 航信订单号 |
| `invoicetype` | int | 是 | 1=蓝票，2=红票 |

### 响应字段

| 字段 | 说明 |
|---|---|
| `invoice_type_code` | 发票类型 |
| `mobilenumber` | 企业电话 |
| `invoicenature` | 抬头类型 |
| `ticket_date` | 开票日期 |
| `openaccountbank` | 开户行 |
| `bankaccount` | 开户账号 |
| `registrationnumber` | 税号 |
| `companyaddress` | 地址 |
| `invoicetitle` | 发票抬头 |
| `invoiceurl` | PDF 地址 |
| `ofdurl` | OFD 地址 |
| `xmlurl` | XML 地址 |
| `ticket_total_amount_has_tax` | 金额 |
| `invoicecode` | 发票代码 |
| `invoicenumber` | 发票号码 |

### 请求示例

```json
{
  "orderId": "1019000000000001",
  "invoicetype": 1
}
```

---

## 3.6 发送邮件

### 接口地址

```text
/ewy_weberp/api/huapiaoer/outopenapis/sendMail
```

### 请求参数

| 参数名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| `orderId` | String | 是 | 订单号 |
| `invoiceType` | int | 是 | 1=蓝票，2=红票 |
| `email` | String | 是 | 目标邮箱 |

### 请求示例

```json
{
  "orderId": "1019000000000001",
  "invoiceType": 1,
  "email": "1888888888@qq.com"
}
```

### 响应示例

```json
{
  "code": "200",
  "data": "ok"
}
```

---

## 3.7 生成开票二维码

### 接口地址

```text
/ewy_weberp/api/huapiaoer/outopenapis/getInvoiceQrcode
```

### 请求参数

| 参数名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| `head.orderId` | String | 是 | 开票订单号 |
| `head.b2cshopid` | String | 是 | 商家税号 |
| `head.remark` | String | 否 | 发票备注 |
| `head.invoiceTypeCode` | String | 是 | 发票类型 |
| `details` | List | 是 | 商品明细 |

### 响应字段

| 字段 | 说明 |
|---|---|
| `data.imgUrl` | 二维码图片地址 |
| `data.orderId` | 订单号 |

### 请求示例

```json
{
  "appsecret": "123456789",
  "head": {
    "orderId": "20240410000001",
    "b2cshopid": "91440300MA5FN0xxxx",
    "remark": "发票备注",
    "invoiceTypeCode": "082"
  }
}
```

### 响应示例

```json
{
  "code": "200",
  "data": {
    "imgUrl": "https://image.huapiaoer.com/xxxx.png",
    "orderId": "20240410000001"
  }
}
```

---

# 4. 辅助功能

## 4.1 企业搜索

### 接口地址

```text
/ewy_weberp/api/piaotong/platform/getInvoiceHeaderInquiry
```

### 说明

查询企业基本信息。

> 注意：官方文档说明“数据存在错误，仅供辅助”。

### 请求参数

| 参数名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| `enterpriseName` | String | 是 | 公司简称（4 个字符起生效） |

### 请求示例

```json
{
  "enterpriseName": "维克多信息"
}
```

### 响应示例

```json
{
  "code": "200",
  "data": [
    {
      "bankAccount": "4562878487282",
      "address": "深圳市南山区粤海街道海珠社区海德三道1236号大成基金总部大厦201",
      "telephone": "18070830426",
      "bankName": "中国银行",
      "taxpayerNum": "91440300MA5FB8A214",
      "enterpriseName": "深圳柯适科技有限公司"
    }
  ]
}
```
