API dokumen

API dokumen mengisi template dengan data yang Anda kirim sebagai JSON (dari ERP, formulir web, atau skrip) tanpa record di baliknya. Anda menerima tautan ke dokumen jadi, dalam format output template atau format yang Anda minta.

API ini bekerja untuk semua jenis template. Sumber data template itu sendiri tidak dipakai: JSON yang Anda kirim adalah record-nya.

Siapa yang bisa menggunakannya

API dokumen dapat dipakai di semua paket, termasuk paket Gratis. Dokumen yang dibuat lewat API adalah dokumen otomatis: dokumen ini diambil dari kuota dokumen otomatis seat Business terlebih dahulu, lalu dari kuota bulanan gratis, lalu dari paket dokumen Anda; jika ketiganya habis, API menjawab QUOTA_EXCEEDED. Di paket Gratis, dokumen memuat baris footer “Generated with AutomaDoc” kecuali perusahaan Anda memiliki paket dokumen yang dibeli, dan Callback Webhook template hanya dikirim dengan Pro (atau trial) atau seat Business. HTTP Trigger berbeda: trigger ini membuat dokumen dari satu record data Anda (record Lark Base, baris Excel atau Google Sheets, item SharePoint, atau baris Dataverse), dan memerlukan Pro, trial, atau seat Business.

Autentikasi

Kirim kunci API di header X-Webhook-API-Key. Ada dua jenis kunci yang bisa dipakai:

• Kunci milik template itu sendiri: di tab Template, di bawah API dokumen (kunci yang sama dengan HTTP Trigger). Kunci ini membuka satu template itu saja.
• Kunci API perusahaan: dibuat oleh admin di Portal Perusahaan (di perusahaan Lark, admin aplikasi Lark), di bawah Perusahaan → Kunci API. Kunci ini membuka semua template perusahaan Anda. Kunci hanya ditampilkan sekali saat dibuat; simpan seperti kata sandi. Template persetujuan tidak punya kunci sendiri, jadi gunakan kunci API perusahaan untuknya.

Mencabut kunci API perusahaan, atau mereset kunci sebuah template, langsung membuat kunci tersebut berhenti berfungsi.

Membuat dokumen

POST https://api.automadoc.cc/api/v1/templates/{templateId}/documents

ID template ada di endpoint yang ditampilkan pada kartu API dokumen milik template.

Field	Wajib	Fungsinya
data	ya	Record-nya: key-nya adalah placeholder. Daftar objek menghasilkan satu dokumen per item, atau, untuk template yang membuat satu dokumen dari banyak record, satu dokumen dari semuanya (lihat Beberapa dokumen sekaligus).
format	tidak	"pdf", "png" (halaman pertama sebagai gambar), atau "native" (file asli template, mis. .docx). Bawaannya mengikuti pengaturan template.
filename	tidak	Pola nama file untuk permintaan ini, dengan placeholder {Field}, menggantikan pola milik template.
recordId	tidak	Yang dicetak {Record_ID}, untuk satu dokumen. Bawaannya ID dokumen.
mode	tidak	"separate", "list", "continuous" atau "labels": apa yang dibuat template, dikirim sebagai pemeriksaan. Jika tidak dikirim, template yang menentukan (lihat Beberapa dokumen sekaligus).

Tambahkan ?wait=20 (hingga 25 detik) agar respons ditahan sampai dokumen siap, sehingga satu permintaan sudah cukup. Tanpa itu, respons langsung dikirim dan Anda melakukan polling ke URL status.

Alat alur kerja yang mengikuti konvensi polling 202 + Location (Power Automate, Logic Apps, dan sejenisnya) dapat menambahkan ?async=true sebagai gantinya: selama dokumen dibuat, respons 202 membawa header Location untuk di-polling dan header Retry-After (5 detik). Lokasi itu menjawab 202 sampai dokumen selesai (200) atau gagal (422, dengan "code": "DOCUMENT_FAILED" dan alasannya di error). Dokumen yang sudah gagal saat permintaan dijawab langsung mendapat 422 itu. Endpoint status juga menerima ?async=true. async mengikuti satu dokumen, jadi tidak dapat dipakai dengan daftar di data untuk template yang membuat satu dokumen per item (INVALID_ASYNC). Konektor Power Automate menggunakannya.

