ネクストエンジンAPIの使い方（アプリ実装編）

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

## はじめに

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

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

[ネクストエンジンとは](http://next-engine.net/%E3%83%8D%E3%82%AF%E3%82%B9%E3%83%88%E3%82%A8%E3%83%B3%E3%82%B8%E3%83%B3%E3%81%A8%E3%81%AF%EF%BC%9F)、ネットショップのバックヤードを支えるサービスのこと。
導入社数No.1という実績があります（2014年8月時点）。
楽天やAmazon, Yahooといった多数のモールのネットショップを一元で管理できます。
2013年11月よりプラットフォーム化し、APIを公開しているので自由にアプリが作成可能です。

## この記事について

### 対象読者

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


### 手に入るもの

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

### やること

まだ[開発環境構築編](http://qiita.com/hamee-dev/items/114aa0e45bf8d01861bd)をご覧になっていない方はそちらを先にご覧下さい。
この記事では環境が整っていてネクストエンジン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`
<pre>
.
└── ne_api_sample
    ├── ReceiveOrder.php
    ├── neApiClient.php
    ├── orderRequestStatusIndex.php
    └── sample.css
</pre>

次に`orderRequestStatusIndex.php`のクライアントIDとクライアントシークレットを入力します。
SDKの時に使用したクライアントIDとクライアントシークレットをそのまま使用しても良いですし、同じ方法で新しくアプリを作成してそのクライアントIDとクライアントシークレットを入力してもOKです。
この状態で`https://localhost/ne_api_sample/orderRequestStatusIndex.php`にアクセスして以下のものが表示されれば成功です。
![スクリーンショット 2015-02-26 15.02.08.png](https://qiita-image-store.s3.amazonaws.com/0/70505/299691da-626f-e8f2-f041-afbedce8982a.png)
これはメイン機能のテスト環境を発行して中身を変更していない初期状態での表示例です。
メイン機能側で様々な伝票を作成してあげると以下のように各伝票のステータスが表示されます。
![スクリーンショット 2015-02-23 15.14.46.png](https://qiita-image-store.s3.amazonaws.com/0/70505/7fd50e9a-128f-7978-5cc9-2b407e515b9e.png)



## ソース解説
### ファイル解説

| ファイル名 | 説明 |
|:-----------|:------------|
| 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を叩くための関数を用意しています。

```php: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を叩いています。

```php: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行目から伝票明細の取得処理です。

```php: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行目がその処理です。

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

1つの伝票の下に複数の明細がぶらさがっている、という状態のオブジェクトを生成しています。
<pre>イメージ
受注伝票[0][明細1]
          [明細2]
受注伝票[1][明細1]
          [明細2]
          [明細3]
受注伝票[2][明細1]
</pre>

### その他API

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

```php: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);
```

```php: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`が返るようになっております。

```php: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](https://developer.next-engine.com) (略してDevNet）という開発者向けコミュニティサイトがあります。
ここには [開発ガイド](https://developer.next-engine.com/guide) 、 [APIリファレンス](https://developer.next-engine.com/api) 、チュートリアルなど開発の役に立つ情報が盛りだくさんです。
また開発者同士でディスカッションする [コミュニティ](https://developer.next-engine.com/forum/active) もあります。
わからないことがあれば [こちら](https://developer.next-engine.com/forum/active) に質問を投稿してください。

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