Docurainを試してみよう（サンプルデータを使って帳票を作成しよう）

DocurainはWeb APIを使って、簡単に納品書や請求書をはじめとする、帳票を生成するサービスになります。今回はこのDocurainの使い方について、サンプルテンプレートを利用して紹介します。

帳票作成APIの実行形式について

Docurainでは基本として、次の2パターンでの利用が可能です。

API実行時にテンプレートをアップロードする（インスタント）
事前にテンプレートをアップロードしておく（事前保存テンプレート）

今回は、この2つの使い方について解説します。

トークンを作成する

Docurainを実行する際には事前にトークンを発行する必要があります。トークンはトークン | Docurainより作成が可能です。まず新規追加ボタンをクリックします。

f:id:moongift:20210719121134j:plain

形式として繰り返し使える通常トークンと、一度だけ使えるワンタイムトークンがあります。必要に応じて選択してください。また、APIを利用許可するIPアドレスを指定します。制限しない場合には *.*.*.* を指定してください。IPアドレスのフォーマットはこちらのドキュメントを参考にしてください。

また、通常トークンの場合は有効期限も指定します。厳密な設定が不要な場合には、十分に長い有効期限を設定してください。

f:id:moongift:20210719121240j:plain

この記事の中ではトークンは YOUR_TOKEN として記述していきますので、ご自身のものと置き換えつつ読み進めてください。

サンプルの帳票について

今回の記事で利用するサンプルの帳票は、公式ドキュメント中のものを利用します。展開してexamplesというフォルダがある状態での利用を想定しています。

f:id:moongift:20210719121319p:plain

インスタントでの実行例

インスタントでの実行は、テンプレートと置き換える文字列を一緒に渡します。 template 引数でテンプレートのExcelファイルを、 entity 引数で置き換え文字列のJSONファイルを指定します。サンプルの納品書は次のようになっています。

f:id:moongift:20210719121709p:plain

また、置き換えるデータ（納品書.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 というファイルが生成されて、返却されます。

f:id:moongift:20210719121350j:plain

事前保存テンプレートでの実行例

テンプレートをアップロードする

事前保存テンプレートの場合は、まず管理画面のテンプレートにて、テンプレートとなるExcelファイルをアップロードします。

f:id:moongift:20210719121424j:plain

テンプレート名は英数字と _ 、そして - のみ利用可能です。このテンプレート名は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ファイルが生成されます。