Respons: 202 Accepted selama dokumen sedang dibuat, 200 OK jika wait melihatnya selesai:

{
  "generationId": "5d2f0c1e-6a1b-4c7e-9f0a-2b8c3d4e5f60",
  "templateId": "9b1c…",
  "status": "processing",
  "statusUrl": "https://api.automadoc.cc/api/v1/documents/5d2f0c1e-6a1b-4c7e-9f0a-2b8c3d4e5f60",
  "createdAt": 1791878400000
}

Mengambil dokumen

GET https://api.automadoc.cc/api/v1/documents/{generationId}

Gunakan kunci yang sama seperti pada permintaan. status bernilai processing, completed, atau failed:

{
  "generationId": "5d2f0c1e-6a1b-4c7e-9f0a-2b8c3d4e5f60",
  "status": "completed",
  "filename": "Invoice-INV-2026-001.pdf",
  "downloadUrl": "https://api.automadoc.cc/api/generations/…/download?expires=…&signature=…",
  "downloadUrlExpiresAt": 1792137600000
}

downloadUrl tidak memerlukan kunci. Tautan ini tetap berlaku selama perusahaan Anda menyimpan dokumen yang dibuat (ditentukan oleh paket Anda), atau 30 hari jika dokumen disimpan tanpa batas waktu, dan berhenti berfungsi saat dokumen dihapus. Setiap kali status dibaca, tautan baru diberikan. Dokumen berstatus failed memiliki error berisi penyebabnya. Dokumen yang selesai dapat memiliki warnings: apa yang tidak dimasukkan ke dalamnya, misalnya gambar yang URL-nya tidak dapat diambil, disebut dengan nama field-nya dan host URL-nya. Placeholder yang tidak memiliki nilai di data Anda dicantumkan bersama dalam satu baris (“3 fields had no value in the data: …”), setelah peringatan lainnya.

Endpoint ini juga melaporkan dokumen yang dimulai oleh HTTP Trigger: responsnya mencantumkan generationIds dokumen-dokumen tersebut.

Sebuah kunci hanya melihat dokumen dari template yang dibukanya. Dokumen yang dibuat secara manual di ekstensi tidak terlihat lewat API.

Mengunduh file dengan kunci

GET https://api.automadoc.cc/api/v1/documents/{generationId}/file

File jadinya itu sendiri, dengan kunci yang sama, untuk alat yang menerima file, bukan tautan. Endpoint ini menjawab 409 dengan DOCUMENT_NOT_READY selama dokumen masih dibuat, 422 dengan DOCUMENT_FAILED dan alasannya di error jika dokumen gagal, dan 404 dengan DOCUMENT_FILE_MISSING setelah retensi perusahaan Anda menghapus file tersebut. Content-Type dan Content-Disposition (nama file) menjelaskan file tersebut.

Daftar template dan datanya

GET https://api.automadoc.cc/api/v1/templates
GET https://api.automadoc.cc/api/v1/templates/{templateId}

Yang pertama mencantumkan semua template perusahaan Anda: id, name, source (base atau approval), templateFormat, mode (apa yang dibuat oleh sebuah permintaan, seperti di Beberapa dokumen sekaligus), outputFormat, dan ready (false selama template belum memiliki file, atau memiliki error yang harus diperbaiki). Endpoint ini memerlukan kunci API perusahaan; kunci milik template itu sendiri ditolak dengan COMPANY_KEY_REQUIRED.

