Cara Integrasi Tilaka API ke Aplikasi Anda: Step-by-Step

Tim developer biasanya baru mencari Tilaka API setelah ada workflow yang sudah berjalan: kontrak HR harus ditandatangani di portal internal, form persetujuan nasabah keluar dari core system, atau dokumen vendor perlu masuk arsip tanpa proses manual. Masalahnya, tanda tangan digital bukan sekadar tombol “sign”. Di belakangnya ada identitas penanda tangan, sertifikat elektronik, dokumen final, callback status, audit trail, dan bukti yang harus tetap rapi saat diperiksa legal.

Artikel ini membahas integrasi dari sudut pandang technical lead. Bukan daftar endpoint resmi, karena detail itu harus mengikuti sandbox dan dokumentasi Tilaka terbaru. Fokusnya adalah blueprint: komponen apa yang disiapkan, bagaimana alur API dirancang, error apa yang wajib diuji, dan kapan integrasi digital signature siap naik produksi.

TL;DR

• Tilaka API perlu dipetakan sebagai lifecycle: identitas, sertifikat, signing request, webhook, verifikasi status, dokumen final, dan audit evidence.
• Mulai dari prerequisite bisnis dan security sebelum kode: use case, sandbox, credential, callback URL, template dokumen, signer flow, dan e-Meterai bila relevan.
• Jangan menebak endpoint atau payload. Gunakan kategori alur, lalu validasi detail final di sandbox Tilaka bersama Solution Architect.
• Webhook harus dirancang idempotent, bisa retry, dan punya rekonsiliasi agar status dokumen tidak bergantung pada satu callback.
• Go-live yang sehat membutuhkan test case gagal, monitoring, rate limit, quota, retention, rollback, dan SOP support.

Prerequisite Integrasi Digital Signature Sebelum Kode

Sebelum membuat client HTTP pertama, tulis dulu keputusan produk dan compliance. Dokumen apa yang akan ditandatangani? Siapa penanda tangannya? Apakah user sudah dikenal sistem atau perlu verifikasi identitas? Apakah dokumen membutuhkan e-Meterai? Apakah dokumen final disimpan di DMS internal, object storage, atau repository khusus? Jawaban ini menentukan bentuk Tilaka API integration yang dipakai, bukan sebaliknya.

Hal minimum yang perlu siap:

• use case dan jenis dokumen, misalnya kontrak karyawan, perjanjian vendor, form persetujuan, atau akad;
• akses sandbox dan credential API melalui jalur resmi Docotel/Tilaka;
• callback URL yang bisa diakses dari environment sandbox;
• template dokumen, posisi tanda tangan, dan aturan multi-signer;
• mapping identitas signer dari sistem internal ke proses Tilaka;
• kebutuhan e-Meterai untuk dokumen tertentu;
• owner security untuk review secret, logging, dan data handling.

Halaman Tilaka Developers memosisikan platform ini sebagai API-first untuk identity, certificate, signature, dan verification. Halaman yang sama juga merangkum empat tahap go-live: generate API key, verify identity, issue certificate, dan monitor serta audit. Itu cukup untuk memulai desain arsitektur, tetapi detail endpoint tetap harus mengikuti developer portal dan sandbox yang berlaku.

💡 Insight: Integrasi tanda tangan digital sering gagal bukan karena API sulit, melainkan karena tim belum sepakat siapa pemilik status dokumen, retry callback, dan arsip bukti.

Bila tim Anda masih memilih jalur Portal, API, atau deployment yang lebih terkontrol, gunakan pilar solusi Tilaka Docotel sebagai konteks sebelum masuk ke desain teknis.

Tilaka Integration: Desain Alur API dan Evidence

Desain yang rapi membagi alur menjadi dua jalur: jalur transaksi dan jalur bukti. Jalur transaksi mengurus pembuatan request, signer journey, dan status dokumen. Jalur bukti mengurus sertifikat, timestamp, audit log, hash, dokumen final, dan data yang dibutuhkan saat audit.

Gunakan arsitektur ringkas berikut sebagai baseline:

Tilaka Sign+ dijelaskan di halaman Tilaka Sign+ sebagai solusi tanda tangan digital berbasis sertifikat elektronik PSrE, tersedia melalui API fleksibel atau portal web. Halaman itu juga menyebut pendekatan hash-based signing. Untuk production design, jadikan klaim ini sebagai topik review bersama security architect: data apa yang dikirim, data apa yang tetap di sistem internal, dan bukti apa yang perlu disimpan.

Untuk trust evidence, cek juga Tilaka Repository karena di sana tersedia rujukan seperti CPS, CRL, OCSP responder, dan agreement dokumen CA. Bagi auditor, artefak seperti ini membantu menjelaskan rantai kepercayaan, bukan hanya status “signed” di aplikasi.

