2023年【经验分享】新手产品经理必学技术接口文档知识

【经验分享】新手产品经理必学技术接口文档知识产品经理需不需要懂技术接口文档？这个问题我觉得就跟问产品经理需不需要懂技术是一样的，而我的建议是，需要懂，但只需要有限度地懂。今日我结合之前的一些项目阅历，以对接电子发票中的开具发票接口为例，共享产品经理怎么学会看懂技术接口文档。

本文是以产品经理理解的角度去说明和解构接口文档，可能在技术角度未必是正确的，假如有卧底的开发大佬，还请勿喷！

一、什么是接口文档

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

随着开发技术的进展，慢慢进展成为前后端分别的开发方式，简洁讲就是前端开发工程师和后端开发工程师各自开发属于自己范围的内容，最终通过api接口来进行前后端信息的传递，而接口文档就是记录各个不同业务用到的api接口以及它们所传递的信息的技术文档。但这种文档一般是内部用的，因此可以说是纯粹为了开发服务，产品经理基本接触不到。

后来，随着业务形态的进展，在某些业务领域或技术领域有较强优势的公司会通过出售自身力量来获得销售的收入，比如支付力量、视频流媒体力量、AI力量等，使得购买的公司能够以最快的方式实现相应的力量，而实现这种力量的方式之一，就是通过开放api接口来进行对接，接口文档可以让产品经理和开发工程师快速对接业务和技术。

这么讲可能有点抽象，举个例子，比如我现在有一个商城产品，需要使用移动支付，但是我自己没有金融牌照，不能做在线收款的业务，而某公司有金融牌照，可以开发在线支付的功能并进行在线收款，该公司通过开放相关的技术接口，商城只需要根据接口对接完成，由该公司来进行代收代付，即可完成在线收款的功能，当然，该公司在此过程中可能会收取相应的费用，这种是属于有业务领域优势的类型。

另外一个例子，比如商城需要做一个在线直播的功能，但是目前公司没有在线视频流媒体等技术的专业开发人员和技术积累，而某公司则是在这方面有着多年的阅历和深厚的技术积累，因此我们可以购买接入该公司的服务，快速实现在线直播的功能，这种，则是属于有技术领域优势的类型。

二、接口工作原理

以下图片可以关心我们理解接口的工作原理：

我举一个例子，比如【接口开放方】开放了一个接口，接口名称为【你好】，接口要求供应【姓名】作为参数，并返回【某某某，你好】的内容，其中【某某某】是恳求接口时供应的【姓名】。

接口的交互用户是无法感知的，所以需要在用户端处理内容的输入和输出，比如在网页上放一个输入框，让用户输入姓名，假设用户输入【李雷】，点击确认，这个时候，【接口恳求方】恳求【你好】这个接口，并传递姓名【李雷】，接下来就会收到【接口开放方】响应回来的信息【李雷，你好】，此时再将收到的这句话通过弹窗之类的形式在用户端显示出来，这样就完成了一次接口的调用。

【接口恳求方】无需理睬【接口开放方】内部的实现方法，只需关注收到响应后如何处理响应即可（如上方例子中的将收到的信息通过弹窗形式显示出来），而处理响应一般涉及业务相关，所以需要产品经理介入，因此产品经理看文档的时候，需要知道，某个接口是为了实现什么功能（比如上方的“你好”接口会返回问好的文字），需要供应什么参数（如上方的“姓名”），会响应什么参数（如上方的“某某某，你好”的信息），收到响应后要怎么处理（一般跟接入方的业务有关）。

三、常规接入流程

这里讲的是常规的接入流程，不代表全部平台都是以这样的方式接入，以下是接入流程示意图：

不是拿到接口文档就可以接入，刚刚提到，接口供应方可能会根据某种方式来收取肯定的费用，所以接口的使用确定是需要在接口开放方的授权下才能进行，所以在完成商务谈判之后，一般接口供应方会要求接入方在他们平台注册账号，并通过技术手段给接入放安排相关签名参数。

