Docurain Labo

Docurainサービス開発日記

【エンジニア向け】これできっと分かる。Docurainのつまづきポイント解説します

Docurainは帳票エンジンと銘打っていますが、使いこなすともっともっとたくさんのことが実現できます。この記事でははじめてDocurainに触れる方が感じるであろう疑問点や、つまづきポイントを解説します。スムーズな帳票作成を実現させるためにも、ぜひご覧ください。

続きを読む

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ファイルが生成されます。

管理画面で作成する

Docurainでは管理画面でもPDFを作成できます。API利用前にテストで実行される際にお試しください。こちらでもインスタント、事前保存テンプレート双方が利用できます。

f:id:moongift:20210719121501j:plain

管理画面から実行する場合には、作成してあるトークンから選択します。あらかじめ作成しておいてください。

まとめ

テンプレートが定型で、繰り返し利用できる場合には事前保存テンプレートを使うのが良いでしょう。クライアントごとに体裁が異なったり、一時的に特別なテンプレートを利用する場合にはインスタントをご利用ください。

帳票開発を、もっと簡単に「Docurain-ドキュレイン-」|帳票開発エンジン

複雑な集約条件においても数式自動シフトが使えるようになりました

明細のある見積書や請求書のような帳票では、ページごとの合計金額、全ページの総合計金額のような項目がよくあります。

1ページ目 2ページ目
f:id:yutay:20210729172942p:plain:w300 f:id:yutay:20210729172947p:plain:w300

その際にDourainでは簡単にページごと、グループごと、全ページの各単位で金額を計算することが可能です。

作成するテンプレートで範囲の定義を行い、その範囲ごとに計算を行うようにすることで実現させます。

早速やってみましょう!

上に載せたような見積書を作成します。

サンプルのテンプレートとデータ(JSON)です。
サンプルダウンロード

範囲について

範囲は#scopeを使用して定義します。

今回、範囲は以下の「全て」・「顧客」・「ページ」の3つの範囲を定義します。

f:id:yutay:20210729164123p:plain

範囲の定義は以下のように書きます。それぞれの範囲を#scope - #endで囲みます。

#scopeの構文は次の通りです。

#scope([範囲の名称] as [変数名])

f:id:yutay:20210729192410p:plain

「全て」の範囲定義の通り、as [変数名] は省略可能です。範囲の名称を変数として使用する必要がない場合(範囲の名称が固定で良い場合)は、as [変数名] を省略します。

これで範囲の定義は完了です。

範囲を使用した計算について

範囲ごとに計算を行うにはDR.SHIFT_FORMULA()を使用します。

DR.SHIFT_FORMULA()は数式の自動シフトを適応可能にしてくれる機能です。*1

依然として Excelの数式そのまま であるため、Excelがもつ数式記述支援機能(構文チェック、引数チェックなど)を全て活用することができます!!

DR.SHIFT_FORMULA()の構文は次の通りです。

=DR.SHIFT_FORMULA(値or式,"scope=[#scope()で代入している変数], target=[対象とするセル範囲]")

scopeを省略した場合、そのセルが所属する印刷範囲を範囲として見なします。

targetの値は、

  • all スコープ内の全ての範囲
  • nearest スコープ内の最近傍セル範囲

のいずれかを指定します。省略した場合はnearestと判定されます。

では、先ほど#scopeにて定義した範囲をDR.SHIFT_FORMULA()から参照して計算を行います。

サンプルを確認しつつ以下をご覧ください。

  • 全ページの合計金額

    f:id:yutay:20210730095220p:plain =DR.SHIFT_FORMULA(SUM(D20),"scope=全て, target=all")とすることで、範囲名称が「全て」の範囲の合計金額セル(D20)を参照しSUMにて合計を算出します。それにより総合計金額を出力します。

  • 顧客ごとの合計金額

    f:id:yutay:20210730100414p:plain =DR.SHIFT_FORMULA(SUM(J31),"scope=$outerScope, target=all")とすることで、範囲名称が$outerScope(顧客ごと)の範囲のページ合計セル(J31)を参照しSUMにて合計を算出します。それにより顧客ごとの合計金額を出力します。

  • ページごとの合計金額

    f:id:yutay:20210730100428p:plain =DR.SHIFT_FORMULA(SUM(J29:J29),"scope=$innerScope, target=all")とすることで、範囲名称が$innerScope(ページごと)の範囲の明細金額セル(J29)を参照しSUMにて合計を算出します。それによりページごとの合計金額を出力します。

  • 明細ごとの金額 f:id:yutay:20210729194310p:plain =DR.SHIFT_FORMULA(G29*I29)とすることで、数量(G29)*単価(I29)を算出します。それにより明細ごとの合計金額を出力します。 DR.SHIFT_FORMULAを使うことで明細行が複数になってもG29・I29のセル範囲は自動シフトするため、何も意識せずテンプレート上で該当のセルを指定すれば良いです。

データを準備して出力

今回使用するデータは以下です。

{
  "顧客リスト": [
    {
      "顧客名": "株式会社 顧客1",
      "見積No": 1127,
      "見積日": "2021-07-29",
      "明細": [
                { "名称": "項目1-1", "数量": 1, "単位": "", "単価": 10000 },
                { "名称": "項目1-2", "数量": 2, "単位": "", "単価": 10000 },
               ...中略...
                { "名称": "項目1-17", "数量": 17, "単位": "", "単価": 10000 }
      ]
    },
    {
      "顧客名": "株式会社 顧客2",
      "見積No": 1128,
      "見積日": "2021-07-29",
      "明細": [
                { "名称": "項目2-1", "数量": 1, "単位": "", "単価": 20000 },
                { "名称": "項目2-2", "数量": 2, "単位": "", "単価": 20000 },
               ...中略...
                { "名称": "項目2-20", "数量": 20, "単位": "", "単価": 20000 }
      ]
    }
  ]
}

出力結果です。

(サンプルテンプレートのA9セルにて明細15行ごとに分割して改ページするようにしています)

1ページ目(総合計)
f:id:yutay:20210729195227p:plain:w300
2ページ目(顧客1の1ページ目) 3ページ目(顧客1の2ページ目)
f:id:yutay:20210729195256p:plain:w300 f:id:yutay:20210729195303p:plain:w300
4ページ目(顧客2の1ページ目) 5ページ目(顧客2の2ページ目)
f:id:yutay:20210729195308p:plain:w300 f:id:yutay:20210729195319p:plain:w300

それぞれの範囲で計算され、「ページ合計金額」、「顧客ごとの合計金額」、「全ての合計金額」が正しく計算されてますね。

今回作成したサンプルは、無料トライアルページからも登録不要で試すことが出来ます。

他にも様々な機能がありますので、ぜひアカウント無料登録してマニュアルを参照しお試しください。

*1:数式の自動シフト:DocurainにてExcel/PDF出力後に命令行が削除されることを意識せずに、Docurainテンプレート上でExcelのセル範囲をそのまま使えることを指します。Docurainテンプレートにて、とあるセルを参照している数式がある場合、命令行が削除された後の行番号を考慮した数式でなければなりませんが、その命令行が削除された後の行番号に自動に適応します。

デザインを刷新しました

ホームページおよび管理コンソール画面のデザインを刷新しました。

機能面でもビジネス面でもステージが切り替わりつつあり、 「次の3年」を戦うために相応しい方向性へと揃えたつもりです。

f:id:takahashikzn:20210626122603p:plain

f:id:takahashikzn:20210626122642p:plain