新手產(chǎn)品經(jīng)理必學(xué)技術(shù)接口文檔知識

產(chǎn)品經(jīng)理需不需要懂技術(shù)接口文檔？這個(gè)同題我覺得就跟問產(chǎn)品經(jīng)理

需不需要懂技術(shù)是一樣的，而我的建議是，需要懂，但只需要有限度地

懂。今天我結(jié)合之前的一些項(xiàng)目經(jīng)驗(yàn)，以對接電子發(fā)票中的開具發(fā)票接

口為例，分享產(chǎn)品經(jīng)理怎么學(xué)會(huì)看懂技術(shù)接口文檔。

本文是以產(chǎn)品經(jīng)理理解的角度去說明和解構(gòu)接口文檔，可能在技術(shù)角度

未必是正確的，如果有臥底的開發(fā)大佬，還請勿噴！

一.什么是接口文檔

要學(xué)會(huì)看接口文檔，首先得明白什么是接口文檔，接口文檔的作用是什

么。

隨著開發(fā)技術(shù)的發(fā)展，漸漸發(fā)展成為前后端分離的開發(fā)方式，簡單講就

是前端開發(fā)工程師和后端開發(fā)工程師各自開發(fā)屬于自己范圍的內(nèi)容，最

后通過api接口來進(jìn)行前后端信息的傳遞,而接口文檔就是記錄各個(gè)

不同業(yè)務(wù)用到的api接口以及它們所傳遞的信息的技術(shù)文檔。但這種

文檔一般是內(nèi)部用的，因此可以說是純粹為了開發(fā)服務(wù)，產(chǎn)品經(jīng)理基本

接觸不到。

后來，隨著業(yè)務(wù)形態(tài)的發(fā)展，在某些業(yè)務(wù)領(lǐng)域或技術(shù)領(lǐng)域有較強(qiáng)優(yōu)勢的

公司會(huì)通過出售自身能力來獲得銷售的收入，比如支付能力、視頻流媒

體能力、AI能力等，使得購買的公司能夠以最快的方式實(shí)現(xiàn)相應(yīng)的能

力，而實(shí)現(xiàn)這種能力的方式之一，就是通過開放api接口來進(jìn)行對接，

接口文檔可以讓產(chǎn)品經(jīng)理和開發(fā)工程師快速對接業(yè)務(wù)和技術(shù)。

這么講可能有點(diǎn)抽象，舉個(gè)例子，比如我現(xiàn)在有一個(gè)商城產(chǎn)品，需要使

用移動(dòng)支付，但是我自己沒有金融牌照，不能做在線收款的業(yè)務(wù)，而某

公司有金融牌照，可以開發(fā)在線支付的功能并進(jìn)行在線收款，該公司通

過開放相關(guān)的技術(shù)接口，商城只需要按照接口對接完成，由該公司來進(jìn)

行代收代付，即可完成在線收款的功能，當(dāng)然，該公司在此過程中可能

會(huì)收取相應(yīng)的費(fèi)用，這種是屬于有業(yè)務(wù)領(lǐng)域優(yōu)勢的類型。

另外一個(gè)例子，比如商城需要做一個(gè)在線直播的功能，但是目前公司沒

有在線視頻流媒體等技術(shù)的專業(yè)開發(fā)人員和技術(shù)積累，而某公司則是在

這方面有著多年的經(jīng)驗(yàn)和深厚的技術(shù)積累，因此我們可以購買接入該公

司的服務(wù)，快速實(shí)現(xiàn)在線直播的功能，這種，則是屬于有技術(shù)領(lǐng)域優(yōu)勢

的類型。

二、接口工作原理

以下圖片可以幫助我們理解接口的工作原理:

接口接入方

請求接匚

攜帶參差

響應(yīng)

攜帶參數(shù)

處理響￡

我舉一個(gè)例子，比如【接口開放方】開放了一個(gè)接口，接口名稱為【你

好】，接口要求提供【姓名】作為參數(shù)，并返回【某某某，你好】的內(nèi)

容，其中【某某某】是請求接口時(shí)提供的【姓名】。

接口的交互用戶是無法感知的，所以需要在用戶端處理內(nèi)容的輸入和輸

出，比如在網(wǎng)頁上放一個(gè)輸入框，讓用戶輸入姓名，假設(shè)用戶輸入【李

雷】，點(diǎn)擊確認(rèn)，這個(gè)時(shí)候，【接口請求方】請求【你好】這個(gè)接口，

并傳遞姓名【李雷】，接下來就會(huì)收到【接口開放方】響應(yīng)回來的信息

