API docs by Redocly

Custom Integration (1.0.0)

Download OpenAPI specification:Download

Recustomer API for Return and Cancel v2

Introduction

Custom Integrationは、Recustomerを利用するために必要な各種データを連携するためのAPIです。
このCustom Integrationは、Order importerとintegration APIの2つの要素で構成されています。

Module1: Order Importer

Order importer（Module1）は注文情報をMerchant環境からRecustomerに送信する役割を担っています。
注文情報が作成・更新されるたびに、エンドポイントが呼び出され、Recustomerに送信する必要があります。

Integration API

Integration API（Module2,3）はRecustomerからMerchant環境の各システムへと通信を行うAPIです。
RecustomerがMerchant環境へデータの更新やデータの取得をする必要がある場合に、このAPIを介して、Recustomerはデータの更新や取得を行います。

Module2: Exchange

Exchangeモジュールは、交換を行う際に、商品のバリエーション情報や在庫情報をRecustomerが取得したり、交換商品の受注伝票をRecustomerが作成したりする場合に使用されます。

Module3: Cancel

Cancelモジュールは、Recustomer上で注文のキャンセル処理が行われた際に、即座にその注文の出荷を停止するために使用されます。
Custom Integrationは、Recustomerを利用するために必要な各種データを連携するためのAPIです。

データフォーマット

Authentication

Order Importer（Module1）

Recustomerからトークンとアクセスキーを提供します。それらのパラメータをAPIのheaderに含めて送信します。

キー名 概要
api_store_key マーチャントを識別するためのキー情報です。
api_token 送信されたリクエストの認証に使うランダムな文字列です。

Integration API（Module2,3）

マーチャント環境にトークン認証を実装する必要があります。
Recustomerから「api_token」のキーでトークンをheaderに含めてマーチャント環境へAPIを送信します。
アクセストークンは外部サービス連携画面にて、Recustomerに提供する必要があります。

module1: Order importer

Order Importer

注文情報をRecustomerに送信します。

header Parameters
api_store_key
required
string
Example: test-store

ストアKey(Recustomerから提供します)

api_token
required
string
Example: X12345678

認証用トークン(Recustomerから提供します)

Request Body schema: application/json
id
required
string

注文ID

order_number
required
string

注文番号

status
required
string
Enum: "processing" "fulfilled" "partial_fulfilled" "canceled"

注文ステータス processing: 処理中、fulfilled: 発送済み、partial_fulfilled: 一部発送済み、canceled: キャンセル済み

fulfillment_status
required
string
Enum: "fulfilled" "null" "partial" "canceled"

発送ステータス fulfilled: 発送済み、null: 未発送、partial: 一部発送済み、canceled: キャンセル済み

financial_status
required
string
Enum: "pending" "authorized" "partially_paid" "paid" "partially_refunded" "refunded" "voided"

支払いステータス pending: 保留中、authorized: 認証済み、partially_paid: 一部支払い済み、paid: 支払い済み、partially_refunded: 一部返金済み、refunded: 返金済み、voided: 無効

order_discount_amount
string (OrderDiscountAmount)

注文に対してのディスカウント金額合計（モール利用の場合は、モール原資クーポン+店舗原資クーポン）

order_point_price
required
string (OrderPointPrice)

注文に対してのポイント利用

total_item_discount_amount
required
string (TotalItemDiscountAmount)

商品ディスカウント合計

subtotal_price
required
string (SubtotalPrice)

商品小計

total_shipping_price
required
string (TotalShippingPrice)

注文時の送料

total_discount
required
string (TotalDiscount)

ディスカウント合計（order_discount_amount+order_point_price+total_item_discount_amount）

additional_fees_amount
string

その他費用合計

total_price
required
string (TotalPrice)

合計金額

total_tax
required
string (TotalTax)

税

payment_at
string

入金日時

is_tax_included
required
boolean

total_priceが税を含む金額か

