公開 API の使い方 (技術者向け)

作成日: 2026-10-30更新日: 2026-10-30

公開 API を使うと、EC・基幹システム・RPA などから、PRING を入れた kintone アプリにレコードを登録し、そのアプリの PRING テンプレートで帳票を生成して、ファイルを受け取るまでを HTTPS で行えます。Pro プランで使えます。設定画面の「API」タブで PRING の API キーを発行し、アプリごとに kintone の API トークンを登録してから、Authorization: Bearer ヘッダーにキーを付けて呼びます。

公開 API は Pro プランで利用できます。

概要と前提

PRING の公開 API は、kintone の画面を開かずに、外部のシステムから PRING の帳票出力を使うための HTTPS の API です。主な使い方は次の 3 つです。

• 外部のシステムから kintone アプリにレコードを登録し、そのまま帳票 (PDF・Excel・Word) まで作る
• kintone にすでにあるレコードから帳票を作る
• 作った帳票のファイルを受け取る

使い始める前に、次の 3 つがそろっていることを確かめてください。

1. Pro プランで契約している。 プランは設定画面の「プランと料金」タブで確かめられます (プランと料金)。
2. 呼び出す kintone アプリに PRING が入っていて、使うテンプレートが登録されている。 帳票は、そのアプリの PRING のテンプレートで作ります (テンプレートの登録)。
3. 設定画面の「自動化と連携」の「API」タブで、アプリごとに kintone の API トークンを登録している。 トークンは、kintone のアプリの設定の「API トークン」で作ります。「API」タブの「このアプリの kintone API トークン」に貼り付けて「トークンを保存」を押すと、「登録済み (日付)」と出ます。消すときは「トークンを消す」を押し、「もう一度押すと消します」と出たら、もう一度押します。権限は「レコード追加」「レコード編集」「レコード閲覧」の 3 つだけにしてください。PRING はトークンを暗号化して保存し、レコードの登録と取得のときだけ使います。

API の入り口は https://api.pring.tech/api/v1/ です。リクエストとレスポンスは JSON (UTF-8) で、帳票のファイルだけはバイナリで受け取ります。

認証

公開 API は、PRING の API キー で呼び出し元を確かめます。kintone の API トークン (前提の 3) とは別のものです。kintone のトークンは PRING が kintone を呼ぶために使い、PRING の API キーはあなたのシステムが PRING を呼ぶために使います。

API キーを発行する

1. kintone で、PRING を入れたアプリのプラグイン設定を開きます。
2. 上の段の「自動化と連携」を選び、「API」タブを開きます。Pro 以外のプランでは「公開 API は Pro プランで使えます。」と「プランと料金を開く」だけが出て、キーは発行できません。
3. 「API キー」の「キーを発行」を押し、「名前」に用途の分かる名前 (例: 「EC 連携 本番」) を入れます。
4. 「スコープ」で、使うもの (下の表) を選びます。必要なものだけにしてください。
5. 開発・検証に使うときは「テスト用のキーにする (prk_test_)」を選びます。
6. 必要なら「許可する IP アドレス」に、1 行に 1 つずつ IP アドレスか CIDR を入れます (任意、20 個まで。下の「IP アドレスの制限」)。
7. 「発行する」を押すと、キーが 1 度だけ 表示されます。「コピー」で写し、次の「キーの保管」のとおりに保管してから「閉じる」を押します。閉じると、もう表示できません。

発行したキーは、「API キー」の表に、名前 (キーは prk_live_… と末尾の 4 文字だけ)・種類・スコープ・許可する IP・発行日・最後に使った日・状態で並びます。有効なキーは 20 個まで持てます。連携先のシステムごとにキーを分けると、1 つを失効しても、ほかの連携は止まりません。

キーの形

キーは prk_live_ または prk_test_ のあとに 16 進数 64 桁が続く 1 行の文字列です。先頭で本番用とテスト用を見分けられるので、ログの調査やシークレットの棚卸しのときに確かめてください。

キーの付け方

すべてのリクエストに、Authorization ヘッダーで Bearer に続けてキーを付けます。

