#GoFile Connect API

Connect APIとは何か

英国の税務申告のためのコンプライアンスゲートウェイ：ソフトウェアがクライアントとその数値を1つのエンドポイントに呼び出し、 # GoFileその呼び出しからHMRCへの受信までのすべての処理を行います。

デジタル税務は、一度呼び出すのが難しいAPIではありません。 自分の認識、18 か月後に期限切れとなる OAuth グラント、実際の発信元デバイスを記述する必要のある不正防止ヘッダー、義務のマッチング、決して作成してはならない期間キー、送信の冪等性、そして何年も後も有効な監査証跡――これらが作業であり、決して終わりはありません。

Connect API は、小さな REST インターフェースの背後で実行および保守される作業です。バージョン 1 では、 バット顧客が承認されているかを確認し、顧客のVATに関する状況をすべて読み、申告書を作成し、領収書を受け取るまで追跡する。

対象者

APIはエージェントモデル向けに設計されています。パートナー企業はHMRCに接続します。 エージェントサービスアカウント 一度承認すれば、その単一の承認で、代理業務を行う権限を持つすべての顧客が対象となります。

仕組み

すべてのリクエストは署名付きのRESTコールです。法律上、人間の介入が必要となるすべての処理は、当社がホストするページ上で行われます。

GET /api/v1/vat/193054661/status

{
  "vat_number": "193054661",
  "mode": "live",
  "obligations": {
    "open": [
      { "period": { "start": "2026-04-01",
                    "end":   "2026-06-30" },
        "due": "2026-08-07",
        "overdue": false }
    ],
    "fulfilled": [ /* filed periods + figures */ ]
  }
}

{
  "external_client_id": "CLIENT-91827",
  "client_name": "Acme Trading Ltd",
  "vat_number": "193054661",
  "return": {
    "vat_due_sales": "12500.00",
    "total_vat_due": "12500.00",
    "net_vat_due":   "8300.00"
    /* ...nine boxes in total */
  }
}

{
  "id": "vfs_...",
  "status": "submitted",
  "receipt": {
    "gofile_reference": "GF-VAT-123",
    "form_bundle": "258868935084"
  }
}

ホスト型承認 ― そしてそれが重要な理由

HMRC単に申告書が欲しいのではなく、その申告書が実在の人物から実在のデバイスで提出され、人間が申告に責任を負ったことを確認したいのです。不正防止ヘッダーはまさにそのためにあるのであり、ヘッダーを間違えることはバグではなく、コンプライアンス上の問題です。

Connect API は、ソフトウェアにそれらを偽造するよう要求することはありません。申請を投稿すると、ページへの URL が返されます。 私たちはホストしていますそのページで、認証された担当者が二段階認証でログインすると、担当者の実際のデバイスがキャプチャされ、申告内容がすべて表示され、担当者が申告内容を確認します。その後、提出書類とともに証拠として保存された、そのデバイスから作成されたヘッダー情報とともに、 HMRC （英国歳入税関庁）に連絡します。

このページは、顧客が一度限りのHMRC歳入税関庁）への接続を行う際にも役立ちます。企業が初めて申告を行う場合、そこで代理人サービスアカウントを承認し、すぐに申告画面に戻ることができます。

構築する必要のないもの

期間キーや finalised フラグ — API はそれらを即座に拒否します。なぜなら、それらは私たちが決定するものであり、それらを間違えると不適切な申請が発生するからです。

サンドボックスとライブ

モードは署名に使用するキーによって選択されるため、グローバルなスイッチを切り替える必要はなく、デプロイメント時に忘れる心配もありません。

• gfk_sandbox_… キーファイルをHMRCのテスト環境に送信します。無料、無制限、CI環境での実行も安全です。
• gfk_live_… キーファイルは実際のリターンを格納します。

両方とも同時に動作します。テストスイートは本番環境のファイルが存在する状態でもサンドボックス環境で実行でき、切り替えはどちらの認証情報でサインインするかによって決まります。使用状況、リクエストログ、および日次制限は、モードごとに個別に追跡されます。

セキュリティと証拠

ローテーションはダウンタイムゼロです。複数の鍵を同時にアクティブにできるため、新しい鍵ペアを発行してデプロイし、古い鍵ペアで署名が行われなくなったら、古い鍵ペアを失効させます。

Webhook、ログ、開発者ポータル

申請処理は本質的に非同期処理です。人間の承認が必要であり、 HMRC歳入税関庁）からの回答も必要となります。ポーリングを行う代わりに、申請処理の進捗状況（承認待ち、提出済み、失敗など）に応じて、署名付きイベントをエンドポイントにプッシュ配信します。各配信は、お客様のWebhookシークレットでHMAC署名されるため、弊社からの配信であることを検証できます。

パートナーポータル api.gofile.co.uk チームに以下をもたらします：

• APIキー — サンドボックスとライブのペアを発行し、最終使用状況を確認し、ローテーションと取り消しを行います。
• リクエストログ 署名済みのリクエストごとに、ステータス、エラーコード、モード、期間、リクエストIDが表示されます。署名失敗も表示されるので、午前2時にHMACを間違えた時などにはまさにうってつけです。
• Webhook配信 イベントごとのステータス、応答コード、および再試行スケジュール。
• 使用法 ―申請件数と提出件数を日別、提出方法別に分類してグラフ化。
• 請求する 請求書、支払い方法、そしてお客様のプラン。

価格

価格にはVAT（付加価値税）は含まれていません。申告手数料は次回の月額請求書に加算されます。顧客ごとの手数料、最低申告量、サンドボックス申告の手数料は一切かかりません。実際の申告書がHMRC歳入税関庁）に届いた場合にのみ料金が発生します。

次は？

バージョン1はVAT（付加価値税）を対象としています。これは、VATがMTDデジタル納税）の義務化対象であり、処理量が最も多い分野だからです。1回の簡単な通話、ホスト型承認、領収書の発行という同じモデルは、英国のその他のコンプライアンス申告にも適用できるように設計されています。

所得税のMTD自然な次のサーフェスであり、簡素化された API の価値が最も高まる場所です。HMRC 独自のHMRCインターフェースは多数のエンドポイントと形状にまたがっており、Connect が VAT で提供するのと同じ合理的なサーフェスにそれを統合する予定です。ロードマップが特定の税金やタイムラインに依存している場合は、 教えてください パートナーの需要によって注文が決定されます。

さあ始めましょう