Yang kedua menjelaskan satu template (kedua jenis kunci bisa dipakai) dan menambahkan dataSchema, skema JSON dari data yang diterimanya (satu properti per placeholder: teks, angka, atau URL gambar, ya/tidak untuk kondisi, daftar untuk loop), sampleData, dan documentsUrl. Alat alur kerja memakainya untuk menampilkan satu input per placeholder.

Deskripsi lengkap rute-rute ini tersedia sebagai dokumen OpenAPI di https://api.automadoc.cc/api/v1/openapi.json.

Cara data Anda mengisi template

Nama. Setiap key diubah menjadi nama placeholder persis seperti nama field Base: spasi, titik, dan simbol lain menjadi _, huruf dan angka dari bahasa apa pun dipertahankan, dan huruf besar-kecil dibedakan.

Key yang Anda kirim	Placeholder yang diisinya
"Customer"	{Customer}
"Invoice No."	{Invoice_No_}
"Unit price"	{Unit_price}
"客户名称"	{客户名称}

Dua key dalam objek yang sama yang menghasilkan nama yang sama, seperti "Unit price" dan "Unit-price", ditolak dengan DATA_NAME_COLLISION, alih-alih salah satunya menang tanpa pemberitahuan.

Nilai.

• Teks dan angka dicetak apa adanya. Angka tetap angka, sehingga filter seperti number, currency, dan sum bisa dipakai.
• true / false bekerja dengan kondisi: {#if Paid}…{/if}.
• null dan daftar kosong tidak mencetak apa pun, dan dianggap kosong dalam {#if}.
• Objek mengisi placeholder bertitik: {"Customer": {"Name": "Acme"}} mengisi {Customer.Name}.
• Daftar objek adalah loop: {"Items": [{"Product": "Pen", "Qty": 2}]} mengisi {#Items}{Product} × {Qty}{/Items}.
• Daftar nilai biasa dicetak dengan pemisah koma: ["red", "blue"] mencetak red, blue.
• Gambar: di tempat template memiliki placeholder gambar (gambar yang Alt Text-nya {Logo}, juga di dalam baris loop), kirim URL https://, atau daftar URL untuk {Photos[1]}, {Photos[2]}. URL harus dapat dijangkau dari internet. Di tempat lain, URL hanyalah teks.
• Lampiran: {ATTACH:Field} hanya menambahkan file dari field lampiran Base atau formulir persetujuan. API dokumen tidak dapat mengirim file untuknya: tidak ada yang ditambahkan, dan URL yang dikirim untuknya dicetak sebagai teks.
• {QR:Field} dan {BARCODE:Field} mencetak kode dari teks yang Anda kirim.

Record_ID, Template_Name, dan Print_Time diisi oleh AutomaDoc; key dengan nama tersebut akan digantikan (respons memberi peringatan).

Untuk template persetujuan, variabel yang tercantum di halamannya adalah nama yang perlu dikirim. Nama file bawaannya memakai permintaan persetujuan, yang tidak ada dalam JSON, sehingga dokumen yang dibuat lewat API diberi nama {Template_Name}-{Record_ID} kecuali Anda mengirim filename.

Beberapa dokumen sekaligus

Kirim data sebagai daftar berisi hingga 50 objek untuk membuat satu dokumen per item. Respons mencantumkan semuanya:

{ "documents": [ { "generationId": "…", "status": "processing", "statusUrl": "…" }, … ] }

Jika ada satu item yang ditolak, tidak ada dokumen yang dibuat. recordId tidak bisa dipakai bersama daftar.

Satu dokumen dari semua item

Jika template diatur untuk membuat satu dokumen dari banyak record (daftar, satu halaman per record, atau label), daftar di data menghasilkan satu dokumen: setiap item menjadi satu record dalam loop {#Records}, satu halaman, atau satu label, sesuai urutan yang dikirim. Hingga 500 item; satu objek menghasilkan dokumen berisi satu item. Responsnya adalah dokumen tersebut, dengan recordCount:

{ "generationId": "…", "status": "processing", "statusUrl": "…", "recordCount": 120 }

• {Record_ID} mencetak posisi setiap item, dari 1 hingga jumlah item.
• Pola nama file membaca item pertama, ditambah {RecordCount} dan {Date}. Tanpa pola, dokumen dinamai {Template_Name}-{Date}.
• "format": "png" menghasilkan PDF: gambar hanya akan memuat halaman pertama.
• Dihitung sebagai satu dokumen. Terhadap batas 600 dokumen per menit per perusahaan, dihitung satu per item untuk satu halaman per record, dan satu per sepuluh item untuk daftar atau label.
• Tidak bisa dikirim untuk ditandatangani (ESIGN_COMBINED).

Pengaturan Record per dokumen pada template yang menentukan. Jika Anda mengirim mode ("separate" untuk satu dokumen per item, atau "list", "continuous" untuk satu halaman per record, atau "labels") dan template diatur lain, permintaan ditolak dengan MODE_MISMATCH, alih-alih mengembalikan jumlah file yang berbeda dari yang diharapkan skrip Anda.

Contoh: curl

curl -X POST 'https://api.automadoc.cc/api/v1/templates/TEMPLATE_ID/documents?wait=20' \
  -H 'X-Webhook-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "Invoice No.": "INV-2026-001",
      "Customer": { "Name": "Acme Corp", "Address": "1 Main St" },
      "Items": [
        { "Product": "Consulting", "Qty": 10, "Price": 120 },
        { "Product": "Travel", "Qty": 1, "Price": 340 }
      ],
      "Logo": "https://example.com/logo.png"
    },
    "format": "pdf"
  }'

Kartu API dokumen pada template menyalin permintaan seperti ini, yang disusun dari placeholder template itu sendiri.

Contoh: Node.js

const API = 'https://api.automadoc.cc'
const headers = { 'X-Webhook-API-Key': process.env.AUTOMADOC_KEY, 'Content-Type': 'application/json' }

async function generate(templateId, data) {
  const res = await fetch(`${API}/api/v1/templates/${templateId}/documents?wait=20`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ data, format: 'pdf' }),
  })
  let doc = await res.json()
  if (!res.ok) throw new Error(`${doc.code}: ${doc.error}`)

  // Still processing after the wait: poll the status URL.
  while (doc.status === 'processing') {
    await new Promise((r) => setTimeout(r, 2000))
    doc = await (await fetch(doc.statusUrl, { headers })).json()
  }
  if (doc.status === 'failed') throw new Error(doc.error)
  return doc.downloadUrl
}

