このセクションの記事

API連携時によくある技術的な質問

  • Q：schemaファイル（schema.graphql）はありますか
    A：以下手順でschema.graphqlがダウンロードできます。
    1. https://api.mercari-shops-sandbox.com/v1/graphqlにアクセス
    2. 画面右「SCHEMA」タブの「DOWNLOAD」から「SDL」を選択する

  • Q：同じtopicのwebhookが複数登録されている場合、どのwebhookが利用されますか
    A：登録されたwebhookのendpoint全てに対してリクエストを送っています。
    利用中のwebhook一覧はOperationsメニュー内「Queries」配下にある「webhook query」を参照してください。
    不要なwebhookがある場合はOperationsメニュー内「Mutations」配下にある「deleteWebhook」で削除が可能です。

  • Q：商品（product）に関する各フィールド値の長さに上限はありますか
    A：仕様書内「Product」「 Variant」「 Stock」「 TransactionMessage」内「validation」欄をご確認ください。

  • Q：商品登録時に「request could not be processed due to permission denied」エラーが出た場合の対応を教えてください
    A：主にショップが非公開状態になっていることにより発生しているエラーです。
    商品をお客さまに公開しない場合は、ショップを公開状態にし、商品ステータスを非公開に設定して登録してください。

  • Q：商品説明に改行を入れる方法を教えてください
    A：description記載時に「\n」で区切ることで改行を行えます。
    例）description: “1行目\n2行目“,
    参考：https://api.mercari-shops.com/docs/index.html#mutation-createProduct

  • Q：複数のMutationを一つにまとめるようなコードを書いてもいいですか
    A：以下のような記載の場合、タイムアウトとなる可能性もあり、性能面の保証ができないため推奨していません。

    mutation UpdateProduct 
    { 
      upd1:updateProduct(input: { id: "id1", price: 350}) { product {id, name, price} } 
      upd2:updateProduct(input: { id: "id2", price: 950}) { product {id, name, price} }
      upd3:updateProduct(input: { id: "id3", price: 500}) { product {id, name, price} }
    }

 

  • Q：購入者による注文キャンセルを制限する設定はできますか
    A：購入者側で注文キャンセルは行えません。
    キャンセル実行権限はショップもしくはメルカリShopsサポートが所持しています。
    参考：注文のキャンセル手順
    「Queries」内「order」「orders」内にある「cancellable」は内部でのシステム的な判断のための項目となり、任意の変更は行えません。
    決済日から1年経過等の条件に合致した場合にキャンセル不可の状態になります。

  • Q：ショップによる注文キャンセルを制限する設定はできますか
    A：注文キャンセルの実行権限に制限はできません。
    参考：注文のキャンセル手順
    「Queries」内「order」「orders」内にある「cancellable」は内部でのシステム的な判断のための項目となり、任意の変更は行えません。
    決済日から1年経過等の条件に合致した場合にキャンセル不可の状態になります。

  • Q：OrderのupdatedAtが変更されるタイミングを教えてください
    A：Orderへ更新が発生する処理全般が対象です。
    例：
    　・決済確定
    　・キャンセル
    　・Complete

  • Q：OrderのpaidAtに値が入る条件を教えてください
    A：購入者の支払いが完了した時点で値がセットされます。例えばコンビニ払いでは、購入者がコンビニでの支払いが完了した時点でその時刻がセットされます。
    ただし、OrderのpaymentMethod の値が次の場合の時、 paid_at はセットされません。
    • CREDIT_CARD が含まれるとき
    • BALANCE のみのとき
      上記の場合、支払い時刻は order.created_at となります。

  • Q：購入者がポイントを使って商品を購入した場合、どのように表記されますか
    A：Typesメニュー内「Order」の「paymentMethod 」がBALANCEと表記されます。

  • Q：PaymentMethodが複数表記されるケースはありますか
    A：ポイントや売上金等、決済手段を併用した場合は複数表記されます。
    ポイントとコンビニ払いで決済された場合は BALANCEとSTORE_PAYMENT 両方が含まれます。

  • Q：APIからお客さまの氏名やニックネームを取得することはできますか
    A：UserInfoとしていくつかのAPIのレスポンスに含む形で取得できます。

  • Q：APIから注文番号を取得することはできますか
    A：order, orders queryなどで取得できるorder idが注文番号です。
    ※order_は注文番号のprefixです

  • Q：お客さまは注文番号を確認できますか
    A：購入者側の取引画面上にもorder_をprefixとした注文番号が表示されます。

  • Q：APIで取引メッセージ受信の検知はできますか
    A：現状検知できません。今後webhookで返すことを予定しています。
    Order自体とは別のResourceがアップデートされるため、updatedDateGteを用いても判断できません。

  • Q：totalPriceに送料や割引額は含まれますか
    A：totalPriceに送料は含まれますが、クーポンによる割引額は含まれません。クーポンによる割引額はOrderCouponのdiscountAmountから取得可能です。totalPriceからdiscountAmountを差し引いた額が最終的にお客さまから支払われた金額となります。
    Orderからは支払手段別の金額内訳は判別できません。

  • Q：salesFeeとはなんですか？
    A：メルカリShopsの販売手数料です。
    参考：「メルカリShopsの手数料」

  • Q：振込金額はどのように算出されますか
    A：totalPriceからsalesFeeやshippingFeeが月次の精算タイミングで差し引かれたものが振込金額になります。

  • Q：updateShippingTrackingCodeへ配送番号以外の情報を入力できますか
    A：自由に入力できる箇所となるため、制限はありません。

  • Q：updateShippingTrackingCodeに入力した内容は発送完了通知に記載されますか
    A：配送番号情報はcompleteOrderのメール文面には記載されません。

  • Q：order内の各種Addressにレスポンスされる「status」とはなんですか
    A：senderAddress、shippingAddressの定義は以下のとおりです。

    • senderAddress

      • 発送元住所を表します。「発送元住所」画面で指定されている住所情報となり、メルカリ便利用時のみ設定されます。

      • WAITING_FOR_SHIPPING以降のStatusで表示されますが、ショップ側で未設定の時点では値が返りません。

    • shippingAddress:

      • 発送先住所を表します。WAITING_FOR_SHIPPING以降のStatusで表示されますが、メルカリ便利用時には設定されません。

  • Q：orderの各種ステータスに遷移するケースを教えてください
    A：「status：COMPLETING」「status：CANCELING」等は非同期的な処理の途上で発生するステータスです。orderに不整合が発生した場合に経由しますが、自動でリカバリーされます。

  • Q：orderステータス「WAITING_FOR_PAYMENT」「WAITING_FOR_SHIPPING」へ遷移する支払手段を教えてください
    A：STORE_PAYMENT（コンビニ/ATM払い）のみが「WAITING_FOR_PAYMENT」へ遷移します。その他支払い手段は「WAITING_FOR_SHIPPING」になります。

  • Q：OrderStatusはどのように遷移しますか？
    A：以下画像のように遷移します。

 

  • Q：商品が購入されてからAPIでorder情報を取得できるまでにタイムラグはありますか
    A：ミリ秒単位では遅延が発生しえます。

  • Q：WebhookTopic内「order_created」のjson raw dataサンプルを教えてください
    A：以下のようなレスポンスが返ります。

    {
      "idempotency_key": "hdwVRBxVjrh5QZvb9J9RVV:order_created",
      "order_id": "hdwVRBxVjrh5QZvb9J9RVV",
      "shop_id": "8o6kxZ3pDTE5HhStMqLzfW",
      "topic": "order_created",
      "product": {
        "product_id": "cxgnJ8dCHTm3ZbwpT8LxyY",
        "name": "productname",
        "price": 1000,
        "variant": {
          "variant_id": "VEsaGvKQycrzFHj8TnMuLd",
          "name": "variantname",
          "sku_code": "rKteYRyPRWbVmGwcNcpDw9",
          "jan_code": "hzeeLUmE5BaegBjbCMm4gN"
        }
      },
      "paid": false,
      "created_at": "2023-01-24T14:06:16+09:00"
    }

 

  • Q：WebhookTopic内「order_paid」のjson raw dataサンプルを教えてください
    A：以下のようなレスポンスが返ります。

    {
      "idempotency_key": "MoVGWH2Gi496VbaPkLy5f5:order_paid",
      "order_id": "MoVGWH2Gi496VbaPkLy5f5",
      "shop_id": "HwPskwoZWGEn6Xuk6Uud5H",
      "topic": "order_paid",
      "product": {
        "product_id": "2nvXS22ydZNyY3MjLDKU9V",
        "name": "productname",
        "price": 1000,
        "variant": {
          "variant_id": "HqGs8mwmCNoYJReNSojPp5",
          "name": "variantname",
          "sku_code": "NfY8CroqbdtgUxtdkrmkvA",
          "jan_code": "Md9KVBXtxiuq2ibMNXEVZN"
        }
      },
      "paid_at": "2023-01-24T14:15:18+09:00"
    }

 

  • Q：webhookに登録するエンドポイントで対応が必要なHTTP request methodは何ですか
    A：POSTmethodに対応してください。

  • Q：大量のPOSTリクエストが発生する場合の対応を教えてください
    A：rate limit上限を恒常的に引き上げるなどの対策を検討するため、別途メルカリShopsサポートまでご相談をお願いします。

  • Q：メルカリAPIのリクエスト制限はありますか
    A：ショップごとに5000pt/hのリクエスト制限があります。
    ※ptの詳細はAPIドキュメントのRate limitingの項目を確認してください

  • Q：Rate limitの制限はどれだけ残っていますか
    A：現状はお伝えできません。

  • Q：Rate limitのコストはどのように計算されますか
    A：返却値ベースではなく実行するクエリに対してコストが計算されます。詳しくはAPIドキュメントをご確認ください。
    例）以下クエリを実行した場合は1として計算されます。

    query {
      productCategories {
        hasChild
        id
        name
        parentId
      }
    }

 

  • Q：メルカリShopsがシステムメンテナンス時にAPIを実行した場合はどのような応答になりますか
    A：HTTP status codeで503が表示され、エラーを示すjsonも返されます。

    $ curl -XPOST -v https://api.mercari-shops.com/v1/graphql
    ...（省略）
    > POST /v1/graphql HTTP/2
    > Host: api.mercari-shops.com
    > User-Agent: curl/7.64.1
    > Accept: */*
    >
    < HTTP/2 503
    ...
    <
    { "errors": [{ "message": "temporary unavailable due to maintenance" }] }

 

  • Q：商品画像の登録で指定したURLに対して、どの程度のアクセスが発生しますか？
    A：商品登録時の一回のみ、画像取得のためのアクセスが発生します。

  • Q： debugCreateOrderのクエリ例を教えてください。
    A：次がクエリの例となります。

    1,500円の商品をクレジットカードで一括払いで購入

    mutation {
      debugCreateOrder(input: { 
        productId: "<Product ID>", 
        variantId: "<Variant ID>",
        creditCardPaymentMethod: {
          amount: 1500,
          payTimes: 1,
          payMethod: ONETIME,
        },
      }) {
        order {
          id
        }
      }
    }


    1,500円の商品をクレジットカードで3回の分割払いで購入

    mutation {
      debugCreateOrder(input: { 
        productId: "<Product ID>", 
        variantId: "<Variant ID>",
        creditCardPaymentMethod: {
          amount: 1500,
          payTimes: 3,
          payMethod: INSTALLMENTS,
        },
      }) {
        order {
          id
        }
      }
    }


    1,500円の商品に対しポイント300pt、残高200円を使用し、残りをクレジットカードで一括払いで購入

    mutation {
      debugCreateOrder(input: { 
        productId: "HVBmYQrdpRjJdKzd3Whq9T",
        variantId: "LPdveUQykj9k7uUdfR8ySN",
        creditCardPaymentMethod: {
          amount: 1000,
          payTimes: 1,
          payMethod: ONETIME,
        },
        balancePaymentMethod: {
          fundsAmount: 200,
          pointAmount: 300,
        },
      }) {
        order {
          id
        }
      }
    }


     *制限
    現在使用できる PaymentMethod は CREDIT_CARD および BALANCE のみです。その他は使用できません。
    配送方法は本来商品に設定された配送方法が選択されますが、 debugCreateOrderでは必ず 未定（出品者が手配） になります。これ以外の配送方法の注文は、現在作成できません。
    ポイント・残高いずれも0の場合は balancePaymentMethodfieldをリクエストに含めないようにしてください。
    非公開状態の商品に対してdebugCreateOrderは実行できないため、エラーになります。debugCreateOrderは公開状態の商品に対して実行するようにしてください。
    variantIdは、productクエリ等から取得できるProductVariantのidを指定してください。

  • Q：Sandbox環境に登録した商品画像がNotFoundになるのはなぜですか
    A：セキュリティ上の理由で、Sandbox環境では商品画像が非公開になります。商品登録・更新時にエラーがなければ、画像も正しく登録できております。


上記をご確認後も問題が解決しない場合は、EC一元管理システムの提供各社へお問い合わせください。

関連記事