会社情報
採用情報
お問い合わせ
Article

システム連携で二重入力を完全になくす実装手順

高田晃太郎
システム連携で二重入力を完全になくす実装手順

複数の業界調査では、現場のデータ入力作業のうちおよそ2割前後が転記・再入力に費やされていると語られることがあります。ただし、この割合を直接裏付ける業界横断の公的統計は限定的であり、参考として総務省の統計調査に関する報告では、調査票の作成作業で「手元資料を転記して作成」が最も多く約62%を占めるとされています[1]。経済産業省のDX関連レポートでも、業務プロセスの分断や属人化が非効率の主因として繰り返し指摘されてきました[2]。本稿の結論はシンプルです。設計段階で「単一の真実の源泉（SSOT: Single Source of Truth）」「イベント駆動（Event-Driven）」「冪等性（Idempotency）」「観測可能性（Observability）」を外さなければ、現場の二重入力は大幅に減らせ、実運用で“実質ゼロ”に近づけられます。SSOTの確立は意思決定の一貫性とデータ品質の基盤となり[3]、イベント駆動は疎結合化と拡張性に寄与します[4]。また、APIレベルのIdempotency-Keyは再送時の重複処理を防ぎ[5]、Outboxパターンは二重書き込み問題を構造的に解消します[6]。大切なのは気合いでも総入れ替えでもなく、既存システムを生かしながら、一貫した識別子設計と整合性戦略を積み上げることです。ここからは、システム連携（API連携・データ連携）で二重入力を“完全になくす”ことを目指す実装手順を、実運用で使えるコードとともに解説します。

二重入力をなくすための設計原則

出発点は、どのシステムがどのデータ項目のSSOTなのかを明確にする作業です。顧客マスタはCRM、課金は請求基盤、在庫はWMSといった権限分掌を定義し、全システムで共有できる外部公開ID（システム横断で一意な識別子。例: UUIDや自然キー）を導入します。内部のオートインクリメントIDは各システムに閉じ込め、連携には外部公開IDとバージョン（もしくは更新時刻）を利用します。これにより、どこが正なのかが曖昧なまま相互更新し合う悪循環を断ち切れます。SSOTの確立は各ステークホルダーが同じデータを参照できる状態を作る上で不可欠です[3]。

通信はイベント駆動を基本にしつつ、APIでの同期連携も併用します。重要なのは冪等性で、同一イベントが重複して到着しても状態が二重に進まないことを保証します。アプリ層ではUpsert（存在すれば更新、なければ挿入）で受け止め、DB層では一意制約と競合時の衝突解決を用意します。送信側はOutboxパターンでトランザクション整合性を担保し[6]、配信側は重複排除キーとリプレイ可能なログを装備します[7]。さらに、処理の可観測性としてイベントID、相関ID、P95遅延、失敗率、リトライ回数をダッシュボードで常時可視化することで、現場からの「届いていない」「重複反映された」という声をデータで即時に潰し込めるようになります[8]。より深いAPI設計の背景は社内ドキュメントでも、イベント駆動の利点も解説しています。

実装手順とコードで学ぶ連携の要点

冪等なUpsertで“二度書き”を物理的に不可能にする

まずは受け側のAPIから整えます。Idempotency-Keyで同一オペレーションの二度掛けを吸収し[5]、DBは外部公開IDに対する一意制約＋Upsertで反映します。以下はPythonによるクライアント実装例です。HTTPレベルのリトライは指数バックオフ、サーバーから409/429が返る場合はキーを維持して待機します（同一操作であることをサーバーが判定できるようにするため）。

import json
import time
import uuid
import hashlib
import hmac
import requests
from typing import Dict, Any

API_URL = "https://api.example.com/customers"
API_TOKEN = "<token>"

class RetriableError(Exception):
    pass

def sign(payload: Dict[str, Any], secret: str) -> str:
    body = json.dumps(payload, separators=(",", ":")).encode()
    return hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()

