在日常工作中，產品經理需要與多方進行溝通協作，那么掌握相關基礎知識對于雙方的溝通能夠更加順暢。本文總結了新手產品經理必學技術接口文檔知識，方便進一步與開發技術進行協作，希望對你有所幫助。

產品經理需不需要懂技術接口文檔？這個問題我覺得就跟問產品經理需不需要懂技術是一樣的，而我的建議是，需要懂，但只需要有限度地懂。今天我結合之前的一些項目經驗，以對接電子發票中的開具發票接口為例，分享產品經理怎么學會看懂技術接口文檔。

本文是以產品經理理解的角度去說明和解構接口文檔，可能在技術角度未必是正確的，如果有臥底的開發大佬，還請勿噴！

一、什么是接口文檔

要學會看接口文檔，首先得明白什么是接口文檔，接口文檔的作用是什么。

隨著開發技術的發展，漸漸發展成為前后端分離的開發方式，簡單講就是前端開發工程師和后端開發工程師各自開發屬于自己范圍的內容，最后通過 api 接口來進行前后端信息的傳遞，而接口文檔就是記錄各個不同業務用到的 api 接口以及它們所傳遞的信息的技術文檔。但這種文檔一般是內部用的，因此可以說是純粹為了開發服務，產品經理基本接觸不到。

后來，隨著業務形態的發展，在某些業務領域或技術領域有較強優勢的公司會通過出售自身能力來獲得銷售的收入，比如支付能力、視頻流媒體能力、AI 能力等，使得購買的公司能夠以最快的方式實現相應的能力，而實現這種能力的方式之一，就是通過開放 api 接口來進行對接，接口文檔可以讓產品經理和開發工程師快速對接業務和技術。

這么講可能有點抽象，舉個例子，比如我現在有一個商城產品，需要使用移動支付，但是我自己沒有金融牌照，不能做在線收款的業務，而某公司有金融牌照，可以開發在線支付的功能并進行在線收款，該公司通過開放相關的技術接口，商城只需要按照接口對接完成，由該公司來進行代收代付，即可完成在線收款的功能，當然，該公司在此過程中可能會收取相應的費用，這種是屬于有業務領域優勢的類型。

另外一個例子，比如商城需要做一個在線直播的功能，但是目前公司沒有在線視頻流媒體等技術的專業開發人員和技術積累，而某公司則是在這方面有著多年的經驗和深厚的技術積累，因此我們可以購買接入該公司的服務，快速實現在線直播的功能，這種，則是屬于有技術領域優勢的類型。

二、接口工作原理

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

我舉一個例子，比如【接口開放方】開放了一個接口，接口名稱為【你好】，接口要求提供【姓名】作為參數，并返回【某某某，你好】的內容，其中【某某某】是請求接口時提供的【姓名】。

接口的交互用戶是無法感知的，所以需要在用戶端處理內容的輸入和輸出，比如在網頁上放一個輸入框，讓用戶輸入姓名，假設用戶輸入【李雷】，點擊確認，這個時候，【接口請求方】請求【你好】這個接口，并傳遞姓名【李雷】，接下來就會收到【接口開放方】響應回來的信息【李雷，你好】，此時再將收到的這句話通過彈窗之類的形式在用戶端顯示出來，這樣就完成了一次接口的調用。

【接口請求方】無需理會【接口開放方】內部的實現方法，只需關注收到響應后如何處理響應即可（如上方例子中的將收到的信息通過彈窗形式顯示出來），而處理響應一般涉及業務相關，所以需要產品經理介入，因此產品經理看文檔的時候，需要知道，某個接口是為了實現什么功能（比如上方的“你好”接口會返回問好的文字），需要提供什么參數（如上方的“姓名”），會響應什么參數（如上方的“某某某，你好”的信息），收到響應后要怎么處理（一般跟接入方的業務有關）。

三、常規接入流程

這里講的是常規的接入流程，不代表所有平臺都是以這樣的方式接入，以下是接入流程示意圖：

不是拿到接口文檔就可以接入，剛剛提到，接口提供方可能會按照某種方式來收取一定的費用，所以接口的使用肯定是需要在接口開放方的授權下才能進行，所以在完成商務談判之后，一般接口提供方會要求接入方在他們平臺注冊賬號，并通過技術手段給接入放分配相關簽名參數。

簽名參數有兩種作用：

1. 獲得接入權限，相當于鑰匙；
2. 攜帶身份信息，相當于身份證。

