Mulai cepat API

Halaman ini membawa Anda dari akun kosong sampai dokumen jadi yang dibuat oleh kode Anda sendiri: sebuah akun, sebuah template, sebuah kunci, dan satu permintaan HTTP. Setiap field, jawaban, dan error dijelaskan di referensi API dokumen.

1. Sebuah akun

Akun AutomaDoc apa pun dapat memanggil API: organisasi Microsoft 365, domain Google Workspace, workspace Lark, atau akun email. Jika Anda hanya memerlukan API, daftar dengan alamat email: lihat Akun khusus API.

Langkah 2 dan 3 dilakukan di Portal Perusahaan di company.automadoc.cc dan memerlukan admin akun Anda (di workspace Lark, admin aplikasi Lark).

2. Template dan ID-nya

Template adalah file Word, Excel, atau PowerPoint dengan placeholder di tempat data Anda akan dimasukkan. Untuk halaman ini, ambil invoice Word yang berisi:

{Invoice_No} dan {Customer} di dalam teks,
baris tabel yang sel pertamanya diawali {#Items}{Product}, lalu {Qty}, dan sel terakhirnya diakhiri {Price}{/Items}: baris ini diulang sekali per item,
{Total | currency:"USD"} di bawah tabel.

Sintaks lengkapnya ada di Sintaks template.

Untuk menambahkannya di Portal Perusahaan:

Buka Template lalu klik Template API baru.
Ketik nama lalu klik Buat template API.
Buka menu di ujung baris template lalu pilih Unggah file. File diperiksa saat diunggah; jika ada masalah, halaman akan memberi tahu dan Anda mengunggah file yang sudah diperbaiki.
Di menu yang sama, pilih Salin ID template.

API dapat mengisi template apa pun milik perusahaan Anda, bukan hanya template API: template yang dibuat di add-in Excel, dari Google Sheet, atau di ekstensi Lark Base bekerja dengan cara yang sama, dan barisnya di Template memiliki Salin ID template yang sama. Jika Anda masuk ke portal dengan Lark, buat template di ekstensi Base; kartu API dokumen-nya, di tab Template, juga menampilkan endpoint lengkap dengan ID-nya.

3. Kunci API perusahaan

Di Portal Perusahaan, buka Perusahaan → Kunci API lalu klik Kunci API baru.
Isi Nama kunci dengan sistem yang akan memakainya, misalnya ERP, lalu klik Buat kunci.
Salin kuncinya. Kunci diawali amk_ dan hanya ditampilkan sekali.

Kunci perusahaan membuka setiap template perusahaan Anda. Simpan seperti kata sandi. Cabut di halaman yang sama langsung menghentikannya.

Template Lark Base juga memiliki kunci sendiri, di kartu API dokumen-nya, yang hanya membuka template tersebut.

4. Kirim permintaan pertama Anda

Kirim data template sebagai JSON ke POST /api/v1/templates/{templateId}/documents, dengan kunci di header X-Webhook-API-Key:

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": "Acme Corp",
      "Items": [
        { "Product": "Consulting", "Qty": 10, "Price": 120 },
        { "Product": "Travel", "Qty": 1, "Price": 340 }
      ],
      "Total": 1540
    },
    "format": "pdf"
  }'

data adalah record-nya. Setiap kunci mengisi placeholder dengan nama yang sama. Spasi, titik, dan simbol lain dalam kunci menjadi _, jadi "Invoice No." mengisi {Invoice_No_}; huruf besar/kecil dibedakan.
format bersifat opsional: "pdf", "png" (halaman pertama sebagai gambar), atau "native" (jenis file milik template itu sendiri). Jika tidak diisi, pengaturan template yang menentukan.
?wait=20 menahan jawaban hingga 20 detik (paling lama 25) selagi dokumen dibuat, sehingga satu permintaan sering kali sudah cukup.

filename, recordId, dan mode juga opsional; lihat Membuat dokumen.

5. Baca jawabannya dan dapatkan file-nya

Jika dokumen selesai dalam waktu tunggu, jawabannya 200 OK:

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

Jika dokumen masih dibuat, jawabannya 202 Accepted dengan "status": "processing" dan belum ada tautan. Baca statusUrl dengan kunci yang sama setiap beberapa detik (paling banyak 60 pembacaan per menit per dokumen) sampai status bernilai completed atau failed:

curl 'https://api.automadoc.cc/api/v1/documents/GENERATION_ID' \
  -H 'X-Webhook-API-Key: YOUR_API_KEY'

