在日常工作中，产品经理需要与多方进行沟通协作，那么掌握相关基础知识对于双方的沟通能够更加顺畅。本文总结了新手产品经理必学技术接口文档知识，方便进一步与开发技术进行协作，希望对你有所帮助。

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

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

一、什么是接口文档

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

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

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

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

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

二、接口工作原理

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

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

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

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

三、常规接入流程

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

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

签名参数有两种作用：

所以签名参数可以理解为是带有身份信息的通行证，有了签名参数，才能够正常请求接口，并且每次请求，接口提供方都能知道是谁发起了接口请求。

四、怎么看接口文档

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

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

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

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

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

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

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

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

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

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

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

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

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

我们可以找一下，发现接口文档中确实有一个【开票接口异步通知】的接口，点开发现这里返回的参数就非常多了，包括开票的状态，电子发票开票成功后电子发票的url等，收到相应的响应信息之后，我们需要只需要处理对应的信息即可，比如前端可能需要更新开票的状态，或者显示电子发票的下载入口等。

以上是个人的经验之谈，希望能够对刚入行的产品经理学习阅读接口文档有一定帮助，感谢阅读！

本文由 @产品锦李 原创发布于人人都是产品经理，未经许可，禁止转载。

题图来自Unsplash，基于CC0协议。

该文观点仅代表作者本人，人人都是产品经理平台仅提供信息存储空间服务。