currency
required
string

通貨単位

quantity
required
integer

注文商品数の合計

created_at
required
string

注文日時

updated_at
string (Updated_at)

更新日時

note
string

注文の補足情報

order_link
string

注文のリンク

required
object (Customer)

顧客情報

required
Array of objects (OrderLineItemImporter)

注文商品

required
object (ShippingAddress)

配送先住所

required
object (BillingAddress)

請求先住所

required
Array of objects (OrderFulfillment)

発送情報

Array of objects (OrderTransaction)

料金情報(支払いが完了している場合必須)

Array of objects (Metafields)

独自で設定したいカラム情報

Responses

Request samples

Content type
application/json
{
  • "id": 1234567,
  • "order_number": 1001,
  • "status": "processing",
  • "fulfillment_status": "fulfilled",
  • "financial_status": "paid",
  • "order_discount_amount": 100,
  • "order_point_price": 100,
  • "total_item_discount_amount": 100,
  • "subtotal_price": 100,
  • "total_shipping_price": "string",
  • "total_discount": 100,
  • "additional_fees_amount": 100,
  • "total_price": 100,
  • "total_tax": 100,
  • "payment_at": "2023-05-10T12:00:00+09:00",
  • "is_tax_included": true,
  • "currency": "JPY",
  • "quantity": 3,
  • "created_at": "2023-05-10T12:00:00+09:00",
  • "updated_at": "2023-05-12T10:30:00+09:00",
  • "note": "テスト注文",
  • "order_link": "https://recustomer.me/order/1",
  • "customer": {
    },
  • "line_items": [
    ],
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "fulfillments": [
    ],
  • "transactions": [
    ],
  • "metafields": [
    ]
}

Response samples

Content type
application/json
{
  • "results": "success"
}

module2: Exchange

Get Product Variants

交換の際に必要な商品情報、及び在庫情報を取得します

path Parameters
product_id
required
string

指定の商品ID

header Parameters
api_token
required
string
Example: X12345678

認証用トークン

Responses

Response samples

Content type
application/json
{
  • "product_id": "product_id",
  • "product_name": "テスト商品",
  • "image_url": "https://recustomer.me/image/12345",
  • "created_at": "2023-05-10T12:00:00+09:00",
  • "updated_at": "2023-05-12T10:30:00+09:00",
  • "variants": [
    ]
}

Create Exchange Order

注文情報を作成します

header Parameters
api_token
required
string
Example: X12345678

認証用トークン

Request Body schema: application/json
original_order_id
required
string

元の注文ID

order_discount_price
required
string (OrderDiscountPricePost)

注文に対してのディスカウント(通常は0でPostします)

order_point_price
required
string (OrderPointPricePost)

注文に対してのポイント利用(通常は0でPostします)

total_item_discount_amount
required
string (TotalItemDiscountAmount)

商品ディスカウント合計

subtotal_price
required
string (SubtotalPrice)

商品小計

total_shipping_price
required
string (TotalShippingPricePost)

注文時の送料(通常は0でPostします)

total_discount
required
string (TotalDiscount)

ディスカウント合計（order_discount_amount+order_point_price+total_item_discount_amount）

total_price
required
string (TotalPrice)

合計金額

total_tax
required
string (TotalTax)

税

is_tax_included
required
boolean

total_amountが税を含む金額か

currency
required
string

通貨単位

required
Array of objects (OrderLineItem)

注文商品

required
object (ShippingAddress)

配送先住所

required
object (BillingAddress)

請求先住所

required
object (CustomerPost)

顧客情報

recustomer_request_id
required
string

Recustomerの返品リクエスト申請ID

Responses

Request samples

