新手产品经理必学技术接口文档知识

新手产品经理必学技术接口文档知识

产品经理需不需要懂技术接口文档？这个同题我觉得就跟问产品经理

需不需要懂技术是一样的，而我的建议是，需要懂，但只需要有限度地

懂。今天我结合之前的一些项目经验，以对接电子发票中的开具发票接

口为例，分享产品经理怎么学会看懂技术接口文档。

本文是以产品经理理解的角度去说明和解构接口文档，可能在技术角度

未必是正确的，如果有卧底的开发大佬，还请勿喷！

一.什么是接口文档

要学会看接口文档，首先得明白什么是接口文档，接口文档的作用是什

么。

随着开发技术的发展，渐渐发展成为前后端分离的开发方式，简单讲就

是前端开发工程师和后端开发工程师各自开发属于自己范围的内容，最

后通过api接口来进行前后端信息的传递,而接口文档就是记录各个

不同业务用到的api接口以及它们所传递的信息的技术文档。但这种

文档一般是内部用的，因此可以说是纯粹为了开发服务，产品经理基本

接触不到。

后来，随着业务形态的发展，在某些业务领域或技术领域有较强优势的

公司会通过出售自身能力来获得销售的收入，比如支付能力、视频流媒

体能力、AI能力等，使得购买的公司能够以最快的方式实现相应的能

力，而实现这种能力的方式之一，就是通过开放api接口来进行对接，

接口文档可以让产品经理和开发工程师快速对接业务和技术。

这么讲可能有点抽象，举个例子，比如我现在有一个商城产品，需要使

用移动支付，但是我自己没有金融牌照，不能做在线收款的业务，而某

公司有金融牌照，可以开发在线支付的功能并进行在线收款，该公司通

过开放相关的技术接口，商城只需要按照接口对接完成，由该公司来进

行代收代付，即可完成在线收款的功能，当然，该公司在此过程中可能

会收取相应的费用，这种是属于有业务领域优势的类型。

另外一个例子，比如商城需要做一个在线直播的功能，但是目前公司没

有在线视频流媒体等技术的专业开发人员和技术积累，而某公司则是在

这方面有着多年的经验和深厚的技术积累，因此我们可以购买接入该公

司的服务，快速实现在线直播的功能，这种，则是属于有技术领域优势

的类型。

二、接口工作原理

以下图片可以帮助我们理解接口的工作原理:

接口接入方

请求接匚

携带参差

响应

携带参数

处理响£

我举一个例子，比如【接口开放方】开放了一个接口，接口名称为【你

好】，接口要求提供【姓名】作为参数，并返回【某某某，你好】的内

容，其中【某某某】是请求接口时提供的【姓名】。

接口的交互用户是无法感知的，所以需要在用户端处理内容的输入和输

出，比如在网页上放一个输入框，让用户输入姓名，假设用户输入【李

雷】，点击确认，这个时候，【接口请求方】请求【你好】这个接口，

并传递姓名【李雷】，接下来就会收到【接口开放方】响应回来的信息

【李雷，你好】，此时再将收到的这句话通过弹窗之类的形式在用户端

显示出来，这样就完成了一次接口的调用。

【接口请求方】无需理会【接口开放方】内部的实现方法，只需关注收

到响应后如何处理响应即可（如上方例子中的将收到的信息通过弹窗形

式显示出来），而处理响应一般涉及业务相关，所以需要产品经理介入，

因此产品经理看文档的时候，需要知道，某个接口是为了实现什么功能

（比如上方的〃你好〃接口会返回问好的文字），需要提供什么参数（如

上方的〃姓名〃），会响应什么参数（如上方的〃某某某，你好〃的信

息），收到响应后要怎么处理（一般跟接入方的业务有关）。

三、常规接入流程

这里讲的是常规的接入流程，不代表所有平台都是以这样的方式接入,

以下是接入流程不意图：

接入放在开放方平台

注册账号

上线

不是拿到接口文档就可以接入，刚刚提到，接口提供方可能会按照某种

方式来收取一定的费用，所以接口的使用肯定是需要在接口开放方的授

权下才能进行，所以在完成商务谈判之后，一般接口提供方会要求接入

