本記事に関するお問い合わせは受け付けておりません。

はじめに

ネクストエンジンではAPIを公開しており、ご自身でアプリケーションを作成することが可能です。この記事はアプリを作ろうと思っているネクストエンジンユーザーを対象とした、アプリ作成の一連のフローを説明するものです。
この記事では開発環境の構築が主な目的です。本番環境に関してはご自身でサーバを用意するなどの対応をお願いします。

ネクストエンジンについて

ネクストエンジンとは、ネットショップのバックヤードを支えるサービスのこと。
導入社数No.1という実績があります（2014年8月時点）。
楽天やAmazon, Yahooといった多数のモールのネットショップを一元で管理できます。
2013年11月よりプラットフォーム化し、APIを公開しているので自由にアプリが作成可能です。

この記事について

対象読者

ネクストエンジンユーザー
ECをやっていて業務を効率化したい人（ネクストエンジンのアカウントが必要になります）
ネクストエンジンAPIを使ってアプリを作りたい人

手に入るもの

ネクストエンジンのメイン機能から受注伝票の情報を取得し、各ステータスと共に一覧で表示するサンプルアプリ

やること

まだ開発環境構築編をご覧になっていない方はそちらを先にご覧下さい。
この記事では環境が整っていてネクストエンジンAPIが叩ける前提で進めていきます。

より詳細なAPIの使い方と解説
サンプルアプリの作成およびソースの解説

サンプルアプリ

ソースはGitHubに上がっておりますのでご参照下さい。
https://github.com/hamee-dev/sample-order-request-status-index

ソース実行

環境構築編でSDKを設置したディレクトリにne_api_sampleというディレクトリを作成し、その下にソースを配置してください
Windowsの場合はC:¥xampp¥htdocs
Macの場合は/Library/WebServer/Documents


.
└── ne_api_sample
    ├── ReceiveOrder.php
    ├── neApiClient.php
    ├── orderRequestStatusIndex.php
    └── sample.css

次にorderRequestStatusIndex.phpのクライアントIDとクライアントシークレットを入力します。
SDKの時に使用したクライアントIDとクライアントシークレットをそのまま使用しても良いですし、同じ方法で新しくアプリを作成してそのクライアントIDとクライアントシークレットを入力してもOKです。
この状態でhttps://localhost/ne_api_sample/orderRequestStatusIndex.phpにアクセスして以下のものが表示されれば成功です。

これはメイン機能のテスト環境を発行して中身を変更していない初期状態での表示例です。
メイン機能側で様々な伝票を作成してあげると以下のように各伝票のステータスが表示されます。

ソース解説

ファイル解説

ファイル名	説明
neApiClient.php	`SDK`に入っていたものそのままで、主にネクストエンジンAPIとの通信の部分の処理をするコアクラスです
orderRequestStatusIndex.php	メインの処理と描画用の`html`が入ったファイルです
ReceiveOrder.php	受注伝票を扱うためのモデルクラスです
sample.css	スタイルを整えるためのスタイルシートです

受注伝票取得方法

メインの処理はorderRequestStatusIndex.phpを追っていきます。
$client = new neApiClient(CLIENT_ID, CLIENT_SECRET, $redirectUri);
でAPIで通信する前段階（認証等）を行っています。
115行目から実行部です。
このサンプルではexecuteSearchという、検索系のAPIを叩くための関数を用意しています。

orderRequestStatusIndex.php

// 第1引数: 先ほどの通信用の`neApiClient`のインスタンス
// 第2引数: 実行するAPIのパス
// 第3引数: 取得するフィールドの配列
// 第4引数: オプション
function executeSearch(neApiClient $client, $path, array $fields, array $opts = [])
{
    $params = $opts;
    $params['fields'] = implode(',', $fields);
    return $client->apiExecute($path, $params);
}

フィールド名一覧はマニュアルをご参照下さい（ http://api.next-e.jp/fields_receiveorder.php ）
130行目で実際に受注伝票を取得するAPIを叩いています。

orderRequestStatusIndex.php

// 受注伝票の取得
// 取得するフィールド一覧
$baseFields = [
    'receive_order_id',
    'receive_order_shop_cut_form_id',
    'receive_order_confirm_check_id',
    'receive_order_order_status_id',
    'receive_order_cancel_type_id',
    'receive_order_deposit_type_id',
    'receive_order_deleted_flag',
    'receive_order_payment_method_id',
    'receive_order_payment_method_name',
    'receive_order_statement_delivery_instruct_printing_date',
    'receive_order_send_date'
    ];
// オプション（件数制限）
$baseOptions = ['limit' => 50];
$baseOrderRequest = executeSearch($client, '/api_v1_receiveorder_base/search', $baseFields, $baseOptions);