签名参数有两种作用：

获得接入权限，相当于钥匙；携带身份信息，相当于身份证。所以签名参数可以理解为是带有身份信息的通行证，有了签名参数，才能够正常恳求接口，并且每次恳求，接口供应方都能知道是谁发起了接口恳求。

四、怎么看接口文档

刚刚讲的都是一些纯理论的东西，接下来我以某电子发票平台的接口文档为例，讲讲假如我所在的平台需要增加一个开具电子发票的功能，在收到接口文档之后，要怎么看。

这是接口文档的名目，在收到文档之后，建议先看介绍，这里面一般会涉及到当前对接的这个产品的说明、实现功能、适用场景等，产品经理需要结合自身产品的业务分析要对接的产品的功能和适用场景是否符合公司想要实现的业务。

接下来是【调用方式】中的【签名方法】，这个需要分状况，假如你的平台是自己对接，自己使用，作为产品经理可以不用看这块，但是假如你做的SaaS系统，你的平台可能会入驻多名商户，每名商户都需要去接口供应方平台注册并供应签名参数，你不行能每次有新入驻的商户就让开发工程师往数据库里加数据，最合理的解决方案就是在后台设计一个商户管理功能，在商户管理功能中增加签名参数的填写，这个时候，作为产品经理你就必需得知道，这个平台需要供应哪些签名参数，从而支撑你完成这块功能的设计，比如这个发票平台的签名参数要求供应以下4个参数：

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

接下来是“主菜”，在api列表中，一般会根据不同的业务功能划分不同的接口，并以对应的业务描述来命名接口，因此，我们假如要设计开具发票的功能，需要先找到对应的接口：

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

口说明：这里面一般会有一些比较重要的信息，肯定要先认真阅读，有些产品经理一上来就跳过接口说明的内容，直接看接口参数，然后遇到问题解决不了，始终在原地转圈，结果发觉人家已经在接口说明中说了会遇到什么问题，是什么缘由，怎么解决。

恳求参数：这个是产品经理需要重点关注的内容，这里面涉及到在调用这个接口的时候需要供应什么参数，这些参数往往都是用户输入的，因此产品经理需要依据所需参数在用户端收集相应的信息，如以下关于开具发票接口的部分恳求参数：

这里面我们要关注的，主要是【是否必填】以及【描述】，描述中会说明这个参数是什么，有什么要求，这里肯定要区分好哪些参数是技术需要的，哪些参数是业务需要的，产品经理要重点关注业务参数，假如不清晰参数的用途，可以找接口供应方的供应关心。

有一些相应的校验需要产品经理在用户端收集信息的时候就做好要求，防止提交给接口的参数是不符合要求的，这样会铺张网络资源（每次恳求都需要等待回复，假如多次尝试失败，会让用户觉得体验不好），甚至铺张金钱（有些平台会根据接口恳求的次数收费，恳求一次扣一次费用）。

响应参数：这是恳求接口之后，接口供应方回传给我们的参数，一般会包含状态和对应的参数，如下是开具发票的响应参数：

但是这里有点惊奇，我们假如申请开具电子发票，至少要把电子发票的文件给我们吧，不然我们怎把文件给用户，这时候我们认真看一下，原来开票的接口是通过异步通知我们的，这里就需要区分什么同步什么是异步了。

一般我们提交之后，可以立刻反馈给我们的就是同步通知，比如这里的状态，告知我们已经提交胜利了或者已经开过票了。而异步通知是说，我们恳求的这个接口需要的一部分内容，需要等待接口供应方处理，处理完之后再告知我们结果，比如这里，开具发票申请提交胜利，但是开票平台需要同步税务局的系统进行开票，这里需要有一个处理的时间，要等它处理完之后再告知我们结果。

我们可以找一下，发觉接口文档中的确有一个【开票接