def upsert_customer(customer: Dict[str, Any], secret: str) -> Dict[str, Any]:
    idem_key = str(uuid.uuid4())
    payload = {
        "external_id": customer["external_id"],
        "name": customer["name"],
        "email": customer["email"],
        "updated_at": customer["updated_at"]
    }
    headers = {
        "Authorization": f"Bearer {API_TOKEN}",
        "Content-Type": "application/json",
        "Idempotency-Key": idem_key,
        "X-Signature": sign(payload, secret)
    }
    backoff = 0.5
    for attempt in range(6):
        resp = requests.put(API_URL, data=json.dumps(payload), headers=headers, timeout=10)
        if resp.status_code in (200, 201):
            return resp.json()
        if resp.status_code in (409, 429, 503):
            time.sleep(backoff)
            backoff = min(backoff * 2, 8)
            continue
        raise RetriableError(f"unexpected {resp.status_code}: {resp.text}")
    raise TimeoutError("upsert timed out after retries")

サーバー側は外部公開IDにユニークインデックスを貼り、競合時は更新時刻やバージョン番号による勝ち負けルールで決着させます（後勝ちや期待バージョン一致などを明確化）。こうすることで、APIが重複受信しても状態は二重に増えません。

Webhook受信での重複排除と署名検証

ソースシステムからのイベントは遅延や順序入れ替わりが避けられません。受信側ではまず署名を検証し[9]、イベントID単位で一度処理したものを短期保存して重複を捨てます。Node.js（TypeScript）とRedisを用いた例を示します（ESM/Node.js 18+想定）。

import express from "express";
import crypto from "crypto";
import { createClient } from "redis";

const app = express();
app.use(express.json({ type: "application/json" }));
const redis = createClient({ url: process.env.REDIS_URL });
await redis.connect();

function verifySignature(body: string, sig: string, secret: string) {
  const h = crypto.createHmac("sha256", secret).update(body).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(h), Buffer.from(sig));
}

app.post("/webhooks/customer", async (req, res) => {
  const raw = JSON.stringify(req.body);
  const sig = req.header("X-Signature") || "";
  if (!verifySignature(raw, sig, process.env.WEBHOOK_SECRET!)) {
    return res.status(401).send("invalid signature");
  }
  const eventId = req.body.id;
  const dedupeKey = `evt:${eventId}`;
  const inserted = await redis.set(dedupeKey, "1", { NX: true, EX: 3600 });
  if (!inserted) {
    return res.status(200).send("duplicate");
  }
  try {
    // Upsert processing here
    res.status(200).send("ok");
  } catch (e) {
    await redis.del(dedupeKey); // allow retry
    res.status(500).send("failed");
  }
});

app.listen(3000);

短期の重複排除はメモリキャッシュでも可能ですが、水平スケールや再起動に耐えるためにRedisのような外部ストアが無難です[10]。長期の順序保証や再処理は、後述のCDC＋メッセージング（Kafkaなど）で担保します[12]。

DBの一意制約とOutboxで配送の「抜け」と「重複」を同時に抑える

送信側の二重送信・送信漏れは、アプリのトランザクションとメッセージ配送を分けて実装すると高確率で発生します。Outboxパターン（同一トランザクション内にイベントを書き、CDCで確実に取り出す）で解決します[11]。PostgreSQLの例を示します。

-- 顧客テーブル（外部公開IDに一意制約）
CREATE TABLE customers (
  id BIGSERIAL PRIMARY KEY,
  external_id TEXT NOT NULL UNIQUE,
  name TEXT NOT NULL,
  email TEXT NOT NULL,
  updated_at TIMESTAMPTZ NOT NULL
);

-- Outboxテーブル（取り出し側はstatusで管理）
CREATE TABLE outbox (
  id BIGSERIAL PRIMARY KEY,
  aggregate_type TEXT NOT NULL,
  aggregate_id TEXT NOT NULL,
  event_type TEXT NOT NULL,
  payload JSONB NOT NULL,
  occurred_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  unique_key TEXT NOT NULL UNIQUE
);

-- Upsertサンプル（更新時刻の新しい方だけ反映）
INSERT INTO customers AS c (external_id, name, email, updated_at)
VALUES ($1, $2, $3, $4)
ON CONFLICT (external_id) DO UPDATE
SET name = EXCLUDED.name,
    email = EXCLUDED.email,
    updated_at = EXCLUDED.updated_at
WHERE c.updated_at < EXCLUDED.updated_at;

-- 同一トランザクションでOutboxへ
INSERT INTO outbox (aggregate_type, aggregate_id, event_type, payload, unique_key)
VALUES ('customer', $1, 'CustomerUpserted', json_build_object('external_id', $1), $2);

