Langsung ke konten utama
POST
Python
Kirim satu dokumen beserta daftar kolom yang ingin dibaca darinya. Didit menjalankan model ekstraksi default pada file tersebut, mengembalikan setiap kolom dengan tipenya (text, number, atau date dalam format YYYY-MM-DD), mendeteksi dan mendekode kode QR dan barcode yang didukung, memeriksa file dari kemungkinan manipulasi, dan secara opsional membandingkan nama pada dokumen dengan orang atau perusahaan yang Anda harapkan. Gunakan untuk bukti dana, slip gaji, rekening koran, dokumen pajak, faktur, atau dokumen apa pun yang tidak mengikuti templat tetap. Ini adalah versi server-ke-server dari langkah Document AI yang di-hosting. Permintaannya berformat multipart/form-data: file dikirim di document, dan definisi kolom dikirim di fields sebagai satu string yang berisi array JSON.

Tentukan kolom yang akan diekstrak

fields adalah array JSON berisi 1 hingga 30 item, dikirim sebagai satu string. Setiap item memiliki key (huruf kecil, angka, dan garis bawah, unik dalam satu permintaan), name yang mudah dibaca, instruction yang memberi tahu model apa yang harus dicari, type (text, number, atau date), serta dua flag: required dan is_full_name.
Dalam permintaan multipart, seluruh array dikirim sebagai satu nilai formulir:
Respons mengembalikan fields yang sudah dinormalisasi dan extracted_data dengan kunci berupa nilai key Anda, dengan null untuk setiap nilai yang tidak dapat ditemukan oleh model. name, instruction, dan type bersifat opsional pada setiap item (type default-nya text); key wajib diisi. Jika fields dikirim sebagai kunci formulir gaya bracket (fields[0][key]=...) atau dalam format selain array JSON, respons 400 dikembalikan sebelum ekstraksi berjalan, sehingga tidak ada biaya yang ditagihkan.

Kode QR dan barcode

Setiap respons yang berhasil menyertakan document_ai.detected_codes. Setiap item berisi: Array ini mencakup setiap halaman yang diproses dari sebuah PDF dan kosong jika tidak ditemukan kode yang didukung. Didit tidak pernah menebak payload: kode QR yang rusak dapat dikembalikan dengan lokasinya dan parsed_payload: null, sementara kegagalan dalam deteksi kode tidak menggagalkan permintaan Document AI.

Pencocokan nama

Tandai paling banyak satu kolom dengan is_full_name: true dan kirim nama orang atau perusahaan yang Anda harapkan memiliki dokumen tersebut: Kirim salah satu kelompok saja, jangan keduanya. Ketika sebuah nama berhasil diekstrak dan nama yang diharapkan tersedia, respons menyertakan name_match_score (0 hingga 100) dan name_on_document. Skor di bawah document_ai_name_match_score_threshold (default 80) memicu peringatan DOCUMENT_AI_NAME_MISMATCH dan menerapkan document_ai_name_mismatch_action. Jika tidak ada kolom yang ditandai is_full_name, Didit akan menggunakan kolom teks pertama yang kuncinya menyerupai nama (name, holder, full_name, account_holder); tandai kolom secara eksplisit jika Anda ingin mengontrol nilai mana yang dibandingkan. Jika tidak ada nilai nama yang dapat ditemukan pada dokumen, atau tidak ada nama yang diharapkan dikirim, pemeriksaan nama dilewati dan name_match_score bernilai null.

Risiko dan tindakan

Setiap risiko di bawah ini dipetakan ke parameter tindakan yang dapat Anda atur per permintaan: DECLINE, REVIEW, atau NO_ACTION. Tindakan yang paling ketat dari yang terpicu menentukan document_ai.status (Declined > In Review > Approved), dan setiap risiko yang terpicu dicantumkan di document_ai.warnings. Default-nya sama dengan langkah alur kerja yang di-hosting; lihat Aturan & peringatan Document AI untuk mengetahui cara setiap risiko dideteksi.

