決済ゲートウェイ
eSewa、Khalti、Stripe、PayPal、銀行のゲートウェイ。コールバック、検証、返金処理も含みます。
API連携 — ネパール
ネパール発のAPI連携障害時を前提に設計する
Soft Himalayaは、カトマンズから決済ゲートウェイ、CRM、ERP、配送業者、独自APIの接続を手がけています。ネパール、英国、オーストラリア、米国、カナダの企業と協働しています。
- 項目のマッピングとレコードの所在を最初に合意
- リトライ、重複、タイムアウトを意図して設計
- ログとアラートで障害を早期に検知
実運用のためのエンジニアリング
項目の所有、認証情報、リトライ、アラートは、システム間でデータが動き出す前に設計します。
- まず仕様を決める
- エンドポイント、項目、エラーの形式は、どちらの側もコードを書き始める前に合意し文書化します。
- 再送しても安全に
- 書き込み処理は冪等に設計します。タイムアウト後に再送しても、注文や決済が二重に発生することはありません。
- 障害は見える形で
- 外部サービスが停止した場合、連携はログとアラートを出します。静かに失敗してレコードを失うことはありません。
- 認証情報を適切に扱う
- キーは環境変数またはシークレットストアに置き、リポジトリには入れません。権限も連携に必要な範囲に限定します。
連携の対象
すでに運用しているシステムをつなぐ
連携の仕事の多くは特別なものではありません。顧客、注文、請求書とは何かについて2つのシステムを一致させ、片方が利用できないときの挙動を設計することです。
CRM・営業ツール
連絡先、商談、活動履歴を、Webサイトやフォームとチームが使うCRMの間で同期します。
ERP・会計
請求書、在庫、仕訳データを、正としている会計システムやERPとやり取りします。
物流・配送
配送手配、ラベル発行、料金照会、追跡ステータスを、自社の画面に取り込みます。
SMS・メール・通知
各プロバイダ経由のトランザクションメッセージ。配信状況と再送の挙動も明示的に設計します。
マーケットプレイス連携
自社プラットフォームと出品先マーケットプレイスの間で、商品、在庫、注文を同期します。
独自のREST・GraphQL API
自社プロダクトやパートナー向けのAPIを、バージョン管理、認証、ドキュメントとあわせて構築します。
Webhookとイベント処理
受信イベントを検証し、キューに入れて処理します。トラフィックが急増してもレコードを取りこぼしません。
レガシー・データベース連携
古いシステムはデータベースへの直接アクセスを許すのではなく、定義したインターフェース経由で公開します。
なぜ重要か
コストは障害時にこそ生じる
何事もない日に2つのシステムをつなぐのは簡単です。費用を払う価値があるのは、プロバイダがタイムアウトし、項目を変更し、レート制限をかけ、同じイベントを二度送ってきたときの処理です。
手作業の再入力は高くつく
スタッフがシステム間で注文を書き写す作業は遅く、数週間後の照合時に初めて表面化する不一致を生みます。
外部サービスは止まる
プロバイダには障害もメンテナンス時間もあります。キュー、リトライ、明確なフォールバックがあれば、相手側が復旧するまで自社側は動き続けられます。
重複が典型的な不具合
タイムアウトは処理の失敗を意味しません。冪等キーと照合がなければ、再送は二重課金や二重出荷になります。
APIは変わる
項目は非推奨になり、バージョンは終了します。連携には監視と担当者が必要で、一度作って祈るだけでは足りません。
進め方
整理し、構築し、意図的に壊す
期間はプロバイダのドキュメントの質、サンドボックスの有無、認証情報と承認がどれだけ早く得られるかによって変わります。多くの場合、この最後の点が一番時間のかかる部分です。
- 01
調査とドキュメント確認
プロバイダのAPIドキュメントを読み、契約プランで実際に何ができるかを確認し、レート制限、サンドボックス、承認の手順を洗い出します。
- 02
データマッピングと仕様
システム間で項目を対応づけ、各レコードの正となる側を決め、実装前にインターフェースを文書化します。
- 03
サンドボックスでの実装
プロバイダのテスト環境に対して構築します。認証情報は最初からコードベースの外に置きます。
- 04
エラーとリトライの設計
タイムアウト、部分的な失敗、重複イベント、レート制限を意図して処理します。レコードを作成する箇所には冪等性を持たせます。
- 05
失敗経路のテスト
正常系だけでなく異常系も検証します。プロバイダの停止、不正な応答、再送されたWebhook、期限切れの認証情報などです。
- 06
デプロイと監視
ログ、アラート、対応手順書を用意した状態で本番稼働させます。顧客より先に貴社が障害に気づける状態にします。
連携の設計
どの連携にも必要な4つの判断
処理したリクエスト数の架空のダッシュボードをお見せする代わりに、連携が安定するか、それとも継続的なサポート案件になるかを分ける判断を挙げます。
認証の方式
APIキー、OAuth、署名付きリクエストのいずれか。加えて認証情報をどう更新し、誰が保持するか。
データマッピング
各項目をどのシステムが所有し、レコードをどう突き合わせ、両側が同じレコードを更新したときにどうするか。
障害時の挙動
リトライ方針、バックオフ、デッドレターの扱い、そしてプロバイダが利用できない間に利用者に何を表示するか。
監視とアラート
何を記録し、何がアラートを発生させ、連携が止まったときに誰が動くのか。
認証情報とプロバイダのアカウントは貴社名義で登録するため、アクセスが当社に依存することはありません。
ツール
構築に使うもの
技術構成は、つなぐシステムと、引き渡し後に貴社チームが保守できるかどうかに沿って選びます。
Node.jsとTypeScript
連携サービス、Webhook、APIレイヤー
LaravelとPHP
既存のPHPアプリケーション内での連携
Python
大量データの同期とバッチ処理
RESTとGraphQL
インターフェース設計、バージョン管理、ドキュメント
キューとワーカー
リトライ、バックオフ、急増時の処理
PostgreSQLとRedis
レコード保存、冪等キー、キャッシュ
セキュリティと信頼性
保証ではなく、実践
破られない連携は存在せず、セキュリティを保証すると謳う会社は誇張しています。私たちが約束できるのは、一貫して適用する実践と、連携が貴社のデータをどう扱うかの明確な説明です。
認証情報の取り扱い
キーは環境変数かシークレットストアに置き、リポジトリには入れません。権限も連携に必要な最小限に絞ります。
通信と検証
通信はTLSで行い、受信するWebhookは署名がプロバイダのシークレットで検証できない限り拒否します。
レート制限とバックオフ
プロバイダが公開している制限を守り、失敗しているエンドポイントを叩き続けるのではなく、指数バックオフとキューで処理します。
データとログの規律
個人情報と決済情報は必要な箇所だけに記録し、不要な箇所では伏せ、保持期間は合意に従います。
お見積もり
まず範囲、それから価格
費用はプロバイダのAPIの品質、関係するシステムの数、サンドボックスの有無、必要な照合ロジックの量によって変わります。お見積もりの前にドキュメントを確認します。
単一の連携
1つのプロバイダを1つのシステムに接続します。決済ゲートウェイ、配送業者、メッセージ配信サービスなどです。
- ドキュメントの確認
- サンドボックスでの実装
- エラーとリトライの処理
- デプロイと引き渡し
複数システムの同期
2つ以上のシステムの整合を保ち、所有ルールと相互の照合を設計します。
- 項目と所有の対応づけ
- 定期実行とイベント駆動の同期
- 重複と競合の処理
- 監視とアラート
独自APIプラットフォーム
パートナーや自社アプリケーションに公開するAPIを、バージョン管理とドキュメントとともに構築します。
- インターフェース設計
- 認証とレート制限
- 公開ドキュメント
- サポートとバージョン計画
質問
よくある質問
プロバイダ、期間、障害時の処理、そして費用の考え方について、よくいただく質問です。
2つのシステムをつなぎ、誰かが手入力し直すことなくデータをやり取りできるようにすることです。たとえば、WebサイトとCRM、ストアと配送業者、アプリケーションと決済ゲートウェイの連携です。作業の大部分は、各レコードをどのシステムが管理するか、一方が利用できないときにどうするかを決めることです。
協働にあたって
明確な連携の関係
匿名のクライアントの声、稼働率の数値、検証できないリクエスト量のグラフは掲載しません。代わりに、私たちが自らに課している基準を示します。
文書化されたインターフェース
項目、エンドポイント、エラーコード、リトライの挙動は書き出して引き渡します。開発者一人の頭の中に留めません。
認証情報は貴社のもの
プロバイダのアカウントは貴社名義で開設し、当社のアクセス権は範囲を限定し、いつでも削除できます。
障害時の検証
正常系が動くことだけでなく、プロバイダが停止した場合やエラーを返した場合に何が起きるかもお見せします。
保守できる形での引き渡し
ソースコード、環境設定、よくある障害への対応手順書を、次にシステムを支える方へ引き渡します。
プロジェクトを始める
つなぎたいシステムをお聞かせください
関係するシステム、お手元にあればプロバイダのAPIドキュメントのリンク、そして現在どの作業を手で行っているかをお送りください。確認したい点、ご提案する範囲、概算をお返しします。