所以簽名參數可以理解為是帶有身份信息的通行證，有了簽名參數，才能夠正常請求接口，并且每次請求，接口提供方都能知道是誰發起了接口請求。

四、怎么看接口文檔

剛剛講的都是一些純理論的東西，接下來我以某電子發票平臺的接口文檔為例，講講如果我所在的平臺需要增加一個開具電子發票的功能，在收到接口文檔之后，要怎么看。

這是接口文檔的目錄，在收到文檔之后，建議先看介紹，這里面一般會涉及到當前對接的這個產品的說明、實現功能、適用場景等，產品經理需要結合自身產品的業務分析要對接的產品的功能和適用場景是否符合公司想要實現的業務。

接下來是【調用方式】中的【簽名方法】，這個需要分情況，如果你的平臺是自己對接，自己使用，作為產品經理可以不用看這塊，但是如果你做的 SaaS 系統，你的平臺可能會入駐多名商戶，每名商戶都需要去接口提供方平臺注冊并提供簽名參數，你不可能每次有新入駐的商戶就讓開發工程師往數據庫里加數據，最合理的解決方案就是在后臺設計一個商戶管理功能，在商戶管理功能中增加簽名參數的填寫，這個時候，作為產品經理你就必須得知道，這個平臺需要提供哪些簽名參數，從而支撐你完成這塊功能的設計，比如這個發票平臺的簽名參數要求提供以下4個參數：

那么你在設計時，就需要提供相應參數的輸入。

接下來是“主菜”，在 api 列表中，一般會按照不同的業務功能劃分不同的接口，并以對應的業務描述來命名接口，因此，我們如果要設計開具發票的功能，需要先找到對應的接口：

點擊對應接口后，就可以看到接口的詳情，以下是作為產品經理需要關注的幾個點：

口說明：這里面一般會有一些比較重要的信息，一定要先仔細閱讀，有些產品經理一上來就跳過接口說明的內容，直接看接口參數，然后遇到問題解決不了，一直在原地轉圈，結果發現人家已經在接口說明中說了會遇到什么問題，是什么原因，怎么解決。

請求參數：這個是產品經理需要重點關注的內容，這里面涉及到在調用這個接口的時候需要提供什么參數，這些參數往往都是用戶輸入的，因此產品經理需要根據所需參數在用戶端收集相應的信息，如以下關于開具發票接口的部分請求參數：

這里面我們要關注的，主要是【是否必填】以及【描述】，描述中會說明這個參數是什么，有什么要求，這里一定要區分好哪些參數是技術需要的，哪些參數是業務需要的，產品經理要重點關注業務參數，如果不清楚參數的用途，可以找接口提供方的提供幫助。

有一些相應的校驗需要產品經理在用戶端收集信息的時候就做好要求，防止提交給接口的參數是不符合要求的，這樣會浪費網絡資源（每次請求都需要等待回復，如果多次嘗試失敗，會讓用戶覺得體驗不好），甚至浪費金錢（有些平臺會按照接口請求的次數收費，請求一次扣一次費用）。

響應參數：這是請求接口之后，接口提供方回傳給我們的參數，一般會包含狀態和對應的參數，如下是開具發票的響應參數：

但是這里有點奇怪，我們如果申請開具電子發票，至少要把電子發票的文件給我們吧，不然我們怎把文件給用戶，這時候我們仔細看一下，原來開票的接口是通過異步通知我們的，這里就需要區分什么同步什么是異步了。

一般我們提交之后，可以馬上反饋給我們的就是同步通知，比如這里的狀態，告訴我們已經提交成功了或者已經開過票了。而異步通知是說，我們請求的這個接口需要的一部分內容，需要等待接口提供方處理，處理完之后再告訴我們結果，比如這里，開具發票申請提交成功，但是開票平臺需要同步稅務局的系統進行開票，這里需要有一個處理的時間，要等它處理完之后再告訴我們結果。

我們可以找一下，發現接口文檔中確實有一個【開票接口異步通知】的接口，點開發現這里返回的參數就非常多了，包括開票的狀態，電子發票開票成功后電子發票的url等，收到相應的響應信息之后，我們需要只需要處理對應的信息即可，比如前端可能需要更新開票的狀態，或者顯示電子發票的下載入口等。

以上是個人的經驗之談，希望能夠對剛入行的產品經理學習閱讀接口文檔有一定幫助，感謝閱讀！