ARTICLE · 1193050
接口文档50美元,PeoplePerHour跨境副业
接口能返回数据，接手的人却不知道该填哪个参数，这种情况并不少见。项目作者觉得很简单，客户端开发者却要反复问：这个字段能不能省，认证信息放哪里，返回空数组算成功还是失败。
这中间有一项具体服务：把已有API整理成别人能够使用的文档。PeoplePerHour当前有一项公开报价50美元的服务，用Swagger或Postman整理接口说明，页面写明三天交付，涉及请求方法、参数、头信息、认证和响应示例等内容。
50美元只是该服务的挂牌报价，不能当成卖家的实际收入。页面另外列出不同工作量的追加选项，其中有“最多五个端点”的加购项。基础价究竟覆盖多少接口，必须单独确认，不能看到加购说明，就反过来宣布50美元固定包含五个接口。
这个细节很能说明文档服务的问题。客户说“帮我写一下API文档”，可能指一个简单查询，也可能指认证、分页、文件上传和几十个端点。名字相同，工作量完全不同。报价之前先确定范围，比接单以后拼命压缩文字更有用。
技术文档不是把接口代码翻译成一段顺口的话。它需要说明别人如何正确调用，也要指出调用失败时会发生什么。能读代码，但不会验证实际行为，容易写出看上去完整、用起来却对不上的说明。
从一条真实请求开始。
接到询问后，先向客户索取接口列表、已有说明、测试环境和允许使用的测试凭据。确认是补全文档，还是还需要修改接口本身。两种工作应分别约定，不能在一个文档订单里默认承担所有后端修复。
测试权限也要讲清楚。只在客户授权的环境与范围内操作，不为了理解接口去访问无关数据，更不对生产环境随意发送可能修改订单或删除记录的请求。涉及写入操作时，用客户提供的测试账户和测试数据，确认能够恢复。
可以先选一个只读接口，按客户给出的条件发起请求。记录方法、路径、必需参数、认证方式与实际响应。用Postman这类工具，不是为了让截图显得专业，而是让每个说明都能对应一次可重复的操作。
请求成功以后，再看返回结果是否和已有说明一致。字段名称、数据类型、空值和时间格式都应核对。客户说某个字段始终存在，测试中却出现缺失，就把差异列出来请对方确认，不擅自选一个版本写成事实。
很多问题藏在正常示例之外。缺少必需参数时返回什么，认证过期后怎样提示，没有结果时是空列表还是错误，分页到最后一页如何判断。文档不一定要覆盖所有异常，但约定范围内常见的失败情况应当有明确说明。
敏感数据需要处理。示例里不放真实客户姓名、邮箱、订单号或有效密钥，可以使用双方确认的测试内容。保存请求集合前，检查变量与环境中是否还留着凭据。文档做得再完整，若顺手把生产令牌一起交出去，就增加了不必要的问题。
好的说明，能让人少问一轮。
一个端点可以从用途、请求条件、参数、响应和错误几部分组织，但不必把每部分都写成很长的文章。使用者最想知道的是，自己现在应该填什么，哪些字段不能漏，以及收到结果后怎样理解。
参数表里，名称与实际接口保持一致，注明类型、是否必需、允许的取值和默认行为。默认值不清楚时，自己验证并让客户确认。不要看到代码中有一个初始值，就假定所有调用场景都会采用它；接口入口还可能做其他处理。
时间和数量单位也要明确。时间戳是秒还是毫秒，日期采用哪个时区，金额字段是元还是最小货币单位，分页编号从零还是从一开始。它们往往只需要几句话，却能减少大量看起来“接口坏了”的误会。
如果使用OpenAPI整理说明，先确定适用版本，再按结构填入路径、方法、参数和数据定义。工具能够检查格式是否成立，却不能判断业务描述是否真实。一个语法正确的文件，也可能把必填字段写成可选，把失败响应写成成功。
文件上传类接口要额外说明内容类型、大小限制和字段名称，不能照搬普通文本请求的示例。测试文件使用不含私人信息的小样本，上传之后按约定清理。客户不允许执行的操作，就在范围记录中说明未实际执行，并请对方提供可以确认的结果，不能把推测写成测试通过。
分页与筛选可以一起看。某个筛选参数省略时返回全部还是默认范围，排序是否稳定，下一页标记怎样得到，都影响调用者能否完整获取数据。用少量测试数据也能检查这些关系，但测试范围有限时，要如实记录，不把一次成功请求描述成覆盖所有数据规模。
响应示例尽量小，但要覆盖当前解释的内容。不必复制一份包含几百行数据的真实返回，让读者自己寻找重点。删减后的示例仍要符合接口结构，并明确哪些是示例值。不能为了简短，改掉字段名称或把数组变成对象。
认证说明应当回答凭据如何获取、放在哪个位置、何时需要刷新，以及缺少权限时怎样识别。具体敏感凭据不出现在公开文件中。涉及复杂授权流程，先让客户确认范围和图示，再决定是否需要额外工作量，不靠一张箭头图掩盖没有验证的细节。
同一个接口的名称，要在目录、参数表、集合和示例中保持一致。代码叫一个名字，文档随手换成更顺口的词，读者搜索时会找不到。技术写作当然需要清楚，但清楚不是把准确名称全部改成普通词，而是在保留名称的同时解释含义。
对于已经存在的代码注释，也不能全盘照搬。注释可能比代码旧，实际服务又可能部署了另一个版本。问清本次文档对应的版本与环境，在交付说明中记录下来。以后接口更新，客户才能判断哪些部分需要维护。
先交一段，确认理解是不是一致。
在展开所有接口之前，可以完成一个端点作为样稿。请客户确认用词、信息深度、示例数据和组织方式。客户想要的是给外部开发者看的接入说明，与内部团队查参数的参考手册，重点并不完全相同。
业务术语也需要统一。客户团队口中的“用户”和“账户”可能不是同一个对象，“完成”与“已支付”也可能代表不同状态。整理一个简短术语表，请客户确认关键含义，再贯穿整份文档。技术写作里很多歧义来自普通词，不全是复杂的代码名称。
返回状态的说明可以配上调用者下一步应当做什么，但建议必须来自实际规则。比如某种错误能否重试、需要等待多久、是否需要重新认证，都不能凭常识补写。没有确定规则，就标出需要客户确认的项，等确认以后再进入正式版本。
确认样稿后，再处理约定范围内的其他接口。按功能分组，把认证与通用错误放在合适的位置，减少同一段内容到处重复。重复内容多了，后续修改容易漏，最终出现同一个参数在两个页面有两种说法。
测试记录与正式说明分开放。测试记录保留请求条件、发现的问题和客户确认结果；正式文档只呈现已经确认、读者需要的信息。不要把未解决的猜测写得像确定规则，也不把内部讨论中的敏感内容直接复制进交付文件。
如果发现接口本身存在错误，明确告诉客户现象、复现条件和影响。由客户决定修复还是暂时说明限制。文档服务可以发现问题，却不能自动变成无限期排错。需要改代码时，重新确认责任、权限、工作量与费用。
交付形式也要在前面说清。Swagger或OpenAPI文件、Postman集合、可阅读的说明页面，分别适合不同用途。客户需要可编辑文件，就保留结构清楚的源文件；只给几张截图，后续无法修改，也很难继续维护。
页面中的托管发布如果属于追加服务，不能默认包含在50美元基础价里。谁负责域名、访问权限和后续更新，服务多久，停用时怎样交接，都需要具体约定。把文档发布出去，只是开始承担另一类维护工作。
这50美元，先扣什么。
PeoplePerHour当前服务费按同一买家的累计合作金额分档，低于250英镑的部分为20%，随后还有7.5%和3.5%的档位，适用税项另计。门槛以英镑表示，不能直接当作美元金额。自己的账户与订单实际适用什么，以平台显示为准。
假设一笔50美元文档订单适用20%服务费，单扣服务费10美元，余下40美元。这不是案例卖家的实际到账，更没有扣税、提现、换汇和工作时间。接口数量不清楚时，任何看似精确的收入计算都容易失去意义。
项目进行中，接口可能继续改动。约定一个本次交付对应的版本或确认时间，把后来的变更单独列出。客户临时增加字段不一定需要大幅加价，但若改变了认证方式或增加一组端点，就要重新评估。没有清楚的范围，文档很容易永远处于“再改一点”的状态。
验收时可以请没有参与编写的开发者按说明完成一次任务。对方在哪一步停住，先记录问题，再区分是说明缺失还是环境未准备好。这个检查不需要表演式展示，真实地照文档操作一次，通常就能看见自己因为太熟悉项目而省略的前提。
报价可以按明确的范围拆成可确认的工作：几个端点，是否已有说明，是否需要实际测试，是否处理认证流程，是否包含托管页面与修改次数。不是把每个按钮都单独收费，而是让双方知道这一笔钱对应什么结果。
发布自己的服务时，作品集可以使用自建的演示接口与自己整理的文档，标明是演示项目。没有客户许可，不把客户内部接口截图放进公开展示。尤其是路径、业务字段和错误信息，有时也会暴露不应公开的系统细节。
账户与作品资料按平台要求填写，服务说明不要承诺自己没有能力验证的技术栈。熟悉REST接口和一种文档工具，可以从窄范围做起；复杂认证、金融接口或高度敏感系统，需要相应经验，不能只凭会操作Postman就接下来。
结束项目时，把源文件、导出文件、使用说明和约定的版本记录一起交齐。临时测试凭据按客户要求撤销或删除，自己的副本也按约定处理。文档中使用了第三方工具，并不意味着客户需要继续依赖你的个人账户才能访问，所有权与访问权限应当能正常交接。
维护安排可以很简单，但不能完全没有边界。交付后修正自己写错的内容，与几个月后接口升级导致的重写，是不同的工作。提前说明包含的修改范围与后续合作方式，既让客户放心，也避免自己为了一个小订单承担长期不确定的责任。
时间记录里，把阅读现有资料、验证接口、等待确认后的修改分别记下。第一次接触某个系统，花在理解业务上的时间可能远多于写字。以后报价时，这些真实记录会比“每个端点几分钟”的想当然更有帮助，也能看出自己适合哪类技术文档项目。
客户确认工作后，按平台流程开票与结算，款项经过清算才成为可提现余额。PeoplePerHour帮助页列出PayPal、Payoneer和银行等提现方式，按本人已经完成验证的账户设置。通常清算需要约十四个工作日，提现处理也需要时间，不把订单金额当作当天已经到账。
交付前最后做一次干净环境测试。移除自己的临时变量，按文档说明重新设置测试凭据，导入集合，完成约定的请求。若必须依赖自己电脑里某个没有交代的设置才能成功，文档仍然缺了一块。
API文档服务最有价值的时刻，往往很安静：另一个开发者照着说明发出请求，得到预期结果，不必再回头问那几个本来应该写清的问题。能做到这一点，交付就不只是一份排版整齐的文件。
立强出海