GET /api/v1/apps HTTP/1.1
Host: api.pring.tech
Authorization: Bearer prk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• キーを URL のクエリ (?key= など) に入れないでください。受け付けません。URL はアクセスログやブラウザの履歴に残ります。
• 通信は HTTPS だけです。HTTP では受け付けません。

スコープ

キーには、使える操作 (スコープ) を付けます。付いていない操作を呼ぶと 403 になります。

アプリとテンプレートの一覧 (GET /api/v1/apps) は、どのスコープのキーでも呼べます。レコードを登録して PDF まで受け取る連携なら、3 つすべてが必要です。帳票を作るだけでレコードを登録しない連携なら、render と files:read で足ります。

401 と 403 の違いと直し方

401 はキーそのものの問題、403 はキーは正しいが権限や設定の問題、と覚えてください。401 のときに同じキーで再試行しても直りません。

キーの保管

• キーはパスワードと同じ扱いです。ソースコード、Git のリポジトリ、チャット、メールに書かないでください。
• 連携先のシステムのシークレット管理 (クラウドのシークレットマネージャー、CI のシークレット、環境変数など) に保管し、プログラムからはそこから読み込みます。
• アプリのログ・エラーの記録・監視ツールに、キーや Authorization ヘッダーを出さないでください。記録するなら先頭の prk_live_ と末尾の数文字だけにします。
• 担当者が替わったとき、連携をやめたときは、そのキーを失効します。

失効と再発行

• 失効: 「API」タブの「API キー」の表で、そのキーの「失効」を押し、「もう一度押すと失効します」と出たら、もう一度押します。「失効しました。このキーはもう使えません。」と出て、状態が「失効」になります。失効したキーは、その時から 401 になります。元に戻せません。
• 再発行 (差し替え): 止めずに替えるときは、①新しいキーを発行する ②連携先のシークレットを新しいキーに替える ③新しいキーで動くことを確かめる ④古いキーを失効する、の順に進めます。キーは複数を同時に使えるので、③までのあいだも連携は止まりません。
• 漏れたかもしれないとき: 迷わず、すぐに失効してください。そのあと新しいキーを発行して差し替えます。

IP アドレスの制限 (任意)

キーに、呼び出しを許す IP アドレスか CIDR を 20 個まで付けられます。付けないときは「制限なし」です。付けると、そのアドレス以外からの呼び出しは 403 になります。固定の IP アドレスから呼ぶサーバー間の連携では、付けておくと、キーが漏れたときの被害を小さくできます。

使用例

例では、キーを環境変数 PRING_API_KEY から読みます。アプリ番号 19、テンプレート tpl_invoice、kintone のフィールドコード (顧客名 など) は、お使いのアプリに合わせて読み替えてください。アプリ番号とテンプレートの ID は、次の e) の一覧で確かめられます。

レコードの値は、kintone の REST API と同じ形 ({"フィールドコード": {"value": 値}}) で送ります。

すぐに動かせるサンプル

「レコードを登録する → PDF を作る → ダウンロードする」までを通しで行うサンプルです。

• register_render_download.sh (curl)
• register_render_download.mjs (Node.js 18 以上)
• register_render_download.py (Python、requests)

サンプルは次の環境変数を読みます。

a) レコードを登録して、PDF まで 1 回で作る

POST /api/v1/apps/{appID}/records に ?render=<テンプレートID>&format=pdf を付けると、登録に続けて帳票を作ります。形式は pdf・xlsx・docx から選べます (テンプレートが対応している形式)。必要なスコープは records:write と render です。

curl

curl -sS -X POST "https://api.pring.tech/api/v1/apps/19/records?render=tpl_invoice&format=pdf" \
  -H "Authorization: Bearer $PRING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "record": {
      "顧客名": { "value": "サンプル商事" },
      "請求日": { "value": "2026-10-31" },
      "明細": { "value": [
        { "value": { "品名": { "value": "商品A" }, "数量": { "value": "2" }, "単価": { "value": "10000" } } }
      ] }
    }
  }'

Node.js (fetch)

const res = await fetch("https://api.pring.tech/api/v1/apps/19/records?render=tpl_invoice&format=pdf", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PRING_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    record: {
      顧客名: { value: "サンプル商事" },
      請求日: { value: "2026-10-31" },
    },
  }),
});
if (!res.ok) throw new Error(`${res.status} ${(await res.json()).detail}`);
const { id, file } = await res.json();
console.log("record", id, "file", file.id);