アプリはコミットに成功すればOutboxへの書き込みも保証されます。取り出しはCDCに任せるため、抜けも重複も構造的に抑えられます[6]。

変更データキャプチャ（CDC）で正確に流す

DebeziumなどのCDCを使えば、Outboxに積まれたイベントを確実にメッセージブローカーへ流せます[12]。MySQLソースの例を示します。

{
  "name": "outbox-connector",
  "config": {
    "connector.class": "io.debezium.connector.mysql.MySqlConnector",
    "database.hostname": "db",
    "database.port": "3306",
    "database.user": "debezium",
    "database.password": "secret",
    "database.server.id": "184054",
    "database.server.name": "company",
    "table.include.list": "app.outbox",
    "tombstones.on.delete": "false",
    "transforms": "outbox",
    "transforms.outbox.type": "io.debezium.transforms.outbox.EventRouter",
    "transforms.outbox.route.by.field": "aggregate_type",
    "transforms.outbox.route.topic.replacement": "${r}.events",
    "key.converter": "org.apache.kafka.connect.storage.StringConverter",
    "value.converter": "org.apache.kafka.connect.json.JsonConverter",
    "value.converter.schemas.enable": "false"
  }
}

アプリコードを触らずに配送を信頼できるのがCDCの強みです。再処理が必要になっても、Kafkaのオフセットや保持期間設定次第でリプレイが可能です[7]。

メッセージングでExactly-Onceに近づける

受け側のコンシューマは冪等Upsertで十分ですが、配信時の重複も抑えたい場合はブローカーのトランザクションや冪等プロデューサを活用します。GoとSaramaでの例を示します（Exactly-Onceは分散環境では厳密には難しいため、「限りなく近づける」発想が実務的です）。

package main

import (
    "log"
    "time"

    sarama "github.com/Shopify/sarama"
)

func main() {
    cfg := sarama.NewConfig()
    cfg.Producer.Return.Successes = true
    cfg.Producer.Idempotent = true
    cfg.Producer.RequiredAcks = sarama.WaitForAll
    cfg.Net.MaxOpenRequests = 1
    cfg.Version = sarama.V2_5_0_0

    prod, err := sarama.NewSyncProducer([]string{"kafka:9092"}, cfg)
    if err != nil { log.Fatal(err) }
    defer prod.Close()

    msg := &sarama.ProducerMessage{
        Topic: "customer.events",
        Value: sarama.StringEncoder("{\"type\":\"CustomerUpserted\"}"),
    }
    for i := 0; i < 3; i++ { // retry with backoff
        _, _, err = prod.SendMessage(msg)
        if err == nil { break }
        time.Sleep(time.Duration(1<<i) * time.Second)
    }
}

IdempotentプロデューサとRequiredAcks=Allにより、ネットワーク断・再送でも重複が抑制されます[13]。受け側でのUpsertと合わせて全体としてExactly-Onceに近い性質を実現します。

APIのIdempotency-Keyは実運用で役に立つ

クライアントが同一操作を再送しても、サーバーは同じ結果を返せばよいだけです。ヘッダーでキーを渡し、一定期間はリプレイしても同一レスポンスを返します[5]。

curl -X PUT https://api.example.com/customers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2b7b2c5a-2d7b-4c7e-8f8e-9e9f0a" \
  -d '{"external_id":"CUST-001","name":"Acme","email":"ops@acme.io","updated_at":"2025-08-01T12:00:00Z"}'

サーバーはキーとレスポンスのハッシュをKVSに記録し、重複時は保存済みの結果を返します。これによりネットワーク不安定時でもフロントの「連打」に強くなります。

運用・監視・データ品質の作り込み

