DocurainはWeb APIを使って、簡単に納品書や請求書をはじめとする、帳票を生成するサービスになります。今回はこのDocurainの使い方について、サンプルテンプレートを利用して紹介します。
帳票作成APIの実行形式について
Docurainでは基本として、次の2パターンでの利用が可能です。
- API実行時にテンプレートをアップロードする（インスタント）
- 事前にテンプレートをアップロードしておく（事前保存テンプレート）
今回は、この2つの使い方について解説します。
トークンを作成する
Docurainを実行する際には事前にトークンを発行する必要があります。トークンはトークン | Docurainより作成が可能です。まず新規追加ボタンをクリックします。
形式として繰り返し使える通常トークンと、一度だけ使えるワンタイムトークンがあります。必要に応じて選択してください。また、APIを利用許可するIPアドレスを指定します。制限しない場合には *.*.*.* を指定してください。IPアドレスのフォーマットはこちらのドキュメントを参考にしてください。
また、通常トークンの場合は有効期限も指定します。厳密な設定が不要な場合には、十分に長い有効期限を設定してください。
この記事の中ではトークンは YOUR_TOKEN として記述していきますので、ご自身のものと置き換えつつ読み進めてください。
サンプルの帳票について
今回の記事で利用するサンプルの帳票は、公式ドキュメント中のものを利用します。展開してexamplesというフォルダがある状態での利用を想定しています。
インスタントでの実行例
インスタントでの実行は、テンプレートと置き換える文字列を一緒に渡します。 template 引数でテンプレートのExcelファイルを、 entity 引数で置き換え文字列のJSONファイルを指定します。サンプルの納品書は次のようになっています。
また、置き換えるデータ（納品書.json）の内容は次のようになります。
{ "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": " 以下余白" } ] }
curlコマンドで書くと次のようになります。
curl -X POST https://api.docurain.jp/api/instant/pdf \ -H 'Authorization:token YOUR_TOKEN' \ -H 'Content-Type:multipart/form-data' \ -F 'template=@./examples/納品書.xlsx;type=application/vnd.ms-excel' \ -F 'entity=@./examples/納品書.json;type=application/json' \ -o delivery1.pdf
これを実行すると delivery1.pdf というファイルが生成されて、返却されます。
事前保存テンプレートでの実行例
テンプレートをアップロードする
事前保存テンプレートの場合は、まず管理画面のテンプレートにて、テンプレートとなるExcelファイルをアップロードします。
テンプレート名は英数字と _ 、そして - のみ利用可能です。このテンプレート名はAPIのURLにも利用されるので、識別しやすいものを設定してください。
実行する
事前保存テンプレートで実行する場合にはURLが変わるので注意してください。 TEMPLATE_NAME となっている部分を、上記のテンプレート名と置き換えてください。後は、先ほどと同じように置き換え文字列が入ったJSONファイルを指定して実行します。
curl -X POST https://api.docurain.jp/api/pdf/TEMPLATE_NAME \ -H 'Authorization:token YOUR_TOKEN' \ -H 'Content-Type:application/json' \ --data-binary @./examples/納品書.json \ -o delivery1.pdf
上記コマンドの場合も、 delivery1.pdfというPDFファイルが生成されます。
管理画面で作成する
Docurainでは管理画面でもPDFを作成できます。API利用前にテストで実行される際にお試しください。こちらでもインスタント、事前保存テンプレート双方が利用できます。
管理画面から実行する場合には、作成してあるトークンから選択します。あらかじめ作成しておいてください。
まとめ
テンプレートが定型で、繰り返し利用できる場合には事前保存テンプレートを使うのが良いでしょう。クライアントごとに体裁が異なったり、一時的に特別なテンプレートを利用する場合にはインスタントをご利用ください。