Python (requests)

import os, requests

res = requests.post(
    "https://api.pring.tech/api/v1/apps/19/records",
    params={"render": "tpl_invoice", "format": "pdf"},
    headers={"Authorization": f"Bearer {os.environ['PRING_API_KEY']}"},
    json={"record": {"顧客名": {"value": "サンプル商事"}, "請求日": {"value": "2026-10-31"}}},
    timeout=60,
)
res.raise_for_status()
body = res.json()
print("record", body["id"], "file", body["file"]["id"])

応答 (201 Created) の例:

{
  "id": "105",
  "revision": "1",
  "file": {
    "id": "fil_01HXY...",
    "url": "https://api.pring.tech/api/v1/files/fil_01HXY...",
    "expires_at": "2026-10-31T09:15:00Z"
  }
}

id は kintone のレコード番号です。ファイルは c) の方法で受け取ります。?render= を付けなければ、レコードの登録だけを行い、id と revision だけを返します。レコードの更新は PUT /api/v1/apps/{appID}/records/{recordID}、取得は GET /api/v1/apps/{appID}/records/{recordID} です。更新のときに revision を付けると、kintone がそのリビジョンと照らし合わせます。レコードがその間に変わっていたら 409 になります。

まとめて登録する

record の代わりに records に配列を入れると、1 回で 100 件まで登録できます。101 件以上は 413 になります。

{
  "records": [
    { "顧客名": { "value": "サンプル商事" }, "請求日": { "value": "2026-10-31" } },
    { "顧客名": { "value": "見本工業" }, "請求日": { "value": "2026-10-31" } }
  ]
}

?render= を付けないときは、201 で、登録したレコードの番号と revision を送った順に返します。

{
  "ids": ["105", "106"],
  "revisions": ["1", "1"]
}

records に ?render= を付けたときは、帳票の生成を非同期で行い、202 と job_id を返します (d)。

b) 既存のレコードから帳票を作る

POST /api/v1/apps/{appID}/records/{recordID}/render に、テンプレート (template) と形式 (format、任意) を送ります。attach_to_field に kintone の添付ファイル欄のフィールドコードを入れると、そのレコードの添付ファイル欄にも保存します。必要なスコープは render です。

curl

curl -sS -X POST "https://api.pring.tech/api/v1/apps/19/records/105/render" \
  -H "Authorization: Bearer $PRING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template": "tpl_invoice", "format": "pdf", "attach_to_field": "請求書PDF" }'

Node.js (fetch)

const res = await fetch("https://api.pring.tech/api/v1/apps/19/records/105/render", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PRING_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ template: "tpl_invoice", format: "pdf", attach_to_field: "請求書PDF" }),
});
const { file, attached_to, warnings } = await res.json();

Python (requests)

res = requests.post(
    "https://api.pring.tech/api/v1/apps/19/records/105/render",
    headers={"Authorization": f"Bearer {os.environ['PRING_API_KEY']}"},
    json={"template": "tpl_invoice", "format": "pdf", "attach_to_field": "請求書PDF"},
    timeout=60,
)
file = res.json()["file"]

応答 (201 Created) の例:

{
  "file": {
    "id": "fil_01HXY...",
    "url": "https://api.pring.tech/api/v1/files/fil_01HXY...",
    "expires_at": "2026-10-31T09:15:00Z"
  },
  "attached_to": "請求書PDF",
  "warnings": []
}

file は a) と同じ形です。attached_to は、attach_to_field を付けたときに、保存した添付ファイル欄のフィールドコードが入ります。この API は結果をそのまま 201 で返し、202 にはなりません。

API の添付をファイルログに記録する

API で添付ファイル欄に保存したファイルをファイルログアプリにも記録するには、「API」タブに「ファイルログの API トークン」を登録します。

1. ファイルログアプリの「アプリの設定 > API トークン」で、トークンを作ります。権限は「レコード追加」だけにしてください。
2. 「API」タブの「ファイルログの API トークン」に貼り付け、「ログのトークンを保存」を押します。