実装が揃っても、運用の作り込みが不十分だと二重入力は現場に忍び込みます。ダッシュボードではイベント到達から最終反映までのエンドツーエンド遅延をP50/P95で可視化し、失敗イベントはDead Letter Queueに集約してJiraやSlackに自動起票します[8]。再処理は相関IDで範囲指定してリプレイし、データ修復は原則API経由の再投入で行います。タイムゾーンやサマータイム、住所の全角半角など、同一性判定を誤らせる細部にも注意が必要です。正規化関数を用意して、比較前に共通フォーマットへ揃えると突合の誤検知を抑えられます。権限と監査も忘れてはいけません。誰がどのイベントを手動再送したのか、いつどの値が上書きされたのかを監査トレイルで追えるようにし、SSOT以外からの手編集は原則禁止にします。既存画面からの入力を止められない場合は、UIからの編集を受けても即座にSSOTへ反映し、ラウンドトリップで最終値を取り直すことで「UIだけ上書き」状態を一掃します。これにより、現場の迷いをなくし、再入力を発生させる余地を減らします。

KPIとROI：導入効果を数式で可視化する

導入効果は感覚ではなく数値で示します。開始時点で一日あたりの再入力件数、1件あたりの入力時間、対象人数を計測し、削減率をトラッキングします。例えば、再入力が1件2分、1人あたり1日30件、対象が80名だとすると、日次で80×30×2=4,800分、すなわち80時間の削減ポテンシャルがあります。人件費を時給3,500円とすると日次で28万円、月20営業日で560万円が上限効果の目安になります。初期構築と運用のTCOを見積もる際は、連携開発工数、ブローカーやCDCの運用費、監視のSaaS費用、トレーニング時間を含めます。一般的な公開事例やベストプラクティスでは、可観測性と一貫したデータモデル（SSOT・外部公開ID）をセットで導入することで、エンドツーエンド遅延の短縮や処理件数の向上、関係者間の調整コスト削減が報告されています。KPIは「二重入力件数」「再処理率」「エンドツーエンド遅延」「手動介入数」「データ整合性アラート件数」の5点を最初の四半期で追うと、改善サイクルが回りやすくなります。

まとめ：現場の「もう一度書く」を設計で根絶する

二重入力は慣習ではなく設計の問題です。SSOTと外部公開IDで発生源を一本化し、OutboxとCDCで配送の抜け・重複を潰し、受け側は冪等Upsertと署名検証で堅牢にする。この三層を揃え、可観測性で運用の透明性を上げれば、属人的な「保険のつもりの再入力」は消えていきます。もし今、どこから着手するか迷っているなら、まずは最も入力頻度の高いエンティティ一つに対象を絞り、APIのIdempotency-Key、DBの一意制約、Outboxの3点セットを小さく実装してみてください。パイロットで数字が出れば、社内の合意形成は一気に楽になります。あなたのチームと現場が、入力ではなく価値創出に時間を使えるよう、今日から設計を一歩進めていきましょう。

参考文献

  1. 総務省. 統計調査等の報告負担に関する調査（調査結果概要・企業票B）. 2006. https://www.soumu.go.jp/toukei_toukatsu/index/seido/02toukatsu01_03000084.html
  2. 経済産業省. DXレポート～ITシステム「2025年の崖」の克服とDXの本格的な展開～. 2018. https://www.meti.go.jp/shingikai/mono_info_service/digital_transformation/20180907_report.html
  3. Talend. Single Source of Truth（SSOT）とは. https://www.talend.com/jp/resources/single-source-truth/
  4. Martin Fowler. What do you mean by “Event-Driven Architecture”?. 2017. https://martinfowler.com/articles/201701-event-driven.html
  5. Stripe. Idempotent Requests. https://stripe.com/docs/idempotency
  6. AWS Prescriptive Guidance. トランザクション・アウトボックス（Transactional Outbox）パターン. https://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html
  7. Apache Kafka Documentation. Design and Implementation (Log, Retention, Offsets). https://kafka.apache.org/documentation/#design
  8. Google SRE Book. Service Level Objectives. https://sre.google/sre-book/service-level-objectives/
  9. GitHub Docs. Securing your webhooks. https://docs.github.com/en/webhooks/using-webhooks/securing-your-webhooks
  10. Redis. SET command (NX/XX, EX/PX options). https://redis.io/commands/set/
  11. Microsoft Azure Architecture Center. Transactional Outbox pattern. https://learn.microsoft.com/azure/architecture/patterns/transactional-outbox
  12. Debezium. Outbox Event Router. https://debezium.io/documentation/reference/stable/transformations/outbox-event-router.html
  13. Apache Kafka Wiki. Idempotent Producer. https://cwiki.apache.org/confluence/display/KAFKA/Idempotent+Producer