File, penyimpanan, dan penagihan

  • File yang diterima: PDF (multi-halaman didukung), JPG, JPEG, PNG, TIFF, WebP, atau ZIP yang berisi dokumen, hingga 30 MB. PDF yang dienkripsi akan menghasilkan respons 400; unggah PDF yang sudah didekripsi atau foto sebagai gantinya.
  • save_api_request (default true): permintaan, kolom hasil ekstraksi, dan kode yang terdeteksi akan muncul di Business Console pada Pemeriksaan Manual, tempat tim Anda dapat meninjaunya. Atur ke false untuk melewati penyimpanan.
  • vendor_data dan metadata dikembalikan tanpa perubahan dalam respons agar Anda dapat menautkan hasil dengan catatan Anda sendiri.
  • Harga: $0.20 per dokumen, ditagihkan saat dokumen diproses dan status dikembalikan. Diskon paket Anda berlaku. Lihat Harga.
Perlu agar pengguna mengunggah dokumen sendiri, mengumpulkan hingga 3 dokumen dalam satu alur, menerjemahkan layar unggah secara otomatis, atau memverifikasi silang kolom hasil ekstraksi dengan data ID atau kuesioner? Gunakan langkah alur kerja Document AI yang di-hosting sebagai gantinya.

Otorisasi

x-api-key
string
header
wajib

Kunci API aplikasi Anda, dari Developers -> API keys di Business Console. Kunci utama memiliki akses penuh. Kunci bernama dapat diberi cakupan: none, read, atau write per sumber daya, dibatasi pada beberapa alur kerja atau pada sesi yang disetujui, pada daftar alamat IP, dan pada tanggal kedaluwarsa. 401 berarti kuncinya salah, dicabut, atau kedaluwarsa; 403 berarti tidak ada kunci yang dikirimkan, kunci tidak memiliki akses ke sumber daya atau tindakan ini, atau permintaan datang dari alamat di luar daftar IP-nya; 404 pada rute sesi berarti sesi berada di luar alur kerja atau status kunci tersebut. Kunci tanpa akses media menerima URL gambar, video, dan PDF sebagai null, dan kunci tanpa izin tulis sesi menerima tautan sesi dan token sebagai null. Lihat https://docs.didit.me/console/api-keys.

Body

multipart/form-data
document
file
wajib

Dokumen yang akan dibaca. Ekstensi yang diizinkan: tiff, jpg, jpeg, png, pdf, webp, zip. Ukuran unggahan maksimum: 30 MB (berkas yang lebih besar ditolak dengan 400). PDF beberapa halaman didukung (perkirakan latensi lebih tinggi); PDF terenkripsi ditolak dengan 400. Gambar dikompresi secara otomatis sebelum diproses.

fields
string
wajib

Satu string array berformat JSON dengan 1–30 definisi kolom (maksimum 16 KB). Setiap item: key (wajib, ^[a-z0-9_]{1,64}$, unik — kunci yang dikembalikan di extracted_data), name (≤100 karakter, ditampilkan dalam pesan), instruction (≤500 karakter, apa yang harus dibaca model), type (default text | number | date), required (boolean, default false), is_full_name (boolean, default false, paling banyak satu per permintaan). Array form bergaya tanda kurung, JSON tidak valid, kunci duplikat, atau lebih dari satu is_full_name akan mengembalikan 400 sebelum pemrosesan atau penagihan apa pun.

Contoh:

"[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]"

expected_first_name
string

Nama depan untuk diverifikasi terhadap kolom nama dokumen (pencocokan samar, mendukung transliterasi). Gunakan bersama dengan expected_last_name; tidak dapat digabungkan dengan expected_company_name.

Contoh:

"Sophia"

expected_last_name
string

Nama belakang untuk diverifikasi terhadap kolom nama dokumen, digabungkan dengan expected_first_name untuk name_match_score.

Contoh:

"Martinez"

expected_company_name
string

Nama perusahaan yang akan diverifikasi terhadap kolom nama pada dokumen (untuk dokumen bisnis). Tidak dapat digabungkan dengan expected_first_name / expected_last_name (sengaja tanpa nilai contoh — sampel permintaan yang dihasilkan menggunakan kolom untuk orang; ganti kolom tersebut dengan kolom ini saat memverifikasi dokumen bisnis).

expected_company_country
string

Kode negara ISO 3166-1 alpha-2 opsional (dua huruf ASCII, misalnya FR) yang menyesuaikan normalisasi nama perusahaan untuk expected_company_name. Hanya digunakan bersama expected_company_name.