方在他们平台注册账号，并通过技术手段给接入放分配相关签名参数。

签名参数有两种作用：

1.获得接入权限，相当于钥匙；

2.携带身份信息，相当于身份证。

所以签名参数可以理解为是带有身份信息的通行证，有了签名参数，才

能够正常请求接口，并且每次请求，接口提供方都能知道是谁发起了接

口请求。

四.怎么看接口文档

刚刚讲的都是一些纯理论的东西，接下来我以某电子发票平台的接口文

档为例，讲讲如果我所在的平台需要增加一个开具电子发票的功能，在

收到接口文档之后，要怎么看。

产品介绍▼

产品介绍

平台指引

接入指引

API文档▼

调用方式▼

签名方法

SDK中心

请求概述

错误码

开票服务相关接口▼

发票开具、打印》

发票申领、分发、余量查询►

发票通知、查询►

多场景开票►

红字信息表►

附录►

发票统计服务相关接口►

商户服务相关接口►

全电发票相关接口►

服务协议►

这是接口文档的目录，在收到文档之后，建议先看介绍，这里面一般会

涉及到当前对接的这个产品的说明、实现功能、适用场景等，产品经理

需要结合自身产品的业务分析要对接的产品的功能和适用场景是否符

合公司想要实现的业务。

接下来是【调用方式】中的【签名方法】，这个需要分情况，如果你的

平台是自己对接，自己使用，作为产品经理可以不用看这块，但是如果

你做的SaaS系统，你的平台可能会入驻多名商户，每名商户都需要去

接口提供方平台注册并提供签名参数，你不可能每次有新入驻的商户就

让开发工程师往数据库里加数据，最合理的解决方案就是在后台设计一

个商户管理功能，在商户管理功能中增加签名参数的填写，这个时候,

作为产品经理你就必须得知道，这个平台需要提供哪些签名参数，从而

支撑你完成这块功能的设计，比如这个发票平台的签名参数要求提供以

下4个参数：

叁数名称类型必选描述

是

algorithmString签名算法，支持RSA-SHA256和HI4AC-SHA256,区分大〃写HM

是

appkeyString,IDgj

是

nonceInteger6位随机数字398

是

timestampInteger秒级时间戳，过期时间5分钟159

那么你在设计时，就需要提供相应参数的输入。

接下来是〃主菜〃，在api列表中，一般会按照不同的业务功能划分

不同的接口，并以对应的业务描述来命名接口，因此，我们如果要设计

开具发票的功能，需要先找到对应的接口：

产品介绍▼

产品介绍

平台指引

接入指引

API文档▼

调用方式▼

签名方法

SDK中心

请求概述

错误码

开票服务相关接口▼

发票开具、打印▼

二手车发票开具

发票作废

发票开具

发票打印

发票红冲

机动车发票开具

发票申领、分发、余量查询►

发票通知、查询►

多场景开票►

红字信息表►

附录►

发票统计服务相关接口►

商户服务相关接口►

全电发票相关接口►

点击对应接口后，就可以看到接口的详情，以下是作为产品经理需要关

注的几个点：

口说明：这里面一般会有一些比较重要的信息，一定要先仔细阅读，有

些产品经理一上来就跳过接口说明的内容，直接看接口参数，然后遇到

问题解决不了，一直在原地转圈，结果发现人家已经在接口说明中说了

会遇到什么问题，是什么原因，怎么解决。

接口说明

使用一二放平台开具发票时，需要先充值并购买相应的资源包（如单机版或者托管等），再绑定税盘

管家；

1.本接口支持开具增值税电子普票、增值税纸质普通发票、增值税电子专票、增值税专用

2.开具纸票时此接口只返回开具数据，名氏票打印请查看【发票打印e】接口。

3.测试环境仅提供区块链电子发票开具，如需测试纸质发票开具或打印，可通过线上环境

请求参数：这个是产品经理需要重点关注的内容，这里面涉及到在调用

这个接口的时候需要提供什么参数，这些参数往往都是用户输入的，因

此产品经理需要根据所需参数在用户端收集相应的信息，如以下关于开

具发票接口的部分请求参数：