Content type
application/json
{
  • "original_order_id": "12345",
  • "order_discount_price": 0,
  • "order_point_price": 0,
  • "total_item_discount_amount": 100,
  • "subtotal_price": 100,
  • "total_shipping_price": 0,
  • "total_discount": 100,
  • "total_price": 100,
  • "total_tax": 100,
  • "is_tax_included": true,
  • "currency": "JPY",
  • "line_items": [
    ],
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "customer": {
    },
  • "recustomer_request_id": "#1001"
}

Response samples

Content type
application/json
{
  • "id": 1234567,
  • "order_number": 1001,
  • "status": "processing",
  • "fulfillment_status": "fulfilled",
  • "financial_status": "paid",
  • "order_discount_amount": 100,
  • "order_point_price": 100,
  • "total_item_discount_amount": 100,
  • "subtotal_price": 100,
  • "total_shipping_price": "string",
  • "total_discount": 100,
  • "additional_fees_amount": 100,
  • "total_price": 100,
  • "total_tax": 100,
  • "payment_at": "2023-05-10T12:00:00+09:00",
  • "is_tax_included": true,
  • "currency": "JPY",
  • "quantity": 3,
  • "created_at": "2023-05-10T12:00:00+09:00",
  • "updated_at": "2023-05-12T10:30:00+09:00",
  • "note": "テスト注文",
  • "customer": {
    },
  • "line_items": [
    ],
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "fulfillments": [
    ],
  • "transactions": [
    ]
}

module3: Cancel

Cancel Order

注文情報をキャンセルします

header Parameters
api_token
required
string
Example: X12345678

認証用トークン

Request Body schema: application/json
order_id
required
string

キャンセルする注文ID

Responses

Request samples

Content type
application/json
{
  • "order_id": 12345
}

Response samples

Content type
application/json
{
  • "id": 1234567,
  • "order_number": 1001,
  • "status": "processing",
  • "fulfillment_status": "fulfilled",
  • "financial_status": "paid",
  • "order_discount_amount": 100,
  • "order_point_price": 100,
  • "total_item_discount_amount": 100,
  • "subtotal_price": 100,
  • "total_shipping_price": "string",
  • "total_discount": 100,
  • "additional_fees_amount": 100,
  • "total_price": 100,
  • "total_tax": 100,
  • "payment_at": "2023-05-10T12:00:00+09:00",
  • "is_tax_included": true,
  • "currency": "JPY",
  • "quantity": 3,
  • "created_at": "2023-05-10T12:00:00+09:00",
  • "updated_at": "2023-05-12T10:30:00+09:00",
  • "note": "テスト注文",
  • "customer": {
    },
  • "line_items": [
    ],
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "fulfillments": [
    ],
  • "transactions": [
    ]
}

Webhook

Shipping Status Webhook

配送ステータスの更新を通知します。

header Parameters
X-Recustomer-Signature-256
required
string^sha256=[a-fA-F0-9]{64}$

ペイロードのHMAC SHA256署名。データの完全性と送信元の認証を保証するためにヘッダーで提供される。署名は'sha256=signature'の形式と一致する必要があり、signatureは64文字の16進文字列である。

X-Recustomer-Sender-ID
required
string
Example: 1bad6b8cf97131fceab8543e81f7757195fbb1d36b376ee994ad1cf17699c464

このヘッダは、受信者がウェブフックの送信元を識別できるように、ウェブフックをトリガーした一意の識別子を含んでいます。

Request Body schema: application/json
tracking_number
required
string

tracking number

estimated_delivery_date
string

order id

latest_tracking_status
required
string
Enum: "荷物受付け" "配送中" "お届け完了" "荷物受取可能" "ご不在のため持ち戻り" "配送トラブル" "保管期限の超過"

latest tracking status

delivery_company
required
string

delivery company

Array of objects

Responses

Request samples

Content type
application/json
{
  • "tracking_number": "string",
  • "estimated_delivery_date": "string",
  • "latest_tracking_status": "荷物受付け",
  • "delivery_company": "string",
  • "logistics_centers": [
    ]
}

Response samples

