PHPでDocurainのインスタントAPIを使ってみる

DocurainはWeb APIを使って簡単に納品書や請求書をはじめとする、帳票を生成するサービスになります。基本的にシステムから、まとめて帳票を出力することになります。そこで今回はPHPから帳票を作成するサンプルコードを解説します。

利用するライブラリについて

今回は Guzzle を利用します。インストールはcomposerを使って行えます。

$ composer require guzzlehttp/guzzle

必要なもの

今回はインスタントAPI（ローカルに帳票テンプレートのExcelファイルがある）を実行します。従って必要なものは次の通りです。

PHPの実行環境
Docurainのトークン
Excelのテンプレートファイル

ライブラリの読み込み

まず Guzzle を読み込みます。

require "vendor/autoload.php";
use GuzzleHttp\Client;

次にDocurainのトークンと帳票テンプレートのパスを設定します。 YOUR_TOKEN はDocurainのトークン | Docurainにて取得したトークンと置き換えてください。

// Docurainで作成したトークン
$token = "YOUR_TOKEN";
// テンプレートのパス
$template_path = "./delivery.xlsx";

テンプレートに適用するパラメータはJSONファイルから読み込んでも良いですが、今回は連想配列で定義しています。以下は抜粋です（全体は記事の最後でコード中で掲載しています）。

// テンプレートに適用するパラメータ
$parameters = [
  "date" => "2019-02-20",
  "customer" => [
    "zip" => "123-456",
    // 省略
  ],
  "orders" => [
    [
      "name" => " カネダ Oリング 油圧用 (ISO型)",
      "code" => "NBR S10 7.8 Φ20",
      "count" => 2,
      "unitPrice" => 300,
      "totalPrice" => 600,
      "notes" => "",
    ],
    // 省略
    [
      "name" => "  以下余白",
    ]
  ]
];

出力フォーマットを指定します。今回はPDFですが、他にも多くのフォーマットを指定できます。

// 出力フォーマット
$output_type = "pdf"; // 他に xlsx, xls, pptx, ppt, png, jpg, gif, svg が指定できます

これらの引数を指定して関数（これから作成します）を実行します。

// APIリクエストの実行
$response = generate_document_instant($token, $template_path, $parameters, $output_type);

関数の内容

続いて generate_document_instant の実装を解説します。

function generate_document_instant($token, $template_path, $parameters, $type) {
  // この内容を解説します
}

まずAPIのエンドポイントを定義します。インスタントAPIの場合、出力フォーマットによってURLが異なります。

// インスタントAPIのURLエンドポイント
$url = "https://api.docurain.jp/api/instant/{$type}";

次にリクエストヘッダーを定義します。これは Authorization でトークンを指定するのみです。

// ヘッダー
$headers = [
    "Authorization" => "token {$token}"
];

次にエンティティ（帳票テンプレート内で利用する置き換え文字列）を準備します。 json_encode 関数で連想配列を文字列化します。

// エンティティ（置き換え文字列）の準備
$entity = [
    "name" => "entity",
    "contents" => json_encode($parameters),
    "headers"  => ["Content-Type" => "application/json"]
];

次に帳票テンプレートを読み込みます。テンプレートの内容は file_get_contents 関数で読み込みます。

// テンプレートの準備
$template = [
    "name" => "template",
    "contents" => file_get_contents($template_path),
    "headers"  => ["Content-Type" => mime_content_type($template_path)],
    "filename" => basename($template_path)
];

後はこれらの変数をまとめてGuzzleのリクエストオプションにします。

// Guzzle用のパラメータ設定
$options = [
    "http_errors" => false,
    "headers" => $headers,
    "multipart" => [$entity, $template]
];

そしてリクエストを実行し、それをそのまま関数の返り値とします。

// HTTPクライアントの作成
$client = new Client();
// リクエストの実行
return $client->request("POST", $url, $options);

返り値の判定

Docurainからのレスポンスは 200 で返ってくるかどうかで処理成否を判定できます。