Authentication, Secret, dan Environment Separation

Halaman developer Tilaka menyebut tahap generate API key, jadi credential management harus diperlakukan sebagai bagian dari desain, bukan catatan implementasi. Simpan secret di secret manager, bukan environment file yang ikut repository. Batasi akses credential hanya ke service yang memanggil Tilaka API. Pisahkan credential sandbox dan production. Rotasi secret harus punya owner, jadwal, dan runbook.

Ada tiga keputusan yang perlu dibuat sebelum coding:

1. Environment boundary. Sandbox, staging, dan production tidak boleh berbagi credential, callback URL, atau dokumen uji yang berisi data nyata.
2. Network trust. Tentukan apakah traffic keluar harus lewat NAT khusus, allowlist IP, private connectivity, atau kontrol tambahan sesuai standar enterprise.
3. Audit boundary. Setiap request harus punya correlation ID agar log aplikasi, log webhook, dan log Tilaka bisa disambungkan.

Dalam discovery integrasi yang Docotel dampingi, pertanyaan paling berguna biasanya sederhana: “Jika callback tidak masuk selama 15 menit, siapa yang tahu dan apa tindakannya?” Jawaban atas pertanyaan ini memaksa tim menentukan observability sejak awal. Tanpa itu, Tilaka API bisa berhasil menandatangani dokumen, tetapi aplikasi bisnis tetap menampilkan status menggantung.

Hindari menyebut metode autentikasi detail seperti OAuth2, mTLS, signed request, atau skema header tertentu sebelum dikonfirmasi di sandbox. Tuliskan interface internal Anda dengan pola adapter, sehingga perubahan auth dari vendor tidak menyebar ke modul bisnis.

Alur Core Tilaka API dari Request sampai Audit

Alur berikut sengaja memakai kategori, bukan endpoint path. Ini menjaga draft tetap akurat ketika dokumentasi sandbox berubah atau konfigurasi enterprise berbeda.

1. Prepare document. Aplikasi menyiapkan PDF final, metadata, signer, posisi tanda tangan, dan aturan e-Meterai bila diperlukan.
2. Create signing request. Backend mengirim request ke Tilaka API dan menyimpan correlation ID serta status awal.
3. Signer completes action. User menyelesaikan proses tanda tangan atau verifikasi sesuai flow yang disepakati.
4. Receive webhook. Sistem menerima event async, memvalidasi payload, lalu memperbarui status internal.
5. Verify status. Job rekonsiliasi mengecek status berkala bila webhook terlambat atau gagal.
6. Fetch final evidence. Sistem mengambil dokumen final dan audit evidence, lalu menyimpan sesuai retention policy.

Dasar hukumnya relevan di sini. UU No. 11 Tahun 2008 tentang ITE Pasal 11 menempatkan tanda tangan elektronik sebagai sah jika memenuhi syarat teknis-hukum, termasuk identitas, kontrol data pembuatan tanda tangan, deteksi perubahan, dan persetujuan penanda tangan. PP No. 71 Tahun 2019 Pasal 60 menjelaskan fungsi tanda tangan elektronik sebagai alat autentikasi dan verifikasi, lalu membedakan tanda tangan tersertifikasi dan tidak tersertifikasi. Permenkominfo No. 11 Tahun 2022 Pasal 3 menegaskan bahwa penyelenggaraan sertifikasi elektronik dilaksanakan oleh PSrE dan PSrE Indonesia wajib memperoleh pengakuan Menteri. Pasal 21 mewajibkan PSrE Indonesia yang telah memperoleh pengakuan untuk memeriksa identitas calon pemilik sertifikat serta memvalidasi sertifikat elektronik. Ketentuan ini memberi konteks tata kelola untuk identity flow dan evidence pada desain integrasi.

Sample Code Pseudocode untuk Node.js, PHP, Java

Gunakan contoh ini sebagai bentuk pola, bukan SDK resmi. Nama method dan payload harus diganti mengikuti dokumentasi sandbox Tilaka yang diberikan kepada tim Anda.

// Node.js pseudocode
const request = await tilakaClient.signing.createRequest({
  correlationId,
  documentRef,
  signerRef,
  callbackUrl,
  metadata: { documentType: "vendor-agreement" }
});
saveMapping({ correlationId, vendorRequestId: request.id, status: request.status });

// PHP pseudocode
$request = $tilakaClient->signing()->createRequest([
  'correlation_id' => $correlationId,
  'document_ref' => $documentRef,
  'signer_ref' => $signerRef,
  'callback_url' => $callbackUrl,
]);
$repository->saveSigningMapping($correlationId, $request->id, $request->status);

// Java pseudocode
SigningRequest request = tilakaClient.signing().createRequest(payload);
signingRepository.saveMapping(correlationId, request.getId(), request.getStatus());