【李雷，你好】，此時(shí)再將收到的這句話通過彈窗之類的形式在用戶端

顯示出來，這樣就完成了一次接口的調(diào)用。

【接口請求方】無需理會(huì)【接口開放方】內(nèi)部的實(shí)現(xiàn)方法，只需關(guān)注收

到響應(yīng)后如何處理響應(yīng)即可（如上方例子中的將收到的信息通過彈窗形

式顯示出來），而處理響應(yīng)一般涉及業(yè)務(wù)相關(guān)，所以需要產(chǎn)品經(jīng)理介入，

因此產(chǎn)品經(jīng)理看文檔的時(shí)候，需要知道，某個(gè)接口是為了實(shí)現(xiàn)什么功能

（比如上方的〃你好〃接口會(huì)返回問好的文字），需要提供什么參數(shù)（如

上方的〃姓名〃），會(huì)響應(yīng)什么參數(shù)（如上方的〃某某某，你好〃的信

息），收到響應(yīng)后要怎么處理（一般跟接入方的業(yè)務(wù)有關(guān)）。

三、常規(guī)接入流程

這里講的是常規(guī)的接入流程，不代表所有平臺都是以這樣的方式接入,

以下是接入流程不意圖：

接入放在開放方平臺

注冊賬號

上線

不是拿到接口文檔就可以接入，剛剛提到，接口提供方可能會(huì)按照某種

方式來收取一定的費(fèi)用，所以接口的使用肯定是需要在接口開放方的授

權(quán)下才能進(jìn)行，所以在完成商務(wù)談判之后，一般接口提供方會(huì)要求接入

方在他們平臺注冊賬號，并通過技術(shù)手段給接入放分配相關(guān)簽名參數(shù)。

簽名參數(shù)有兩種作用：

1.獲得接入權(quán)限，相當(dāng)于鑰匙；

2.攜帶身份信息，相當(dāng)于身份證。

所以簽名參數(shù)可以理解為是帶有身份信息的通行證，有了簽名參數(shù)，才

能夠正常請求接口，并且每次請求，接口提供方都能知道是誰發(fā)起了接

口請求。

四.怎么看接口文檔

剛剛講的都是一些純理論的東西，接下來我以某電子發(fā)票平臺的接口文

檔為例，講講如果我所在的平臺需要增加一個(gè)開具電子發(fā)票的功能，在

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

產(chǎn)品介紹▼

產(chǎn)品介紹

平臺指引

接入指引

API文檔▼

調(diào)用方式▼

簽名方法

SDK中心

請求概述

錯(cuò)誤碼

開票服務(wù)相關(guān)接口▼

發(fā)票開具、打印》

發(fā)票申領(lǐng)、分發(fā)、余量查詢?

發(fā)票通知、查詢?

多場景開票?

紅字信息表?

附錄?

發(fā)票統(tǒng)計(jì)服務(wù)相關(guān)接口?

商戶服務(wù)相關(guān)接口?

全電發(fā)票相關(guān)接口?

服務(wù)協(xié)議?

這是接口文檔的目錄，在收到文檔之后，建議先看介紹，這里面一般會(huì)

涉及到當(dāng)前對接的這個(gè)產(chǎn)品的說明、實(shí)現(xiàn)功能、適用場景等，產(chǎn)品經(jīng)理

需要結(jié)合自身產(chǎn)品的業(yè)務(wù)分析要對接的產(chǎn)品的功能和適用場景是否符

合公司想要實(shí)現(xiàn)的業(yè)務(wù)。

接下來是【調(diào)用方式】中的【簽名方法】，這個(gè)需要分情況，如果你的

平臺是自己對接，自己使用，作為產(chǎn)品經(jīng)理可以不用看這塊，但是如果

你做的SaaS系統(tǒng)，你的平臺可能會(huì)入駐多名商戶，每名商戶都需要去

接口提供方平臺注冊并提供簽名參數(shù)，你不可能每次有新入駐的商戶就

讓開發(fā)工程師往數(shù)據(jù)庫里加數(shù)據(jù)，最合理的解決方案就是在后臺設(shè)計(jì)一

個(gè)商戶管理功能，在商戶管理功能中增加簽名參數(shù)的填寫，這個(gè)時(shí)候,

作為產(chǎn)品經(jīng)理你就必須得知道，這個(gè)平臺需要提供哪些簽名參數(shù)，從而

支撐你完成這塊功能的設(shè)計(jì)，比如這個(gè)發(fā)票平臺的簽名參數(shù)要求提供以

下4個(gè)參數(shù)：

