セカイロジAPI (0.1.7)

セカイロジ API のドキュメントです．

この API ドキュメントは OpenAPI フォーマットで記載されています．

定義ファイルをダウンロードする

セカイロジ API は現在，

• トラッキング番号を通知する Webhook
• Webhook のエンドポイントを設定する機能(UI の設定メニューへ追加)
• API トークンを発行する機能(UI の設定メニューへ追加)
• テスト環境の提供
• 出荷依頼依頼作成 API
• 出荷依頼依頼一覧取得 API
• 出荷依頼依頼取得 API
• 出荷依頼依頼削除 API
• 返送一覧取得
• 商品登録 API
• 商品検索 API
• 商品取得 API
• 商品削除 API
• 商品分類検索 API
• 入庫登録 API
• 入庫検索 API
• 入庫取得 API
• 入庫キャンセル API

を提供しています．

Webhook に関しては，本番環境でテスト用の Webhook を発信する機能を用意しています．

YAML ファイルをダウンロードして，ローカルで開発用のモックサーバーを立ち上げることができます．

ローカルでの開発用モックサーバーの立ち上げ

docker-compose.yml

  api:
    image: stoplight/prism:4
    volumes:
      - ./:/tmp
    command: mock -h 0.0.0.0 /tmp/something_path/openapi.yaml

sh

$ docker-compose up -d
$ docker-compose exec api bash
/home/app# curl -X POST http://localhost:4010/...

https://sandbox.sekailogi.com に本番環境とは別の環境を用意しています． 本番環境と同様にWeb UIが上記URLで提供されているので，ログインして処理を行えます．

APIは https://api.sandbox.sekailogi.com のURLに対してリクエストすれば，テスト環境へのリクエストとなります． APIトークンなどもテスト環境上で生成したものを使うことが出来ます．本番環境のものは使うことが出来ません．

テスト環境用ツール

テスト環境にのみ，入荷や出荷を任意のタイミングで完了させたり返送のデータを作成するための機能を用意しています． メニューのテスト環境用ツールから遷移出来ます．

テスト環境用ツールは

• 作成した入庫依頼を完了させるための機能
• 作成した出荷依頼を完了させるための機能
• 出荷済みにした出荷依頼から返送を作成するための機能

が備えられており，操作したい対象の入庫依頼番号・注文管理番号を入力して行いたい操作を選びます．

テスト環境の制限

• 出荷の承認
  • DHL・佐川急便・ヤマト運輸でのみ利用可能
  • 郵政系（EMSや国際小包など）やFedExはテストラベルの発行が行えないため承認エラーが発生します（出荷依頼のみは登録できます）

https://api.sekailogi.com へAPIリクエストしていただけます．

API トークンの取得

セカイロジの UI の 設定 > API設定 の画面から発行することができます．

API トークンは発行時のみ表示されます．原文は保存されないため，その後再確認することはできません．

API トークンを利用した認証方法

上記で取得した API トークンを HTTP ヘッダに Authorization: Bearer APIトークン という形で設定し，API リクエストを行います．

出荷依頼検索 など複数の結果を返すAPIに関しては

• limit: 1回に返す結果の件数（上限100）
• page: limit*pageの数を進めた数から結果を取得するようにする．1から始まる．

のようにクエリパラメータを共通で指定できる．

セカイロジの UI の 設定 > API設定 の画面から Webhookを追加する ボタンから Webhook エンドポイントを設定することができます．

設定されたエンドポイントに対して，イベントが発生した際に HTTP POST リクエストを行います．

エンドポイントを設定する際に署名トークンが発行され，それを元に後述する正当性検査を行うことを推奨します．

設定 > API設定 で Webhook エンドポイントを追加した後に，ログを表示 ボタンからその Webhook エンドポイントへの Webhook 送信ログを確認することが出来ます．

リクエストの正当性検査

設定されたエンドポイントはインターネットに公開されている必要があるため，BOT やクローラなどからアクセスされることや悪意のあるユーザによってリクエストが送信されることが起こり得えます．

そのため，正当な Wehook リクエストには以下のようなヘッダを付与します．

Sekailogi-Signature-512: シグネチャの値

シグネチャの値は，

• SHA512 関数によって HMAC を計算する
• 署名トークンをキーとして使用
• リクエスト本文（JSON ペイロード）文字列をメッセージとして使用
• 16 進数文字列として出力する

以上の方法で導出した値と一致するかをもって正当性を検証します．

Node.js での導出例

import { createHmac } from 'crypto';

const hmac = createHmac('sha512', signatureToken)
  .update(Buffer.from(JSON.stringify(payload)).toString('utf8'))
  .digest('hex');

Webhook エンドポイントのレスポンスに関して

設定された Webhook エンドポイントは Webhook 受信時に

• 正しく処理出来た場合は 200 OK を返す
• 正しく処理出来なかった場合は 5XX のステータスコードを返す

ことを期待します

失敗時は，72 時間で 3 回まで再送を試みます．

Webhook の設定 UI に Webhookをテスト というボタンを用意するため，それを押すことでテスト用の Webhook を発信させることが出来ます．

このボタンから発信した Webhook に関しては

{
  "webhook_id": "617fdf754b7db14ee76ec096",
  "owner_order_no": "order_no_0001",
  "tracking_code": "123456789",
  "event_occurred_at": "2019-08-24T14:15:22Z",
  "shipment_id": "617fdf754b7db14ee76ec096",
  "owner_id": "617fdf754b7db14ee76ec096",
  "is_test": true
}

という様にis_test: true というフィールドが追加されているため，Webhook を受け取るエンドポイントの方で実際に何かを更新する処理をスキップするなどする事ができます．

出荷に関するもの

返送に関するもの

商品に関するもの

入庫に関するもの