協力会社パートナー API v1

バス会社等の協力会社さまの自社システムと KIZUNA プラットフォームを接続するための REST API です。事業者ポータルで行う操作（見積提出・配車の承諾/拒否・運行報告・精算確認）とマスターデータ同期を、機械同士で行えます。

0. 接続開始まで（オンボーディング）

1. 基本仕様

• ベース URL: https://splendor-star.co.jp
• 形式: JSON（UTF-8）／日付 YYYY-MM-DD・日時 ISO 8601
• 認証: Authorization: Bearer <APIトークン>（全エンドポイント必須）
• レート制限: 1 分あたり 120 リクエスト / 1 トークン（超過は 429）

curl -H "Authorization: Bearer $TOKEN" \
     https://splendor-star.co.jp/api/provider/v1/me

{"data": {"id": 8, "name": "○○交通株式会社",
          "provider_type": "bus_company", "api_version": "v1"}}

エラー形式（共通）

{"error": {"code": "deadline_passed", "message": "Quote deadline has passed"}}

成功時は必ず {"data": ...} に包まれます。存在しない ID と他社の ID はどちらも 404 not_found です（他社データは見えない設計）。

2. 見積依頼（RFQ）

GET/api/provider/v1/rfqs

自社が招待されている見積依頼の一覧（回答期限の近い順・最大 200 件）。?state=open で回答期限内・未確定のものだけに絞れます。

{"data": [{
  "id": 31, "number": "RFQ-26-0031", "state": "sent",
  "route_description": "東京・箱根・京都・大阪 ゴールデンルート 24名",
  "date_start": "2026-10-01", "date_end": "2026-10-04",
  "start_time": 8.0, "end_time": 18.0,
  "pickup_location": "成田空港", "dropoff_location": "関西空港",
  "vehicle_type": "minibus", "pax_count": 24, "bus_count": 1,
  "estimated_km": 360.0, "deadline": "2026-09-05T12:00:00",
  "my_quote": null
}]}

GET/api/provider/v1/rfqs/{id}

単一の見積依頼。my_quote に自社の見積が入ります（未提出なら null）。

POST/api/provider/v1/rfqs/{id}/quote

見積の提出。確定前であれば同じエンドポイントで更新できます（送信したフィールドのみ更新される PATCH 方式。未送信フィールドは保持されます）。

curl -X POST -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"total_price": 312000, "vehicle_id": 99, "driver_id": 129,
          "includes_tolls": true, "notes": "高速・駐車場込み"}' \
     https://splendor-star.co.jp/api/provider/v1/rfqs/31/quote

成功: 201 + 見積 JSON（state: "submitted"）。

POST/api/provider/v1/rfqs/{id}/withdraw

提出済み見積の取り下げ。

3. 配車（受注後の運行）

見積が採用されると運行日ごとに配車オーダーが作成されます。

GET/api/provider/v1/dispatches

自社の配車一覧。絞り込み: ?state=assigned|confirmed|in_progress|completed|cancelled、?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD（最大 500 件）。

{"data": [{
  "id": 120, "number": "DSP-26-0120", "state": "assigned",
  "provider_response": "pending",
  "date": "2026-10-01", "start_time": 8.0, "end_time": 18.0,
  "pickup_location": "成田空港", "dropoff_location": "ホテル",
  "rfq_id": 31, "rfq_number": "RFQ-26-0031",
  "vehicle_id": 99, "driver_id": 129
}]}

POST/api/provider/v1/dispatches/{id}/accept

配車の承諾。vehicle_id / driver_id を渡すと同時に割当できます。成功で state: "confirmed"。

POST/api/provider/v1/dispatches/{id}/decline

配車の拒否。{"reason": "..."} を推奨（KIZUNA 側に理由が通知され、代替手配が始まります）。成功で state: "cancelled"。

POST/api/provider/v1/dispatches/{id}/start ・ /complete

運行開始・運行完了の報告。confirmed → in_progress → completed の順にのみ遷移します。既に目的の状態にある場合は 200（冪等）、それ以外の順序違いは 409 invalid_state を返します。

4. 精算

GET/api/provider/v1/settlements

自社の精算台帳。?month=YYYY-MM で月次絞り込み。

{"data": {
  "entries": [{
    "id": 41, "number": "STL-26-0041", "state": "settled",
    "service_date": "2026-10-01", "service_month": "2026-10",
    "dispatch_number": "DSP-26-0120",
    "amount_payable": 78000.0,
    "payment_reference": "10月分振込", "settled_date": "2026-11-15"
  }],
  "total_payable": 78000.0
}}

state: pending（計上済）→ approved（承認済）→ settled（支払済）。disputed は金額協議中です。異議申立ては v1 では API 未対応のため、ポータルまたは担当者へご連絡ください。

5. 自社リソース

• GET/api/provider/v1/vehicles → [{id, name, plate_number, vehicle_type, seats}]
• GET/api/provider/v1/drivers → [{id, name}]

6. マスターデータ同期（既存 API）

車両・乗務員・運行予定・顧客マスターの一括アップロードは従来からの同期エンドポイントを使います。

• GET/api/provider/ping — 疎通確認
• POST/api/provider/import — {"import_type": "vehicles|drivers|schedule|customers", "data": [...], "meta": {"content_hash": "..."}}

同一内容の再送は content_hash により自動スキップされます。詳細なペイロード仕様は接続時に個別にご案内します。

7. Webhook（イベントのプッシュ通知）

受信用の https URL を KIZUNA 担当者にお伝えいただくと、イベント発生時に JSON を POST します（設定しない場合はこれまでどおりポーリング運用で問題ありません）。

POST（ヘッダ）
X-Kizuna-Event: rfq_invited
X-Kizuna-Timestamp: 1751242200
X-Kizuna-Signature: hmac_sha256_hex( secret, "{timestamp}." + body )

POST（ボディ）
{"event": "rfq_invited", "created_at": "...", "data": { ...RFQ要約... }}

署名検証: 交付された秘密鍵で {タイムスタンプ}.{生ボディ} の HMAC-SHA256（16進）を計算し、ヘッダと一致するか確認してください。応答が 2xx 以外の場合は指数バックオフで最大 8 回再送します。受信処理は冪等に実装してください（同一イベントが複数回届く可能性があります）。

8. 運用上の注意

• ポーリング推奨間隔: Webhook（§7）未設定の場合、RFQ/配車の新着確認は 5 分間隔のポーリングを推奨します。
• 冪等性: accept / decline / start / complete は同じ結果への再送に対して 200 を返し、状態は壊れません（履歴状態への操作は 409）。見積 POST は送信フィールドのみの更新（PATCH）です。
• 時刻: start_time / end_time は 0–24 の小数（時）です（例 8.5 = 8:30）。
• 障害時: 5xx は間隔を空けて再試行してください。4xx はリクエスト側の修正が必要です。
• サポート: トークン発行・接続テスト・技術相談は KIZUNA 担当者まで。

9. 代理店（販売パートナー）受注 API

旅行代理店さまの自社システムから、団体オーダーの発注・状況確認・搭乗者名簿の登録・精算状況の照会ができます。認証は代理店ごとの Bearer トークン（KIZUNA から交付）で、仕様の流儀は本書前半と共通です（エラー形式・レート制限・他社データは 404）。

curl -X POST -H "Authorization: Bearer $AGENT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"contact_name": "王偉", "destinations": "東京・大阪 6日",
          "arrival_date": "2026-11-10", "departure_date": "2026-11-15",
          "pax_count": 25}' \
     https://splendor-star.co.jp/api/agent/v1/orders