Kirim dokumen untuk ditandatangani

Tambahkan blok sign untuk mengirim dokumen agar ditandatangani begitu dokumen selesai dibuat. Tidak ada biaya tambahan selain dokumennya.

sign berlaku untuk template Lark Base: template Word dengan kolom tanda tangan (lihat Tanda tangan elektronik) yang membuat satu dokumen per record, dengan data dikirim sebagai satu objek. Template lain menolaknya dengan SIGN_BASE_TEMPLATES_ONLY: template Excel, daftar SharePoint, Dataverse, Google Sheets, dan khusus API, serta template Lark Approval, yang ditandatangani di dalam persetujuan itu sendiri. Hanya akun Lark yang memiliki template Lark Base, jadi di akun Microsoft, Google, atau email tidak ada template yang menerima sign.

{
  "data": { "Customer": "Acme Corp" },
  "sign": {
    "signers": {
      "Customer": { "name": "Budi Santoso", "contact": "budi@acme.example" },
      "Supplier": { "larkUserId": "ou_1234…" }
    },
    "order": "sequential"
  }
}

Field	Fungsinya
signers	Satu penanda tangan untuk setiap peran tanda tangan di template, berdasarkan nama peran. Setiap peran wajib memilikinya: tidak ada record untuk membaca penanda tangan. Orang di luar perusahaan Anda ditulis { "name", "contact"? }: sebuah nama, dan bila perlu catatan kontak yang disimpan bersama permintaan, misalnya alamat email (tidak ada yang dikirim ke alamat itu). Rekan kerja ditulis { "larkUserId" }: open_id Lark miliknya, untuk orang di perusahaan Lark Anda yang memakai AutomaDoc.
order	"parallel" (semua sekaligus) atau "sequential" (sesuai urutan di template). Bawaannya mengikuti pengaturan template.
generatePasswords	Kata sandi buatan untuk setiap penanda tangan luar. Bawaan true.
locale	Bahasa pesan bot dan halaman audit, misalnya "en".