登録していないあいだは、「API」タブに「ファイルログのトークン未登録 (API の添付は記録されません)」と出ます。ファイルログアプリがまだ無いときは、先に「監査ログ」タブでファイルログアプリを作ってください。

トークンを登録しないまま attach_to_field を付けると、ファイルは添付ファイル欄に保存されますが、warnings に "audit_not_recorded" が入ります。このとき、ファイルログアプリにはそのファイルの行がありません。

c) ファイルを受け取る

GET /api/v1/files/{fileID} を呼ぶと、1 回だけ使えるリンク (/api/v1/files/{fileID}/content?t=…) へ 302 で転送します。転送先からファイルを受け取ってください。このリンクには Authorization ヘッダーは要りません。必要なスコープは files:read です。

• 1 回だけ使えるリンクは 15 分 で切れます。生成したファイルも、生成から 15 分で削除します。
• 使い終わったリンクや切れたリンクは 410 になります。もう一度受け取るときは、ファイルの削除前に GET /api/v1/files/{fileID} から呼び直してください。
• 残しておく帳票は、b) の attach_to_field で kintone に保存してください。

curl (-L で転送先までたどります)

curl -sS -L -o invoice.pdf "https://api.pring.tech/api/v1/files/fil_01HXY..." \
  -H "Authorization: Bearer $PRING_API_KEY"

Node.js (fetch) (fetch は転送を自動でたどります)

import { writeFile } from "node:fs/promises";