叁數(shù)名稱類型必選描述

是

algorithmString簽名算法，支持RSA-SHA256和HI4AC-SHA256,區(qū)分大〃寫HM

是

appkeyString,IDgj

是

nonceInteger6位隨機(jī)數(shù)字398

是

timestampInteger秒級時(shí)間戳，過期時(shí)間5分鐘159

那么你在設(shè)計(jì)時(shí)，就需要提供相應(yīng)參數(shù)的輸入。

接下來是〃主菜〃，在api列表中，一般會(huì)按照不同的業(yè)務(wù)功能劃分

不同的接口，并以對應(yīng)的業(yè)務(wù)描述來命名接口，因此，我們?nèi)绻O(shè)計(jì)

開具發(fā)票的功能，需要先找到對應(yīng)的接口：

產(chǎn)品介紹▼

產(chǎn)品介紹

平臺指引

接入指引

API文檔▼

調(diào)用方式▼

簽名方法

SDK中心

請求概述

錯(cuò)誤碼

開票服務(wù)相關(guān)接口▼

發(fā)票開具、打印▼

二手車發(fā)票開具

發(fā)票作廢

發(fā)票開具

發(fā)票打印

發(fā)票紅沖

機(jī)動(dòng)車發(fā)票開具

發(fā)票申領(lǐng)、分發(fā)、余量查詢?

發(fā)票通知、查詢?

多場景開票?

紅字信息表?

附錄?

發(fā)票統(tǒng)計(jì)服務(wù)相關(guān)接口?

商戶服務(wù)相關(guān)接口?

全電發(fā)票相關(guān)接口?

點(diǎn)擊對應(yīng)接口后，就可以看到接口的詳情，以下是作為產(chǎn)品經(jīng)理需要關(guān)

注的幾個(gè)點(diǎn)：

口說明：這里面一般會(huì)有一些比較重要的信息，一定要先仔細(xì)閱讀，有

些產(chǎn)品經(jīng)理一上來就跳過接口說明的內(nèi)容，直接看接口參數(shù)，然后遇到

問題解決不了，一直在原地轉(zhuǎn)圈，結(jié)果發(fā)現(xiàn)人家已經(jīng)在接口說明中說了

會(huì)遇到什么問題，是什么原因，怎么解決。

接口說明

使用一二放平臺開具發(fā)票時(shí)，需要先充值并購買相應(yīng)的資源包（如單機(jī)版或者托管等），再綁定稅盤

管家；

1.本接口支持開具增值稅電子普票、增值稅紙質(zhì)普通發(fā)票、增值稅電子專票、增值稅專用

2.開具紙票時(shí)此接口只返回開具數(shù)據(jù)，名氏票打印請查看【發(fā)票打印e】接口。

3.測試環(huán)境僅提供區(qū)塊鏈電子發(fā)票開具，如需測試紙質(zhì)發(fā)票開具或打印，可通過線上環(huán)境

請求參數(shù)：這個(gè)是產(chǎn)品經(jīng)理需要重點(diǎn)關(guān)注的內(nèi)容，這里面涉及到在調(diào)用

這個(gè)接口的時(shí)候需要提供什么參數(shù)，這些參數(shù)往往都是用戶輸入的，因

此產(chǎn)品經(jīng)理需要根據(jù)所需參數(shù)在用戶端收集相應(yīng)的信息，如以下關(guān)于開

具發(fā)票接口的部分請求參數(shù)：

#請求參數(shù)

最大

必長度

參數(shù)名稱類型描述

填（宇

節(jié)）

銷方名稱（銷方票面信息）：如果1

根據(jù)填入信息填入票面，如果不顯

seller_namestring否100默認(rèn)讀取商戶平臺銷方企業(yè)名稱顯

稱不含有特殊符號：轉(zhuǎn)義符*'

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

銷方納稅人識別號（銷方票面信息;

統(tǒng)一社會(huì)信用代碼（一般是15、17

sellerjaxpayernumstring是20

20位長度位數(shù)字或大寫字母，字母I

S、V、Z除外）

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

根據(jù)填入信息填入票面，如果不顯

seller_addressstring否100默認(rèn)讀取商戶平臺銷方企業(yè)地址顯

注意：地址與電話加起來長度R00

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

銷方電話（銷方票面信息）：如果j

根據(jù)填入信息填入票面，如果不亂

sellerjelstring否20默認(rèn)讀取商戶平臺銷方企業(yè)電話顯

話支持分機(jī)殘（使用英文括殘），二

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

銷方銀行名稱（銷方票面信息）:W

入則根據(jù)填入信息填入票面，如果:

