开票信息快查 API(invoice.companySearch)

输入企业名称,即可取回该企业的开票资料(购买方信息): 公司名称、纳税人识别号、注册地址、注册电话、开户银行与银行账号。 适合电商 / 本地生活 / SaaS 等需要让客户自助填写抬头并开发票的场景—— 用户填公司名,你直接拿到规范字段去开票,不用再手动核对税号、开户行。 上游结果原样透传:只命中一家时为对象,模糊命中多家时为数组。 接口编码 invoice.companySearch,仅需请求头 X-API-Key。

0.0100 元/次 GET JSON / UTF-8 免签名 0.01 元/次 查不到不收费

当前收费方式:PER_CALL(按次计费,0.0100 元/次)(后台「接口管理」可随时调整)

最后更新: · 接口版本 v1

接口概述

一句话说明

invoice.companySearch 是「按企业名取开票资料」的接口: 传入客户填写的企业名称,返回可直接用于开票的购买方开票资料(上游结果原样透传, 命中多家时为数组),不必再让用户逐项手填税号、开户行,也不必担心填错导致发票作废。

接口规格
请求地址https://api.xujian.tech/openapi/invoice/companySearch
请求方式 GET(companyName 放 Query String)
鉴权方式请求头 X-API-Key
接口编码invoice.companySearch
收费类型PER_CALL(按次计费,0.0100 元/次)
计费特殊规则 查得计费:companyName 缺失、上游不可用、未查询到该企业的开票信息时, 返回失败且不扣费
响应格式JSON,Content-Type: application/json;charset=UTF-8
是否需要授权 否(无需授权,API Key 有效且余额充足即可调用)
典型用途电商 / 本地生活开票抬头自动带出、企业采购下单、SaaS 发票管理、财务对账

快速开始

cURL
# 按企业名称查开票资料
curl -s -G "https://api.xujian.tech/openapi/invoice/companySearch" \
  --data-urlencode "companyName=示例科技有限公司" \
  -H "X-API-Key: 你的APIKey"

companyName 怎么填

companyName 是客户输入的企业全称 / 营业执照名称,必填。 名称越接近营业执照全称,命中率越高;若上游无该企业的开票记录,接口会返回失败且不计费。

请求参数

请求头(Header)
参数名类型必填说明
X-API-KeyString是开发者 API Key
业务参数(Query String)
参数名类型必填默认值示例说明
companyNameString是—示例科技有限公司 企业名称(建议用营业执照全称);缺失或查不到该企业的开票信息时返回失败且不计费

响应参数

data —— 上游原始结果(原样透传)

data 是上游返回结果的原样透传: 只命中一家时为对象,模糊命中多家时为数组。 平台不做字段映射、不做择优、不裁剪字段。

字段类型示例说明
dataObject 或 Array—上游原始结果:单条为对象,多条为数组
data[].nameString示例科技有限公司企业名称(购买方名称)
data[].taxNoString91110108MA01C2X3Y4纳税人识别号(统一社会信用代码 / 税号)
data[].addressString北京市海淀区中关村大街1号示例大厦8层注册地址(开票用注册地址,可能含省市区与街道门牌)
data[].phoneString010-88886666注册电话(开票用联系电话)
data[].bankNameString招商银行股份有限公司北京中关村支行开户银行(开户行名称,可能含支行)
data[].bankAccountString110902012810888银行账号(对公账号)

公共字段

字段类型说明
apiCodeString接口编码 invoice.companySearch
apiNameString接口名称
chargeTypeString计费类型
balanceBigDecimal 调用完成后(已扣费)的账户余额(元)
costMsLong本次调用耗时(毫秒)

口径与边界提示

① data 为上游原始结果原样透传,字段名为上游命名 (name / taxNo / address / phone / bankName / bankAccount),可直接带入发票;
② 上游按企业名称模糊搜索,命中多家时 data 是数组, 请按 name / taxNo 自行取用需要的那一条;
③ 个别企业可能缺失其中某几项(如未登记开户行、无联系电话),展示前请做判空;
④ 请核对 companyName 与营业执照一致,名称偏差可能导致查不到或命中多家。

响应示例

成功(code = 0)

JSON
{
  "code": 0,
  "msg": "success",
  "data": {
    "data": [
      {
        "address": "北京市海淀区中关村大街1号示例大厦8层",
        "bankAccount": "110902012810888",
        "bankName": "招商银行股份有限公司北京中关村支行",
        "name": "示例科技有限公司",
        "phone": "010-88886666",
        "taxNo": "91110108MA01C2X3Y4"
      },
      {
        "address": "上海市浦东新区世纪大道100号示例中心5层",
        "bankAccount": "1001234509001234567",
        "bankName": "中国工商银行股份有限公司上海分行营业部",
        "name": "示例科技(上海)有限公司",
        "phone": "",
        "taxNo": "91310115MA1K3XXXXX"
      }
    ],
    "apiCode": "invoice.companySearch",
    "apiName": "开票信息快查",
    "chargeType": "PER_CALL",
    "balance": 99.9900,
    "costMs": 310
  }
}

失败(缺少 companyName)—— 不收费