Content type
application/json
{
  • "results": "string"
}

Return Order Webhook

返品ステータスの更新を通知します。

header Parameters
X-Recustomer-Signature-256
required
string^sha256=[a-fA-F0-9]{64}$

ペイロードのHMAC SHA256署名。データの完全性と送信元の認証を保証するためにヘッダーで提供される。署名は'sha256=signature'の形式と一致する必要があり、signatureは64文字の16進文字列である。

X-Recustomer-Sender-ID
required
string
Example: 1bad6b8cf97131fceab8543e81f7757195fbb1d36b376ee994ad1cf17699c464

このヘッダは、受信者がウェブフックの送信元を識別できるように、ウェブフックをトリガーした一意の識別子を含んでいます。

Request Body schema: application/json
required
id
required
integer (Id)

Return OrderのID

order_number
required
string (Order Number)

注文番号

request_id
required
string (Request Id)

リクエストのID

created_at
required
string <date-time> (Created At)

返品作成日時

refund_reject_reason
string (Refund Reject Reason)

返金拒否理由

approval_at
string <date-time> (Approval At)

返品承認日時

send_backed_at
string <date-time> (Send Backed At)

返送日時

reshipmented_at
string <date-time> (Reshipmented At)

再返送日時

exchanged_at
string <date-time> (Exchanged At)

交換日時

refunded_at
string <date-time> (Refunded At)

返金日時

completed_at
string <date-time> (Completed At)

リクエスト完了日時

approval_status
string (Approval Status)
Enum: "unapproved" "partially_unapproved" "approved" "partially_approved" "rejected" "deleted"

承認ステータス

send_back_status
string (Send Back Status)
Enum: "unarrived" "partially_unarrived" "accepted" "partially_accepted" "refused" "unnecessary" "expired"

返送ステータス

reshipment_status
string (Reshipment Status)
Enum: "unreshiped" "partially_unreshiped" "reshiped"

再返送ステータス

exchange_status
string (Exchange Status)
Enum: "unexchanged" "partially_unexchanged" "exchanged" "partially_exchanged" "rejected"

交換ステータス

refund_status
string (Refund Status)
Enum: "unrefunded" "processing" "refunded" "rejected"

返金ステータス

payment_status
string (Payment Status)
Enum: "unpaid" "processing" "paid"

決済ステータス

exchange_slip_creation_status
string (Exchange Slip Creation Status)
Enum: "uncreated" "partiallycreated" "created"

交換伝票発行ステータス

required
Array of objects (Order Items)
required
object (CustomerWebhook)
object (AddressWebhook)
object (AddressWebhook)
object (RefundInfoWebhook)
is_archive
required
boolean (Is Archive)

Responses

Request samples

Content type
application/json
{
  • "id": 1,
  • "order_number": "#1001",
  • "request_id": "#1001_01",
  • "created_at": "2024-01-17 20:13:41.103117+00",
  • "refund_reject_reason": "2024-01-17 20:13:41.103117+00",
  • "approval_at": "2024-01-17 20:13:41.103117+00",
  • "send_backed_at": "2024-01-17 20:13:41.103117+00",
  • "reshipmented_at": "2024-01-17 20:13:41.103117+00",
  • "exchanged_at": "2024-01-17 20:13:41.103117+00",
  • "refunded_at": "2024-01-17 20:13:41.103117+00",
  • "completed_at": "2024-01-17 20:13:41.103117+00",
  • "approval_status": "unapproved",
  • "send_back_status": "unarrived",
  • "reshipment_status": "unreshiped",
  • "exchange_status": "unexchanged",
  • "refund_status": "unrefunded",
  • "payment_status": "unpaid",
  • "exchange_slip_creation_status": "uncreated",
  • "order_items": [
    ],
  • "customer": {
    },
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "refund_info": {
    },
  • "is_archive": true
}

Response samples

Content type
application/json
{
  • "results": "string"
}