const res = await fetch(`https://api.pring.tech/api/v1/files/${file.id}`, {
  headers: { Authorization: `Bearer ${process.env.PRING_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}`);
await writeFile("invoice.pdf", Buffer.from(await res.arrayBuffer()));

Python (requests) (requests も転送を自動でたどります)

res = requests.get(
    f"https://api.pring.tech/api/v1/files/{file['id']}",
    headers={"Authorization": f"Bearer {os.environ['PRING_API_KEY']}"},
    timeout=60,
)
res.raise_for_status()
open("invoice.pdf", "wb").write(res.content)

d) 非同期: 202 と job_id

records でまとめて送り、?render= を付けたときだけ、すぐには帳票を返さず 202 Accepted と job_id を返します。レコードの登録はこの時点で終わっていて、ids と revisions も返ります。1 件の登録 (a) と既存のレコードからの生成 (b) は 202 になりません。

{
  "job_id": "job_01HXY...",
  "status": "queued",
  "poll_url": "/api/v1/jobs/job_01HXY...",
  "ids": ["105", "106"],
  "revisions": ["1", "1"]
}

GET /api/v1/jobs/{jobID} を、status が done か failed になるまで間を空けて呼んでください。必要なスコープは render です。

status は queued (順番待ち) → running (処理中) → done (完了) か failed (失敗) と進みます。ジョブには次の項目が入ります。

• total: 全体の件数。done: 終わった件数。failed: 失敗した件数。
• detail: status が failed のときの理由。
• result_url: done になると入ります。すべての帳票をまとめた ZIP 1 つの署名付きの URL です。24 時間使えます。
• files: 同じ ZIP が [{"url": …, "expires_at": …}] の形で入ります。
• expires_at: 切れる時刻。

完了したジョブの例:

{
  "status": "done",
  "total": 2,
  "done": 2,
  "failed": 0,
  "result_url": "https://...",
  "files": [
    { "url": "https://...", "expires_at": "2026-11-01T09:00:00Z" }
  ],
  "expires_at": "2026-11-01T09:00:00Z"
}

curl

curl -sS "https://api.pring.tech/api/v1/jobs/job_01HXY..." -H "Authorization: Bearer $PRING_API_KEY"

Node.js (fetch)

async function waitJob(jobId) {
  for (let i = 0; i < 60; i++) {
    const res = await fetch(`https://api.pring.tech/api/v1/jobs/${jobId}`, {
      headers: { Authorization: `Bearer ${process.env.PRING_API_KEY}` },
    });
    const job = await res.json();
    if (job.status === "done") return job.result_url;
    if (job.status === "failed") throw new Error(job.detail ?? "job failed");
    await new Promise((r) => setTimeout(r, Math.min(2000 * 2 ** Math.floor(i / 5), 30000)));
  }
  throw new Error("timeout");
}

Python (requests)

import time

def wait_job(job_id):
    for i in range(60):
        job = requests.get(
            f"https://api.pring.tech/api/v1/jobs/{job_id}",
            headers={"Authorization": f"Bearer {os.environ['PRING_API_KEY']}"},
            timeout=30,
        ).json()
        if job["status"] == "done":
            return job["result_url"]
        if job["status"] == "failed":
            raise RuntimeError(job.get("detail", "job failed"))
        time.sleep(min(2 * 2 ** (i // 5), 30))
    raise TimeoutError(job_id)

ポーリングの間隔は 2 秒から始め、だんだん長くしてください (例では最長 30 秒)。短い間隔で呼び続けると、レート制限 (429) に当たります。

e) アプリとテンプレートの一覧

GET /api/v1/apps は、PRING を入れたアプリと、そのアプリのテンプレートの一覧を返します。アプリ番号とテンプレートの ID を確かめるのに使います。

curl

curl -sS "https://api.pring.tech/api/v1/apps" -H "Authorization: Bearer $PRING_API_KEY"

Node.js (fetch)

const res = await fetch("https://api.pring.tech/api/v1/apps", {
  headers: { Authorization: `Bearer ${process.env.PRING_API_KEY}` },
});
const { apps } = await res.json();
for (const a of apps) console.log(a.app_id, a.name, a.templates.map((t) => t.id));

Python (requests)

apps = requests.get(
    "https://api.pring.tech/api/v1/apps",
    headers={"Authorization": f"Bearer {os.environ['PRING_API_KEY']}"},
    timeout=30,
).json()["apps"]
for a in apps:
    print(a["app_id"], a["name"], [t["id"] for t in a["templates"]])

応答の例:

{
  "apps": [
    {
      "app_id": "19",
      "name": "請求",
      "api_token_registered": true,
      "templates": [
        { "id": "tpl_invoice", "name": "請求書", "formats": ["pdf", "xlsx"] }
      ]
    }
  ]
}

api_token_registered が false のアプリは、「API」タブで kintone の API トークンを登録するまで、レコードの登録と取得ができません。

エラー

エラーは RFC 7807 (Problem Details) の形の JSON (Content-Type: application/problem+json) で返します。detail に、何を直せばよいかを書きます。

{
  "type": "https://pring.tech/ja/help/developer/public-api#errors",
  "title": "Forbidden",
  "status": 403,
  "detail": "This API key does not have the render scope.",
  "instance": "/api/v1/apps/19/records/105/render"
}

kintone がレコードの値を受け付けなかったときは、errors に kintone のメッセージがフィールドコードごとに入ることがあります ({"フィールドコード": ["メッセージ", ...]})。

再試行してよいのは 429・502・5xx です。429 の応答には Retry-After ヘッダー (秒) が付きます。その秒数だけ待ってから送り直してください。400・401・403・404・409・413・422 は、同じリクエストを送り直しても結果は変わりません。レコードの登録 (POST …/records) を再試行するときは、前の試行で登録できていないかを先に確かめてください (二重登録を避けるため)。

制限

• 件数: 1 リクエストで 1 レコード、または records で 100 件までです。101 件以上は 413 になります。プランの 1 リクエストあたりの上限を超えると 422 になります。
• レート制限: API キーごとに毎秒 100 リクエストまでです。契約 (テナント) ごとの上限もあります。超えると 429 になります。
• 枚数: API で生成した帳票の枚数は、Pro の月間の込み枚数 (100,000 枚) に入ります。数え方は画面からの出力と同じです (利用枚数の上限)。
• ファイルの保存期間: 生成したファイルは 15 分で削除します。ジョブの ZIP (result_url) は 24 時間で切れます。残すときは attach_to_field で kintone に保存します。
• ファイルログ: API で添付したファイルをファイルログアプリに記録するには、「API」タブに「ファイルログの API トークン」を登録します (b)。登録していないときは、warnings に audit_not_recorded が入ります。
• レコードの値: PRING のサーバーには保存しません (処理中のメモリでだけ扱います)。
• 急に呼び出しが増えたときなど、不正な利用と見られる呼び出しは、一時的に止めることがあります。

執筆・運営: TechJapan合同会社 (PRING 開発チーム) (開発・運営元) · お問い合わせ