JSON
{
  "code": 500,
  "msg": "companyName 不能为空(企业名称)",
  "data": null
}

失败(查不到企业开票信息)—— 不收费

JSON
{
  "code": 500,
  "msg": "未查询到该企业的开票信息,请核对企业名称后重试;本次调用不计费",
  "data": null
}

错误码与常见失败原因

codemsg(示例)处理建议
0success调用成功
500缺少请求头 X-API-Key补充 X-API-Key
500API Key 无效 / API Key 已停用检查 Key 或重新启用
500客户不存在或已停用联系平台(可联系微信xujian_cq)
500接口不存在或已停用确认 invoice.companySearch 当前是否维护中
500 余额不足,请先充值。可联系微信xujian_cq 充值后重试,余额不足不扣费
500开票信息快查服务未启用 / 数据服务未配置平台侧配置问题,联系平台处理;不计费
500 companyName 不能为空(企业名称) 补齐 companyName;不计费
500未查询到该企业的开票信息,请核对企业名称后重试;本次调用不计费确认企业名称与营业执照一致;不计费
500数据服务暂时不可用(请求上游超时或网络异常),本次调用不计费稍后重试;不计费

多语言代码示例

Java(Hutool)

Java
String body = HttpRequest.get("https://api.xujian.tech/openapi/invoice/companySearch")
        .form("companyName", "示例科技有限公司")
        .header("X-API-Key", apiKey)
        .timeout(15000)
        .execute()
        .body();

JSONObject json = JSONUtil.parseObj(body);
if (json.getInt("code") != 0) {
    System.out.println("查询失败(不收费):" + json.getStr("msg"));
    return;
}
// data 可能为对象(命中一家)或数组(命中多家),这里统一按数组处理
Object raw = json.getJSONObject("data").get("data");
JSONArray list = raw instanceof JSONArray ? (JSONArray) raw : JSONUtil.createArray().put(raw);
for (Object o : list) {
    JSONObject item = (JSONObject) o;
    System.out.println("公司名称:" + item.getStr("name"));
    System.out.println("税号:" + item.getStr("taxNo"));
    System.out.println("开户行:" + item.getStr("bankName"));
    System.out.println("账号:" + item.getStr("bankAccount"));
}

Python

Python
import requests


def get_invoice_info(api_key: str, company_name: str) -> list:
    """按企业名称查开票资料;返回候选企业列表(可能多家),查不到返回空列表且不扣费"""
    resp = requests.get(
        "https://api.xujian.tech/openapi/invoice/companySearch",
        params={"companyName": company_name},
        headers={"X-API-Key": api_key},
        timeout=20,
    )
    result = resp.json()
    if result.get("code") != 0:
        print("查询失败(不收费):", result.get("msg"))
        return []
    data = result["data"]["data"]
    # 命中一家时为 dict,命中多家时为 list,统一成 list
    return data if isinstance(data, list) else [data]


if __name__ == "__main__":
    for info in get_invoice_info("你的APIKey", "示例科技有限公司"):
        print(info["name"], info["taxNo"], info["bankAccount"])

JavaScript(浏览器 / Node 18+)

JavaScript
const params = new URLSearchParams({ companyName: "示例科技有限公司" });

const resp = await fetch(`https://api.xujian.tech/openapi/invoice/companySearch?${params}`, {
  headers: { "X-API-Key": API_KEY },
});

const { code, msg, data } = await resp.json();
if (code === 0) {
  // 命中一家时为对象,命中多家时为数组,统一成数组
  const list = Array.isArray(data.data) ? data.data : [data.data];
  for (const info of list) {
    console.log(info.name, info.taxNo, info.bankAccount);
  }
} else {
  console.warn("查询失败(不收费):", msg);
}

常见问题(FAQ)

invoice.companySearch 接口怎么收费?

invoice.companySearch 的收费类型为 PER_CALL(按次计费),当前单价 0.0100 元/次,调用前校验余额,余额不足返回「余额不足,请先充值。可联系微信xujian_cq」且不扣费;充值可可联系微信xujian_cq。扣费金额、交易前后余额均记录于交易流水中。

companyName 必填吗?怎么提高命中率?

必填。companyName 是客户输入的企业名称,建议用营业执照全称; 名称越接近全称,命中率越高。不传或传空会直接返回失败且不计费。

返回哪些字段?够开发票用吗?

data 是上游结果的原样透传,开票所需的购买方信息都在里面: name(公司名称)、taxNo(纳税人识别号)、address(注册地址)、 phone(注册电话)、bankName(开户银行)、bankAccount(银行账号), 可直接带入增值税发票,无需用户逐项手填。命中多家时 data 为数组,请按 name / taxNo 自行取用。

没有查到企业开票信息会扣费吗?

不会。接口采用「先预鉴权、查到开票信息后再扣费」的两段式流程, companyName 缺失、上游不可用、未查询到该企业的开票信息时,返回失败且不扣费、不写扣费流水。

调用需要签名或加密吗?

不需要。XAPI 的接口仅校验请求头 X-API-Key,不做签名、时间戳或加密。

扫码添加微信
联系作者 · 微信二维码

微信号:xujian_cq

接口对接、充值 / 授权、定制需求都可以直接聊