// レスポンスステータスの判定
if ($response->getStatusCode() > 200) {
    // リクエスト成功（後述します）
} else {
    // APIリクエストエラーの場合
    echo $response->getBody();
}
echo PHP_EOL;

処理が成功した場合には、ファイル名を指定して file_put_contents にてレスポンス内容を出力すれば帳票として保存されます。

// 出力ファイル名
$file_name = "delivery.$output_type";
// 現在のディレクトリを取得
$cd = getcwd();
// ファイルの書き込み
file_put_contents("$cd/$file_name", $response->getBody());
echo "Saved. $cd/$file_name";

処理全体は次のようになります。

<?php
require "vendor/autoload.php";
use GuzzleHttp\Client;
// Docurainで作成したトークン
$token = "YOUR_TOKEN";
// テンプレートのパス
$template_path = "./delivery.xlsx";
// テンプレートに適用するパラメータ
$parameters = [
  "date" => "2019-02-20",
  "customer" => [
    "zip" => "123-456",
    "address1" => "東京都調布市松濤1146",
    "address2" => "パレットハウス徳丸 109",
    "name" => "水谷 知明",
  ],
  "shop" => [
    "name" => "Sample Shop Web通販事業部",
    "zip" => "123-5678",
    "address" => "東京都板橋区東坂下1-3-2",
    "staffName" => "堀口",
  ],
  "notes" => "",
  "tax" => 4152,
  "sum" => 56052,
  "qrCode" => "fsa89gb43wkfdakdsaf8v9ergbhjkfrtdlsgyre89sgf43qgfdr",
  "barCode" => "2112345678900",
  "orders" => [
    [
      "name" => "AWE Sシリーズ CO2 減圧レギュレータ",
      "code" => "2KW25-S",
      "count" => 1,
      "unitPrice" => 32400,
      "totalPrice" => 32400,
      "notes" => "",
    ],
    [
      "name" => " NESCO R134a ボールゲージ式マニホールドキット",
      "code" => "AR44-FN",
      "count" => 1,
      "unitPrice" => 18900,
      "totalPrice" => 18900,
      "notes" => "",
    ],
    [
      "name" => " カネダ Oリング 油圧用 (ISO型)",
      "code" => "NBR S10 7.8 Φ20",
      "count" => 2,
      "unitPrice" => 300,
      "totalPrice" => 600,
      "notes" => "",
    ],
    [
      "name" => "  以下余白",
    ]
  ]
];
// 出力フォーマット
$output_type = "svg"; // 他に xlsx, xls, pptx, ppt, png, jpg, gif, svg が指定できます

function generate_document_instant($token, $template_path, $parameters, $type) {
    // インスタントAPIのURLエンドポイント
    $url = "https://api.docurain.jp/api/instant/{$type}";
    // ヘッダー
    $headers = [
        "Authorization" => "token {$token}"
    ];
    // エンティティ（置き換え文字列）の準備
    $entity = [
        "name" => "entity",
        "contents" => json_encode($parameters),
        "headers"  => ["Content-Type" => "application/json"]
    ];
    // テンプレートの準備
    $template = [
        "name" => "template",
        "contents" => file_get_contents($template_path),
        "headers"  => ["Content-Type" => mime_content_type($template_path)],
        "filename" => basename($template_path)
    ];
    // Guzzle用のパラメータ設定
    $options = [
        "http_errors" => false,
        "headers" => $headers,
        "multipart" => [$entity, $template]
    ];
    // HTTPクライアントの作成
    $client = new Client();
    // リクエストの実行
    return $client->request("POST", $url, $options);
}

// APIリクエストの実行
$response = generate_document_instant($token, $template_path, $parameters, $output_type);

// レスポンスステータスの判定
if ($response->getStatusCode() === 200) {
    // 出力ファイル名
    $file_name = "delivery.$output_type";
    // 現在のディレクトリを取得
    $cd = getcwd();
    // ファイルの書き込み
    file_put_contents("$cd/$file_name", $response->getBody());
    echo "Saved. $cd/$file_name";
} else {
    // APIリクエストエラーの場合
    echo $res->getBody();
}

echo PHP_EOL;