document_ai_name_match_score_threshold
integer
default:80

name_match_score minimum (0–100) untuk menganggap nama cocok. Skor yang lebih rendah menambahkan DOCUMENT_AI_NAME_MISMATCH, yang diatur oleh document_ai_name_mismatch_action.

Rentang yang diperlukan: 0 <= x <= 100
Contoh:

80

document_ai_unreadable_document_action
enum<string>
default:REVIEW

Tindakan yang diambil saat tidak ada kolom yang dapat dibaca dari dokumen (DOCUMENT_AI_UNREADABLE_DOCUMENT).

Opsi yang tersedia:
DECLINE,
REVIEW,
NO_ACTION
document_ai_missing_required_fields_action
enum<string>
default:REVIEW

Tindakan yang diambil saat setidaknya satu kolom required tidak dapat dibaca (DOCUMENT_AI_MISSING_REQUIRED_FIELDS; additional_data.missing_fields mencantumkannya).

Opsi yang tersedia:
DECLINE,
REVIEW,
NO_ACTION
document_ai_document_tampering_action
enum<string>
default:DECLINE

Tindakan yang diambil saat forensik PDF/EXIF mencurigai adanya manipulasi — dimodifikasi setelah penandatanganan digital, editor PDF yang dikenal, manipulasi overlay teks, ekspor ulang yang mencurigakan, anomali gambar (DOCUMENT_AI_SUSPECTED_MANIPULATION).

Opsi yang tersedia:
DECLINE,
REVIEW,
NO_ACTION
document_ai_name_mismatch_action
enum<string>
default:NO_ACTION

Tindakan yang diambil saat name_match_score berada di bawah ambang batas (DOCUMENT_AI_NAME_MISMATCH).

Opsi yang tersedia:
DECLINE,
REVIEW,
NO_ACTION
document_ai_unsupported_file_action
enum<string>
default:REVIEW

Tindakan yang harus diambil ketika unggahan kosong atau bukan file yang dapat diproses (DOCUMENT_AI_UNSUPPORTED_FILE).

Opsi yang tersedia:
DECLINE,
REVIEW,
NO_ACTION
save_api_request
boolean
default:true

Jika true (default), menyimpan panggilan sebagai sesi tipe API — terlihat di Business Console, dapat diambil melalui GET /v3/session/{sessionId}/decision/ menggunakan request_id yang dikembalikan, dengan dokumen yang diunggah, nilai yang diekstrak, definisi kolom, dan snapshot pencocokan nama yang disimpan. Jika false, tidak ada yang disimpan dan request_id adalah UUID sementara hanya untuk korelasi respons; panggilan tetap ditagihkan.

Contoh:

true

vendor_data
string

String buram opsional (ID pengguna internal, email, UUID Anda…) yang disimpan pada sesi yang dipertahankan dan dikembalikan dalam respons. Gunakan untuk mengorelasikan panggilan API dengan catatan Anda sendiri dan memfilter sesi nantinya.

Contoh:

"user-123"

metadata
object

Objek JSON opsional yang disimpan bersama sesi (saat save_api_request=true) dan dikembalikan dalam respons. Dalam permintaan multipart, kirimkan sebagai kolom string yang dikodekan dalam JSON (misalnya metadata={"flow":"onboarding"}) — kolom ini akan diuraikan menjadi sebuah objek.

Contoh:

Respons

Dokumen diproses. document_ai.status bernilai Approved, Declined, atau In Review; setiap masalah yang terdeteksi dirinci dalam document_ai.warnings. Dokumen yang bermasalah tetap menghasilkan 200 — periksa isi respons, bukan hanya kode HTTP. Ketika save_api_request=true, request_id adalah ID sesi yang disimpan.

request_id
string<uuid>

ID sesi yang disimpan saat save_api_request=true (dapat digunakan dengan GET /v3/session/{sessionId}/decision/); jika tidak, berupa UUID korelasi sementara.

document_ai
object
vendor_data
string | null

Salinan vendor_data yang Anda kirimkan, atau null.

metadata
object | null

Salinan objek metadata yang Anda kirimkan, atau null.

created_at
string<date-time>

Waktu permintaan diproses (UTC, ISO 8601).

Terakhir diubah pada 7 November 2026