completed: downloadUrl membuka file tanpa kunci. Tautan ini berlaku selama perusahaan Anda menyimpan dokumen yang dibuat, dan setiap pembacaan status memberikan tautan baru.
failed: error menjelaskan alasannya, misalnya loop yang tidak pernah ditutup.
warnings, jika ada, mencantumkan apa yang tidak diikutkan, seperti gambar yang URL-nya tidak dapat diambil, atau placeholder yang tidak memiliki nilai di data Anda.

Untuk mendapatkan file itu sendiri dengan kunci, bukan lewat tautan:

curl -o invoice.pdf 'https://api.automadoc.cc/api/v1/documents/GENERATION_ID/file' \
  -H 'X-Webhook-API-Key: YOUR_API_KEY'

Jika permintaan ditolak

Setiap penolakan memiliki code dan error dalam bahasa Inggris. Yang pertama kali akan Anda temui:

Status	`code`	Yang perlu dilakukan
401	`API_KEY_MISSING`	Tambahkan header `X-Webhook-API-Key`
403	`API_KEY_INVALID`	Periksa kunci dan ID template: ID yang salah juga mendapat jawaban ini
409	`TEMPLATE_FILE_MISSING`	Unggah file template
400	`TEMPLATE_VALIDATION_ERRORS`	Perbaiki file template; `validationErrors` mencantumkan masalahnya
403	`QUOTA_EXCEEDED`	Tidak ada dokumen tersisa bulan ini; beli paket dokumen atau seat
429	`RATE_LIMITED`	Lebih dari 60 permintaan per menit untuk satu template, atau 600 dokumen per menit untuk perusahaan Anda; tunggu lalu coba lagi

Daftar lengkapnya ada di Error.

Hal yang sama di Node.js

Node.js 18 atau yang lebih baru sudah memiliki fetch bawaan. Simpan ini sebagai quickstart.mjs dan jalankan dengan AUTOMADOC_KEY=amk_… node quickstart.mjs:

import { writeFile } from 'node:fs/promises'

const API = 'https://api.automadoc.cc'
const KEY = process.env.AUTOMADOC_KEY
const TEMPLATE_ID = 'TEMPLATE_ID'

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

  // Not finished within the wait: read the status until it is.
  while (doc.status === 'processing') {
    await new Promise((resolve) => setTimeout(resolve, 3000))
    const poll = await fetch(doc.statusUrl, { headers: { 'X-Webhook-API-Key': KEY } })
    doc = await poll.json()
    if (!poll.ok) throw new Error(`${doc.code}: ${doc.error}`)
  }
  if (doc.status === 'failed') throw new Error(doc.error)
  return doc
}

const doc = await makeDocument(TEMPLATE_ID, {
  Invoice_No: 'INV-2026-001',
  Customer: 'Acme Corp',
  Items: [
    { Product: 'Consulting', Qty: 10, Price: 120 },
    { Product: 'Travel', Qty: 1, Price: 340 },
  ],
  Total: 1540,
})

const file = await fetch(doc.downloadUrl)
await writeFile(doc.filename, Buffer.from(await file.arrayBuffer()))
console.log(`Saved ${doc.filename}`, doc.warnings ?? '')

Langkah selanjutnya

Loop. Daftar objek mengisi loop {#Items}…{/Items}, satu baris atau blok per objek; loop dapat memfilter, mengurutkan, dan membatasi barisnya. Lihat Loop.
Gambar. Beri gambar di template Alt Text {Logo} lalu kirim "Logo": "https://…". URL-nya harus berupa alamat http(s) publik; di tempat lain di template, URL hanyalah teks. Lihat Gambar dinamis dan Cara data Anda mengisi template.
PDF, gambar, atau file Office. "format" memilih output per permintaan; pengaturan template berlaku jika Anda tidak mengisinya.
Banyak dokumen dalam satu permintaan. Kirim data sebagai daftar berisi hingga 50 objek untuk mendapatkan satu dokumen per item. Lihat Beberapa dokumen sekaligus.
Satu dokumen dari banyak record. Template yang diatur untuk membuat daftar, satu halaman per record, atau label mengubah daftar berisi hingga 500 item menjadi satu dokumen, yang dihitung sebagai satu. Lihat Satu dokumen dari banyak record dan Satu dokumen dari semua item.
Tanda tangan elektronik. Untuk template Lark Base dengan field tanda tangan, blok sign mengirim dokumen untuk ditandatangani begitu dokumen dibuat. Lihat Kirim dokumen untuk ditandatangani.
Tanpa kode sama sekali. Di Microsoft 365, konektor Power Automate membuat permintaan yang sama dari sebuah flow.