支付网关
eSewa、Khalti、Stripe、PayPal 与银行网关，包括回调、校验与退款处理。
API 集成 — 尼泊尔
来自尼泊尔的 API 集成为故障场景而设计
Soft Himalaya 以加德满都为基地，对接支付网关、CRM、ERP、物流公司与定制 API，服务尼泊尔、英国、澳大利亚、美国与加拿大的企业。
- 先确定字段映射与记录归属
- 重试、重复与超时都经过刻意设计
- 日志与告警让故障尽早暴露
面向真实系统的工程
字段归属、凭据、重试与告警，都在数据开始在系统间流动之前设计好。
- 先定接口契约
- 端点、字段与错误格式在任何一方开始写代码之前就约定好并形成文档。
- 可以放心重试
- 写操作做成幂等，超时后重复调用也不会产生重复的订单或付款。
- 故障看得见
- 第三方服务宕机时，集成会记录日志并发出告警，而不是悄无声息地失败、丢失记录。
- 妥善管理凭据
- 密钥存放在环境变量或密钥库中，绝不进入代码仓库，权限也限定在集成所需的范围内。
我们集成什么
连接你已经在运行的系统
大多数集成工作并不稀奇。它要做的是让两个系统对“客户、订单或发票是什么”达成一致，并处理其中一方不可用的情况。
CRM 与销售工具
在网站、表单与团队使用的 CRM 之间同步联系人、商机与跟进记录。
ERP 与财务
与作为权威数据源的财务系统或 ERP 交换发票、库存与账目记录。
物流与配送
快递下单、面单生成、运费查询与物流状态，回传到你自己的界面中。
短信、邮件与通知
通过服务商发送交易类消息，明确处理送达状态与重试行为。
电商平台与渠道同步
在你的平台与所入驻的电商平台之间同步商品目录、库存与订单。
定制 REST 与 GraphQL API
为你的产品或合作伙伴构建 API，包含版本管理、鉴权与文档。
Webhook 与事件处理
入站事件经过接收、校验、排队与处理，流量突增时也不会丢失记录。
遗留系统与数据库桥接
通过定义清晰的接口开放老旧系统，而不是允许直接访问其数据库。
为什么重要
成本在于故障场景
在一切正常的日子里连接两个系统并不难。真正值得付费的，是服务商超时、改了字段、对你限流或把同一事件发了两次时会发生什么。
人工重复录入代价高昂
员工在系统之间手抄订单既慢，又会造成数周后对账时才暴露的不一致。
第三方会宕机
服务商有故障，也有维护窗口。队列、重试与清晰的降级策略，能让你这边在对方恢复期间照常运转。
重复是最常见的缺陷
超时并不代表调用失败。没有幂等键与对账，一次重试就会变成第二笔扣款或第二次发货。
API 会变
字段会被弃用，版本会下线。集成需要监控和负责人，而不是做一次就听天由命。
工作方式
先梳理，再构建，然后故意把它弄坏
周期取决于服务商文档的质量、是否提供沙箱，以及凭据与审批多快到位——这往往是整个工作中最慢的一环。
- 01
调研与文档审阅
我们阅读服务商的 API 文档，确认你的套餐实际允许什么，并梳理限流、沙箱与审批步骤。
- 02
数据映射与接口契约
在系统之间映射字段，确定每条记录以哪一方为准，并在开发前写好接口文档。
- 03
沙箱实现
基于服务商的测试环境开发集成，从一开始就把凭据放在代码库之外。
- 04
错误与重试设计
刻意处理超时、部分失败、重复事件与限流，在会创建记录的地方保证幂等。
- 05
测试故障路径
我们既测正常路径，也测异常情况：服务商宕机、响应格式错误、Webhook 重放、凭据过期。
- 06
部署与监控
集成上线时配好日志、告警与书面运维手册，让你比客户更早发现故障。
集成规划
每个集成都绕不开的四项决定
与其展示我们处理过多少请求的虚构看板，不如列出决定一个集成是稳定可靠、还是反复出现的支持工单的那些决定。
鉴权方式
API 密钥、OAuth 还是签名请求——以及凭据如何轮换、由谁保管。
数据映射
每个字段归哪个系统所有、记录如何匹配，以及两边同时修改同一条记录时怎么办。
故障行为
重试策略、退避、死信处理，以及服务商不可用期间用户会看到什么。
监控与告警
记录什么、什么会触发告警，以及集成停止时由谁负责处理。
凭据与服务商账户都以贵司名义注册，访问权限不依赖于我们。
工具
我们用什么来构建
技术选型取决于要连接的系统，以及交付后你的团队能维护什么。
Node.js 与 TypeScript
集成服务、Webhook 与 API 层
Laravel 与 PHP
在现有 PHP 应用内完成集成
Python
大数据量同步与定时任务
REST 与 GraphQL
接口设计、版本管理与文档
队列与 Worker
重试、退避与突发流量处理
PostgreSQL 与 Redis
记录存储、幂等键与缓存
安全与可靠性
是做法，而不是保证
没有攻不破的集成，任何声称能保证安全的代理方都言过其实。我们能承诺的，是一套始终如一执行的做法，以及对集成如何处理你的数据的清晰说明。
凭据管理
密钥存放在环境变量或密钥库中，绝不进入代码仓库，权限只给到集成所需的最小范围。
传输与校验
调用全程走 TLS，入站 Webhook 的签名若无法用服务商密钥验证通过，一律拒绝。
限流与退避
请求遵守服务商公布的限额，采用指数退避与排队，而不是反复冲击一个正在失败的端点。
数据与日志规范
个人信息与支付数据只在必要处记录，其余地方做脱敏，并按双方约定的期限保留。
项目估价
先定范围，再谈价格
费用取决于服务商 API 的质量、涉及多少系统、是否有沙箱，以及需要多少对账逻辑。报价之前，我们会先审阅文档。
单一集成
把一个服务商接入一个系统——支付网关、快递公司或消息服务。
- 文档审阅
- 沙箱实现
- 错误与重试处理
- 部署与交接
多系统同步
让两个或更多系统保持一致，并在它们之间建立归属规则与对账机制。
- 字段与归属映射
- 定时与事件驱动的同步
- 重复与冲突处理
- 监控与告警
定制 API 平台
向合作伙伴或你自己的应用开放的 API，包含版本管理与文档。
- 接口设计
- 鉴权与限流
- 公开文档
- 支持与版本规划
疑问
常见问题
关于服务商、周期、故障处理，以及集成工作如何报价的常见问题。
就是把两个系统连接起来，让它们无需人工重复录入就能交换数据——例如网站与 CRM、网店与快递公司、应用与支付网关。大部分工作在于确定每条记录由哪个系统负责，以及其中一个系统不可用时该怎么办。
合作方式
一段清楚的集成合作关系
我们不刊登匿名客户评价、可用率百分比，也不放无法核实的请求量图表。取而代之的，是我们对自己设定的标准。
接口有文档
字段、端点、错误码与重试行为都会写下来并交付，而不是只存在某个开发者的脑子里。
凭据归你所有
服务商账户以贵司名义开设，我们的访问权限范围受限，且随时可以收回。
故障场景经过测试
我们会展示服务商宕机或返回错误时会发生什么，而不仅仅是正常路径能跑通。
可维护的交接
源代码、环境配置以及常见故障的运维手册，都会交给接下来负责这套系统的人。
开始一个项目
告诉我们哪些系统需要互通
把涉及的系统、服务商 API 文档链接（如有），以及目前靠人工完成的工作发给我们。我们会回复需要确认的问题、建议的服务范围和一份估价。