Permintaan tanda tangan dimulai saat dokumen siap. Rekan kerja menerima pesan dari bot AutomaDoc di Lark. Tautan penanda tangan luar, beserta kata sandi buatannya, dikembalikan sekali saja, oleh GET /api/v1/documents/{generationId} pertama setelah permintaan dimulai:

{
  "status": "completed",
  "signing": {
    "status": "started",
    "requestId": "…",
    "links": [{ "role": "Customer", "displayName": "Budi Santoso", "url": "https://…/sign/…", "password": "K7mQ…" }]
  }
}

Teruskan sendiri kepada mereka, dan kirim kata sandi secara terpisah jika bisa. Pembacaan berikutnya menampilkan entri yang sama dengan url dan password bernilai null serta "linksRedacted": true. Jika tautan hilang, buat tautan baru dari halaman Tanda tangan. signing.status bernilai queued sampai dokumen selesai, sebentar starting saat permintaan dibuka, lalu started atau failed (dengan kode error).

sign ditolak jika data berupa daftar (SIGN_SINGLE_DOCUMENT) dan pada template yang membuat satu dokumen dari banyak record (ESIGN_COMBINED).

Saat dokumen siap

Jika template memiliki Callback Webhook, callback itu juga dipanggil untuk dokumen API, beserta tautan unduhannya, dengan Pro (atau trial) atau seat Business, seperti untuk setiap dokumen otomatis.

Error

Setiap penolakan memiliki code dan error dalam bahasa Inggris:

