編輯導讀：產品經理在工作中，避免不了要閱讀接口文檔，但是有很多新人產品對接口并不太了解。本文作者分享了接口文檔從0到1的過程，從業務、產品層面闡述了接口文檔的結構及內容的規范，希望對你有所幫助。

前兩天接到領導的一個任務，讓我根據業務流程圖設計出一份接口交互文檔出來；

此時小白的內心就有點慌，不知道要怎么開始……

經過一番冷靜思考后，我翻出了之前參加過幾個項目的接口文檔及業務流程圖；然后參考之前文檔照葫蘆畫瓢，結合自己的經驗理清了本次接口設計的思路及主體框架形成初步方案；再帶著我的初步方案找領導確認；經過領導的一番耐心指導，確定了此次接口文檔的框架及要點；就這樣屁顛屁顛回去開搞了。

話不多說，直接進入主題

下圖是經過抽象簡化脫敏后的業務流程圖，涵蓋了融資的主要過程：

材料提交、材料審核、授信、借款申請、放款審核、放款、還款、逾期處理等。另外根據不同資金方，流程圖中列舉了一些不同點，希望對大家的工作有所啟發。

步驟

在我看來接口設計主要分為2步：確定接口交互節點和規范接口內容

第一步是確定接口交互節點

確定交互節點主要分為兩部分：

1. 與業務流程強關的，時效性要求比較高的接口。如準入結果查詢、資方額度查詢等；
2. 與業務主流程不那么相關的，時效性要求不高的。如貸中監控數據推送、還款跑批，逾期代償等；

先將整個流程分為四大部分：材料提交、授信、借款、還款（含逾期代償）；

然后結合業務路程圖，按照在什么階段、什么場景、觸發關鍵節點的前置條件，交互的方向以及時效性，梳理出交互節點。如下圖例子：

再梳理出時效性要求不高的那部分，格式與上面的保持一致。不過，這部分一般比較散亂，需要具備一定的經驗才能考慮周全；我的做法是取所有項目接口的并集，然后根據項目情況刪除一些用不到的。這樣子第一步就完成了。

第二步是規范接口內容

同樣也分為兩部分：

1. 確認請求和響應要傳輸的數據；
2. 對傳輸數據類型進行定義；

這部分我僅從業務、產品層面思考。

1. 每一個接口中都存在唯一的標識碼（我猜應該是銀行用于區分是哪項業務）；
2. 根據所處的業務階段，傳輸不同的字段。如授信接口，傳姓名、身份證、手機號、銀行卡等等；

接下來就是對請求、響應接口它的參數名稱、出現要求、示例值、備注規定好，其他的如：字段長度、類型就交給研發了；

• 參數名稱：一般是漢語轉英語，如用戶編號，UserID；
• 出現要求：主要有必須出現M、條件出現C、選擇出現O三種；
• 示例值：如UserName：張三；

備注：對某些可能存在歧義或者有特殊規定的進一步說明；如ApprovalStatus，授信通過情況，01通過，02拒絕；

全部完成后，就是對這些接口匯總，生成目錄，形成文檔。最后就可以交差啦！

小結

簡單來說，接口設計主要就是確定交互節點和規范接口內容；先根據業務流程梳理出交互節點，再深刻理解業務背景對接口進行詳細定義；

本文由 @九牧 原創發布于人人都是產品經理。未經許可，禁止轉載

題圖來自Unsplash，基于CC0協議