入，則默認(rèn)讀取商戶平臺銷方企業(yè)1

seller_bank_namestring否100

注意：銀行與帳號加起來長度R00

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

這里面我們要關(guān)注的，主要是【是否必填】以及【描述】，描述中會(huì)說

明這個(gè)參數(shù)是什么，有什么要求，這里一定要區(qū)分好哪些參數(shù)是技術(shù)需

要的，哪些參數(shù)是業(yè)務(wù)需要的，產(chǎn)品經(jīng)理要重點(diǎn)關(guān)注業(yè)務(wù)參數(shù)，如果不

清楚參數(shù)的用途，可以找接口提供方的提供幫助。

有一些相應(yīng)的校驗(yàn)需要產(chǎn)品經(jīng)理在用戶端收集信息的時(shí)候就做好要求，

防止提交給接口的參數(shù)是不符合要求的，這樣會(huì)浪費(fèi)網(wǎng)絡(luò)資源（每次請

求都需要等待回復(fù)，如果多次嘗試失敗，會(huì)讓用戶覺得體驗(yàn)不好），甚

至浪費(fèi)金錢（有些平臺會(huì)按照接口請求的次數(shù)收費(fèi)，請求一次扣一次費(fèi)

用）。

響應(yīng)參數(shù)：這是請求接口之后，接口提供方回傳給我們的參數(shù)，一段會(huì)

包含狀態(tài)和對應(yīng)的參數(shù)，如下是開具發(fā)票的響應(yīng)參數(shù)：

響應(yīng)參數(shù)

字段類型備注

開票狀態(tài)

曰1:已提交（如果訂單已逑交開票請求并且沒有開票成功,平臺會(huì)根據(jù)策略

9正裁果會(huì)通過異步通知I郵箱等方式返回，也可以通過查詢接口手動(dòng)進(jìn)彳

2：已開票成功（表示已經(jīng)成功開過票了，不能再進(jìn)行重復(fù)開票）

order_snstring是亍商戶訂單號：開發(fā)者商戶訂單號對應(yīng)自亍商戶訂單唯一標(biāo)識

invoicejdstring是發(fā)票標(biāo)識：■?唯一識SU號

但是這里有點(diǎn)奇怪，我們?nèi)绻暾堥_具電子發(fā)票，至少要把電子發(fā)票的

文件給我們吧，不然我們怎把文件給用戶，這時(shí)候我們仔細(xì)看一下，原

來開票的接口是通過異步通知我們的，這里就需要區(qū)分什么同步什么是

異步了。

一般我們提交之后，可以馬上反饋給我們的就是同步通知，比如這里的

狀態(tài)，告訴我們已經(jīng)提交成功了或者已經(jīng)開過票了。而異步通知是說,

我們請求的這個(gè)接口需要的一部分內(nèi)容，需要等待接口提供方處理，處

理完之后再告訴我們結(jié)果，比如這里，開具發(fā)票申請?zhí)峤怀晒?，但是開

票平臺需要同步稅務(wù)局的系統(tǒng)進(jìn)行開票，這里需要有一個(gè)處理的時(shí)間，

要等它處理完之后再告訴我們結(jié)果。

我們可以找一下，發(fā)現(xiàn)接口文檔中確實(shí)有一個(gè)【開票接口異步通知】的

接口，點(diǎn)開發(fā)現(xiàn)這里返回的參數(shù)就非常多了，包括開票的狀態(tài)，電子發(fā)

票開票成功后電子發(fā)票的url等，收到相應(yīng)的響應(yīng)信息之后，我們需要

只需要處理對應(yīng)的信息即可，比如前端可能需要更新開票的狀態(tài)，或者

顯示電子發(fā)票的下載入口等。

接入指引appkey是string32

API文檔▼

message是string100

調(diào)用方式▼

是

簽名方法notifyjypestring20

SDK中心

是

請求概述notifyJimestring20

錯(cuò)誤碼是

orderJdstring64

開票服務(wù)相關(guān)接口▼

是

發(fā)票開具、打印▼g_unique_idstring64

二手車發(fā)票開具

order_sn是string64

發(fā)票作廢

是

ticket_snstring8

發(fā)票開具

是

發(fā)票打印ticket_codestring12

發(fā)票紅沖ticket_date是string20

機(jī)動(dòng)車發(fā)票開具

發(fā)票申領(lǐng)、分發(fā)、余量查詢?

發(fā)票通知、查詢▼

ticket_status是string1

作廢結(jié)果異步通知

開具發(fā)票查詢

開票結(jié)果異步通知