#请求参数

最大

必长度

参数名称类型描述

填（宇

节）

销方名称（销方票面信息）：如果1

根据填入信息填入票面，如果不显

seller_namestring否100默认读取商户平台销方企业名称显

称不含有特殊符号：转义符*'

‘逗号'空格等特殊符号】

销方纳税人识别号（销方票面信息;

统一社会信用代码（一般是15、17

sellerjaxpayernumstring是20

20位长度位数字或大写字母，字母I

S、V、Z除外）

销方地址（销方票面信息）：如果1

根据填入信息填入票面，如果不显

seller_addressstring否100默认读取商户平台销方企业地址显

注意：地址与电话加起来长度R00

不含换行符、制表符等特殊字符】

销方电话（销方票面信息）：如果j

根据填入信息填入票面，如果不乱

sellerjelstring否20默认读取商户平台销方企业电话显

话支持分机残（使用英文括残），二

行符、制表符等特殊字符】

销方银行名称（销方票面信息）:W

入则根据填入信息填入票面，如果:

入，则默认读取商户平台销方企业1

seller_bank_namestring否100

注意：银行与帐号加起来长度R00

不含换行符、制表符等特殊字符】

这里面我们要关注的，主要是【是否必填】以及【描述】，描述中会说

明这个参数是什么，有什么要求，这里一定要区分好哪些参数是技术需

要的，哪些参数是业务需要的，产品经理要重点关注业务参数，如果不

清楚参数的用途，可以找接口提供方的提供帮助。

有一些相应的校验需要产品经理在用户端收集信息的时候就做好要求，

防止提交给接口的参数是不符合要求的，这样会浪费网络资源（每次请

求都需要等待回复，如果多次尝试失败，会让用户觉得体验不好），甚

至浪费金钱（有些平台会按照接口请求的次数收费，请求一次扣一次费

用）。

响应参数：这是请求接口之后，接口提供方回传给我们的参数，一段会

包含状态和对应的参数，如下是开具发票的响应参数：

响应参数

字段类型备注

开票状态

曰1:已提交（如果订单已逑交开票请求并且没有开票成功,平台会根据策略

9正裁果会通过异步通知I邮箱等方式返回，也可以通过查询接口手动进彳

2：已开票成功（表示已经成功开过票了，不能再进行重复开票）

order_snstring是亍商户订单号：开发者商户订单号对应自亍商户订单唯一标识

invoicejdstring是发票标识：■・唯一识SU号

但是这里有点奇怪，我们如果申请开具电子发票，至少要把电子发票的

文件给我们吧，不然我们怎把文件给用户，这时候我们仔细看一下，原

来开票的接口是通过异步通知我们的，这里就需要区分什么同步什么是

异步了。

一般我们提交之后，可以马上反馈给我们的就是同步通知，比如这里的

状态，告诉我们已经提交成功了或者已经开过票了。而异步通知是说,

我们请求的这个接口需要的一部分内容，需要等待接口提供方处理，处

理完之后再告诉我们结果，比如这里，开具发票申请提交成功，但是开

票平台需要同步税务局的系统进行开票，这里需要有一个处理的时间，

要等它处理完之后再告诉我们结果。

我们可以找一下，发现接口文档中确实有一个【开票接口异步通知】的

接口，点开发现这里返回的参数就非常多了，包括开票的状态，电子发

票开票成功后电子发票的url等，收到相应的响应信息之后，我们需要

只需要处理对应的信息即可，比如前端可能需要更新开票的状态，或者

显示电子发票的下载入口等。

接入指引appkey是string32

API文档▼

message是string100

调用方式▼

是

签名方法notifyjypestring20

SDK中心

是

请求概述notifyJimestring20

错误码是

orderJdstring64

开票服务相关接口▼

是

发票开具、打印▼g_unique_idstring64

二手车发票开具

order_sn是string64

发票作废

是

ticket_snstring8

发票开具

是

发票打印ticket_codestring12

发票红冲ticket_date是string20

机动车发票开具

发票申领、分发、余量查询►

发票通知、查询▼

ticket_status是string1

作废结果异步通知

开具发票查询

开票结果异步通知