連携APIの説明

まるごと売り切りの連携APIで、御社の業務システムから案件を登録し、案件の状態・結果・明細を受け取れます。家財の概算を、都道府県・部屋数・品目の点数から求めることもできます。

落札者の個人情報は、連携APIでは一切お渡ししません。

鍵とスコープ

鍵は、各社の管理者が設定の画面で発行します。すべての呼び出しに Authorization: Bearer <鍵> を付けます。回数は鍵ごとに60回/分です。超えると 429 と Retry-After を返します。

スコープ

案件の登録（sales:write）
案件と結果の取得（sales:read）
明細の取得（statements:read）
家財の概算（estimates:read）
依頼者の氏名・連絡先（pii:read）

エンドポイント

メソッド	パス	スコープ	内容
`GET`	`/api/partner/v1/ping`	`（鍵のみ）`	鍵の確認
`POST`	`/api/partner/v1/sales`	`sales:write`	案件の登録（下書き）。Idempotency-Key ヘッダーが必要です
`GET`	`/api/partner/v1/sales`	`sales:read`	案件の一覧（status・updated_since で絞り込み。並びは created_at, id の昇順）
`GET`	`/api/partner/v1/sales/{id}`	`sales:read`	案件の状態と結果（結果はご依頼者の共有の同意があるときだけ）
`GET`	`/api/partner/v1/sales/{id}/lots`	`sales:read`	品ごとの結果（この一覧だけ品番号の昇順。落札額は同意があるときだけ）
`GET`	`/api/partner/v1/statements/{sale_id}`	`statements:read`	明細の金額（同意があるときだけ）
`POST`	`/api/partner/v1/estimates`	`estimates:read`	家財の概算（作成ではないため Idempotency-Key は不要。個人情報は受け取りません）

Webhook

登録した宛先に、次の出来事を送ります。同じ出来事は同じ event_id です。順番は保証しないため、created_at で判断してください。sale.closed の時点では支払いがまだのため unpaid_count は常に0で、確定額は statement.issued で送ります。

`sale.published`	運営が公開を承認したとき
`sale.closed`	案件の全品の落札・売れ残りが決まったとき
`statement.issued`	依頼者への明細を作ったとき

署名の確かめ方

見出し X-SBGG-Signature: t=<UNIX秒>,v1=<hex(HMAC-SHA256(秘密, t + "." + 本文))> を確かめ、300秒以上ずれていたら捨ててください。

// Node.js
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(secret, header, body) {
  const [, t, v1] = header.match(/^t=(\d+),v1=([0-9a-f]{64})$/) ?? [];
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

結果・明細は、ご依頼者の共有の同意がある案件だけ返します。同意が無い・取り消された案件は result_withheld: "no_consent" です。ご依頼者の氏名・連絡先・住所は、pii:read・組織の設定・同意の3つがそろうときだけ返します。

落札者の個人情報は、連携APIでは一切お渡ししません。

例（curl）

curl -X POST https://marugoto-urikiri.jp/api/partner/v1/sales \
  -H "Authorization: Bearer mg_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 7b1f0c2e-job-2026-0142" \
  -H "Content-Type: application/json" \
  -d '{"external_ref":"JOB-2026-0142","title":"足立区梅田 一戸建て まるごと","pref":"東京都","city_label":"足立区",
       "address":"東京都足立区梅田〇-〇-〇","property_type":"detached","layout_band":"4k_plus",
       "starts_at":"2026-11-10T19:00:00+09:00","ends_at":"2026-11-17T21:00:00+09:00",
       "pickup_windows":[{"date":"2026-11-21","from":"10:00","to":"16:00"}],
       "consignor":{"name":"山田 花子","contact":"090-0000-0000","relation":"長女"},"bulk_buy_quote_jpy":80000}'

curl -X POST https://marugoto-urikiri.jp/api/partner/v1/estimates \
  -H "Authorization: Bearer mg_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"pref":"東京都","rooms":3,"items":[{"category":"furniture","count":40},{"category":"kitchen","count":12}]}'

OpenAPI

OpenAPI 3.1 の定義（JSON）