Status	code	Penyebab
400	INVALID_JSON, DATA_REQUIRED, DATA_NOT_OBJECT	Body bukan JSON, tidak memiliki data, atau data bukan objek maupun daftar objek
400	DATA_NAME_COLLISION, DATA_INVALID_NAME	Dua key mengisi placeholder yang sama; sebuah key tidak memiliki huruf atau angka
400	DATA_MIXED_ARRAY	Sebuah daftar mencampur objek dan nilai biasa
400	DATA_TOO_DEEP, DATA_ARRAY_TOO_LONG, DATA_TOO_MANY_KEYS, DATA_STRING_TOO_LONG	Melebihi batas
400	IMAGE_URL_NOT_ALLOWED, TOO_MANY_IMAGES	URL gambar bukan alamat http(s) publik; terlalu banyak gambar
400	BATCH_EMPTY, BATCH_TOO_LARGE	Daftar kosong; lebih dari 50 item (500 untuk template yang membuat satu dokumen dari banyak record)
400	INVALID_FORMAT, INVALID_FILENAME, INVALID_RECORD_ID, INVALID_WAIT, INVALID_MODE, INVALID_ASYNC	Sebuah opsi tidak valid
400	TEMPLATE_VALIDATION_ERRORS	File template memiliki error yang harus diperbaiki terlebih dahulu (tercantum di validationErrors)
400	MODE_MISMATCH	mode bukan yang dibuat template
401	API_KEY_MISSING	Tidak ada header X-Webhook-API-Key
403	API_KEY_INVALID	Kunci salah, sudah dicabut, atau tidak membuka template ini; ini juga jawaban untuk ID template yang tidak ada
403	QUOTA_EXCEEDED	Tidak ada sisa dokumen bulan ini; beli paket dokumen atau seat
403	TEMPLATE_DISABLED	Template melebihi batas template paket Anda
403	COMPANY_KEY_REQUIRED	Mencantumkan template memerlukan kunci API perusahaan, bukan kunci milik template
404	TEMPLATE_NOT_FOUND, DOCUMENT_NOT_FOUND	Template atau dokumen tersebut tidak ada untuk kunci ini
404	DOCUMENT_FILE_MISSING	File dokumen sudah dihapus oleh retensi perusahaan Anda
409	TEMPLATE_FILE_MISSING, TEMPLATE_NO_OWNER	Template belum memiliki file; template tidak memiliki pemilik (buka dan simpan sekali, atau gunakan kunci API perusahaan)
409	DOCUMENT_NOT_READY	Mengunduh file dokumen yang masih dibuat
413	BODY_TOO_LARGE	Body lebih dari 1 MB
422	DOCUMENT_FAILED	Mengunduh file dokumen yang gagal, atau mengirim permintaan atau membaca status dengan async=true untuk dokumen tersebut; error menjelaskan alasannya
429	RATE_LIMITED	Lebih dari 60 permintaan per menit untuk satu template, 600 dokumen per menit untuk satu perusahaan, 60 pembacaan status atau 60 unduhan per menit untuk satu dokumen, atau 60 daftar template per menit untuk satu perusahaan. Dokumen dari HTTP Trigger dihitung dalam 600 milik perusahaan; permintaannya punya batas sendiri, 300 per menit per template
400	SIGN_INVALID, SIGN_SINGLE_DOCUMENT, SIGN_BASE_TEMPLATES_ONLY	Blok sign tidak valid, data berupa daftar, atau template bukan template Lark Base, sehingga dokumennya tidak dapat dikirim untuk ditandatangani
400, 409	ESIGN_…	Ditolak oleh tanda tangan elektronik: ESIGN_ROLES_MISMATCH (ada peran tanpa penanda tangan, atau peran yang tidak dikenal), ESIGN_SIGNER_FIELD (penanda tangan dibaca dari field), ESIGN_INVALID_SIGNER (larkUserId yang bukan pengguna di perusahaan Anda), ESIGN_NO_MASTER (template tidak memiliki kolom tanda tangan), ESIGN_COMBINED (template membuat satu dokumen dari banyak record), ESIGN_RECORD_UNREADABLE (template tidak memiliki pemilik yang menjadi pengirim permintaan)
502	WORKER_UNAVAILABLE	Layanan dokumen tidak dapat dijangkau; coba lagi sebentar lagi
503	TEMPLATE_FORMAT_UNAVAILABLE	Template berupa file Excel atau PowerPoint yang belum bisa dibuka oleh layanan dokumen; coba lagi nanti
503	COMBINED_UNAVAILABLE	Satu dokumen dari banyak record belum bisa dibuat saat ini; coba lagi nanti
503	ATTACHMENTS_UNAVAILABLE	Template membuat satu dokumen dari banyak record dan menambahkan lampiran ke PDF, yang belum bisa dilakukan saat ini; coba lagi nanti

Batas

Body permintaan	1 MB
Dokumen per permintaan	50, atau 500 item dalam satu dokumen dari banyak record
Kedalaman objek dan daftar bertingkat	8 tingkat
Item dalam satu daftar	1.000
Key dalam satu objek	500
Karakter dalam satu nilai	100.000
Gambar per dokumen	50; 500 dari semua item dalam satu dokumen dari banyak record
wait	25 detik
Permintaan per template	60 per menit; HTTP Trigger punya batas sendiri, 300 per menit
Pembacaan status per dokumen	60 per menit; unduhan file punya batas sendiri, 60
Daftar template	60 per menit per perusahaan; deskripsi satu template 60 per menit
Dokumen per perusahaan	600 per menit, API dokumen dan HTTP Trigger digabung