今回の例では/api_v1_receiveorder_base/searchに$baseFieldsで指定したフィールドを50件制限で取得するようなリクエストを投げています。
例えばオプションに
$baseOptions = ['receive_order_id-eq' => 1];
と書いてあげれば伝票番号が1のもののみを取得することが可能です。
フィールド名＋演算子の形で使用することができます。
各演算子はマニュアルをご参照下さい（ http://api.next-e.jp/operator_compare.php ）
例:
出荷確定日が2015年1月1日よりも前の伝票
$baseOptions = ['receive_order_send_date-lt' => '2015-01-01 00:00:00'];
ピック指示内容がnullでないもの
$baseOptions = ['receive_order_picking_instruct-nnull];
取得したい条件を上記ルールによって作成し、オプションとして指定して下さい。

伝票明細取得方法

134行目から伝票明細の取得処理です。

orderRequestStatusIndex.php

// 受注明細の取得
// 取得するフィールド一覧
$detailFields = [
    'receive_order_id',
    'receive_order_row_stock_allocation_quantity',
    'receive_order_row_quantity',
    'receive_order_row_no',
    'receive_order_row_goods_id'
    ];
// オプション（検索条件）
$receiveOrderIds = arrayColumn($baseOrderRequest['data'], 'receive_order_id');
$detailOptions = ['receive_order_id-in' => implode(',', $receiveOrderIds)];
$detailOrderRequest = executeSearch($client, '/api_v1_receiveorder_row/search', $detailFields, $detailOptions);

基本的なAPIの叩き方、関数の使い方は受注伝票のところとほぼ同様です。
今回はoptionに、先程取得した受注伝票のIDをINで指定しています。
$detailOptions = ['receive_order_id-in' => implode(',', $receiveOrderIds)];
こうすることで各伝票の明細を一括で取得することが可能です。

受注伝票モデルのインスタンス配列を生成

受注伝票と明細を別々に取得したのでそれらをまとめて1つのオブジェクトに変換します。
147行目がその処理です。

orderRequestStatusIndex.php

// 受注伝票インスタンスの配列を生成
$receiveOrders = generateReceiveOrders($baseOrderRequest['data'], $detailOrderRequest['data']);

1つの伝票の下に複数の明細がぶらさがっている、という状態のオブジェクトを生成しています。

イメージ
受注伝票[0][明細1]
          [明細2]
受注伝票[1][明細1]
          [明細2]
          [明細3]
受注伝票[2][明細1]

その他API

このサンプルでは受注伝票・明細の他に、商品マスタと利用者情報についてのAPIを使用しています。
商品マスタのAPIの叩き方はコードの150から155行目、利用者情報に関しては158行目をご参照下さい。

orderRequestStatusIndex.php

// 発売日待ち商品を取得する
$goodsFields = [
    'goods_id',
    'goods_release_date'
    ];
$goodsOptions = ['goods_release_date-gt' => date('Y-m-d H:i:s')];
$goodsRequest = executeSearch($client, '/api_v1_master_goods/search', $goodsFields, $goodsOptions);

orderRequestStatusIndex.php

// 利用者情報（ホストを特定するのに使用）
$company = $client->apiExecute('/api_v1_login_company/info');

リクエストURI一覧はマニュアルにありますので是非ご参照下さい（ http://api.next-e.jp/request_url.php ）

ReceiveOrderクラスに関して

ReceiveOrderクラスには主に、各伝票のステータスを判定する関数が用意されております。
$receiveOrderInstance->isNewStatus();というアクセスをしてあげれば、この伝票が新規受付の状態なのかtrueかfalseが返るようになっております。

ReceiveOrder.php

    // 伝票の各ステータスを調べるインスタンスメソッド群
    // input:  void
    // output: boolean
    // 新規受付のステータスか判定する関数
    public function isNewStatus()
    {
        return ($this->base['receive_order_order_status_id'] === self::ORDER_STATUS_IMPORT_ORDER_MAIL &&
                $this->base['receive_order_cancel_type_id']  === self::AVAILABLE_ORDER &&
                $this->base['receive_order_deleted_flag']    !== self::DELETED);
    }

必要に応じてご活用下さい。

おわりに

以上でネクストエンジンAPIを使ったアプリ作成の説明を終わります。
ご自身の業務を効率化するアプリ、他社との連携用のアプリなど、カスタマイズは無限大です。
是非アプリを作成してみてください。

Developer Networkの紹介

ネクストエンジンには Developer Network (略してDevNet）という開発者向けコミュニティサイトがあります。
ここには開発ガイド、 APIリファレンス、チュートリアルなど開発の役に立つ情報が盛りだくさんです。
また開発者同士でディスカッションするコミュニティもあります。
わからないことがあればこちらに質問を投稿してください。

ネクストエンジン Developer Networkwork
https://developer.next-engine.com/