Pola yang perlu dijaga di semua bahasa sama: jangan expose secret ke frontend, jangan simpan response mentah tanpa masking, jangan gunakan nomor identitas sebagai correlation ID, dan jangan menganggap request berhasil sebelum status final diverifikasi. Untuk sistem dengan volume tinggi, pisahkan modul create request, webhook receiver, rekonsiliasi, dan evidence downloader agar masing-masing bisa di-scale serta dimonitor.

Webhook dan Error Handling Tidak Boleh Belakangan

Webhook adalah titik yang menentukan apakah integrasi terasa real-time atau rapuh. Anggap setiap event bisa datang terlambat, datang dua kali, atau gagal diproses. Receiver harus idempotent: jika event yang sama masuk lagi, sistem tidak membuat status ganda atau mengunduh dokumen berulang tanpa kontrol.

Rancang status machine sederhana, misalnya created, pending signer, signed, rejected, expired, failed, evidence archived. Status final seperti signed, rejected, dan expired sebaiknya tidak bisa ditimpa event lama. Simpan raw event dengan payload hash, event time, received time, dan hasil validasi.

⚠️ Peringatan: Jangan jadikan webhook sebagai satu-satunya sumber kebenaran. Pair webhook dengan job rekonsiliasi supaya status dokumen tetap bisa pulih saat callback gagal.

Tim solusi Docotel biasanya meminta satu dokumen tambahan sebelum UAT: runbook operasional. Isinya bukan kode, tetapi keputusan: siapa owner incident, kapan retry dihentikan, siapa boleh re-open request, dan bukti apa yang harus dilampirkan saat ticket ditutup.

Sandbox Test dan Go-Live Checklist

Sandbox bukan hanya tempat mencoba happy path. Gunakan sandbox untuk membuktikan bahwa aplikasi Anda bisa gagal dengan rapi. Buat minimal 10 skenario: single signer sukses, multi-signer sukses, signer menolak, request expired, dokumen invalid, callback gagal, duplicate callback, evidence download retry, e-Meterai bila dipakai, dan arsip final.

Halaman FAQ Tilaka menyebut Tilaka dapat mendukung hingga 25 tanda tangan elektronik tersertifikasi dalam satu PDF. Jika workflow Anda multi-signer, validasi batas dan perilaku real di sandbox, terutama posisi tanda tangan, urutan approval, ukuran file, dan pengalaman signer di perangkat mobile.

Checklist sebelum production:

• rate limit, quota, dan SLA sudah dikonfirmasi dengan owner Tilaka/Docotel;
• secret production sudah masuk secret manager dan punya jadwal rotasi;
• webhook punya retry, idempotency, dan dead-letter handling;
• monitoring mencakup request pending, callback failure, evidence download failure, dan status mismatch;
• retention dokumen final dan audit evidence sesuai kebijakan internal;
• e-Meterai sudah diuji untuk dokumen yang memang membutuhkan;
• SOP support mencakup signer tidak menerima link, dokumen expired, dan dispute status;
• rollback jelas: apa yang dilakukan jika service signing tidak tersedia.

Untuk dokumen yang membutuhkan meterai, baca juga panduan e-Meterai untuk perusahaan agar tim tidak mencampur keputusan pajak dokumen dengan keputusan integrasi API.

💡 Tindak lanjut: Jika tim Anda sudah punya aplikasi target, siapkan sequence diagram, contoh dokumen, dan daftar error case. Dari situ sandbox Tilaka API bisa diuji lebih cepat dan lebih terukur.

Akses Developer Sandbox Tilaka API

Integrasi Tilaka API yang baik tidak dimulai dari menyalin endpoint. Ia dimulai dari desain lifecycle: identitas, dokumen, signing request, webhook, evidence, arsip, dan monitoring. Setelah itu baru sandbox membuktikan apakah asumsi teknis Anda benar.

Docotel dapat membantu tim Anda menyusun blueprint, menghubungkan kebutuhan bisnis dengan opsi Tilaka, dan menyiapkan checklist UAT untuk developer, security, legal, dan operation owner. Untuk konteks trust layer, baca juga panduan PSrE Indonesia agar desain API tetap selaras dengan dasar hukum tanda tangan elektronik.

Siapkan tiga hal untuk sesi awal: contoh dokumen, diagram sistem target, dan daftar status yang harus muncul di aplikasi. Dari sana, tim bisa menentukan mana yang perlu dibuat di aplikasi Anda, mana yang ditangani Tilaka, dan bukti apa yang wajib ada sebelum production.

—

Disusun oleh: Tim Solution Architects Docotel
Dipublikasikan: 2026-09-14
Terakhir diperbarui: 2026-09-14