README

SDK PHP resmi untuk VerifAID. Ekstrak data e-KTP, SIM, NPWP, BPJS, dan Kartu Keluarga dari foto dalam satu baris kode.

$verifaid = new \Verifaid\Client('sv_live_xxx');

$ktp = $verifaid->ocr()->ktp('/path/ke/ktp.jpg');

echo $ktp['nik'];        // 3201010101010001
echo $ktp['full_name'];  // BUDI SANTOSO

Persyaratan

PHP 7.4 atau lebih baru (sudah diuji sampai PHP 8.4)
Ekstensi curl dan json

SDK ini tidak punya dependensi lain, jadi tidak akan bentrok dengan package di proyek Anda.

Instalasi

composer require verifaid/verifaid-php

API key

Jenis key menentukan layanan yang bisa dipakai:

Prefix key	Layanan	Cara mendapatkan	Dipakai lewat
`sv_live_`	OCR self-service, kuota dari top-up	Dibuat sendiri di menu API Key dashboard VerifAID	`$verifaid->ocr()`
`sv_h2h_`	OCR Host-to-Host untuk klien enterprise	Dikirim tim VerifAID ke email Anda setelah invoice aktivasi lunas	`$verifaid->h2h()`

Setiap key hanya bekerja di resource-nya sendiri. Memanggil ocr() dengan key sv_h2h_, atau h2h() dengan key sv_live_, langsung melempar InvalidArgumentException sebelum request dikirim.

Simpan API key di environment variable, jangan di kode:

$verifaid = new \Verifaid\Client(getenv('VERIFAID_API_KEY'));

OCR dokumen

Setiap method mengirim satu gambar dan mengembalikan array berisi data dokumen.

Method	Dokumen	Field utama
`ktp($image)`	e-KTP	`nik`, `full_name`, `birth_place_date`, `address_ktp`, `rt_rw`, `village`, `subdistrict`, `city`, `province`, ...
`sim($image)`	SIM	`license_type`, `license_number`, `full_name`, `valid_until`, ...
`npwp($image)`	NPWP	`npwp_number`, `full_name`, `nik`, `address_npwp`, `kpp_name`
`bpjs($image)`	BPJS Kesehatan / KIS	`card_number`, `full_name`, `nik`, `birth_date`, `faskes_tingkat_1`, ...
`kk($image)`	Kartu Keluarga	`informasi_keluarga` (header KK) dan `anggota_keluarga` (daftar anggota)

Daftar field lengkap ada di docblock setiap method, jadi IDE seperti PhpStorm dan VS Code bisa melengkapi nama field secara otomatis.

Field yang tidak ada atau tidak terbaca pada dokumen dikembalikan sebagai string kosong "", bukan dihilangkan.

$kk = $verifaid->ocr()->kk('/path/ke/kk.jpg');

echo $kk['informasi_keluarga']['nomor_kk'];

foreach ($kk['anggota_keluarga'] as $anggota) {
    echo $anggota['nama_lengkap'] . ' - ' . $anggota['status_hubungan'] . PHP_EOL;
}

Input gambar

Format yang diterima: JPEG, PNG, dan WEBP. Format dideteksi dari isi file, bukan dari ekstensinya. File yang formatnya salah ditolak sebelum dikirim, jadi tidak memakan kuota.

use Verifaid\Image;

// Path file
$verifaid->ocr()->ktp('/path/ke/ktp.jpg');

// File upload Laravel / Symfony
$verifaid->ocr()->ktp($request->file('ktp'));

// Isi file mentah, misalnya dari S3
$verifaid->ocr()->ktp(Image::fromString($binary, 'ktp.jpg'));

// Base64, dengan atau tanpa prefix "data:image/jpeg;base64,"
$verifaid->ocr()->ktp(Image::fromBase64($request->input('foto_ktp')));

Kuota

Satu hit dipotong begitu gambar lolos pemeriksaan kualitas dan diproses AI.

Gambar yang ditolak karena terlalu buram atau gelap (UnprocessableEntityException) tidak memotong kuota.
Gambar yang sudah diproses AI tetap memotong kuota, termasuk bila ternyata bukan dokumen yang valid, misalnya foto SIM yang dikirim ke ktp().
Bila pemrosesan gagal karena gangguan di sisi VerifAID, kuota dikembalikan otomatis.

Bila kuota habis, SDK melempar QuotaExceededException.

Host-to-Host (H2H)

Untuk klien enterprise dengan key sv_h2h_. Klien H2H tidak memakai dashboard: API key, dokumentasi integrasi, dan invoice dikirim lewat email oleh tim VerifAID, begitu juga top-up kuota dan upgrade paket. Hubungi tim VerifAID untuk berlangganan.

Method-nya sama dengan OCR, ditambah cek kuota:

$verifaid = new \Verifaid\Client('sv_h2h_xxx');

$sim = $verifaid->h2h()->sim('/path/ke/sim.jpg');

$kuota = $verifaid->h2h()->quota();
echo $kuota['tier'];            // PREMIUM
echo $kuota['remaining_hits'];  // 950

Jenis dokumen yang bisa dipakai bergantung pada paket:

Paket	Dokumen
BASIC	KTP
BUSINESS	KTP, SIM, NPWP, BPJS
PREMIUM	KTP, SIM, NPWP, BPJS, KK

Meminta dokumen di luar paket menghasilkan PermissionDeniedException.

Kuota H2H hanya terpotong bila ekstraksi berhasil. Gambar yang terlalu buram ditolak dengan UnprocessableEntityException, dan gangguan sementara di sisi VerifAID menghasilkan ServerException. Keduanya tidak memotong kuota. Untuk ServerException, ulangi request beberapa saat kemudian.

Menangani error

Setiap error dari API dilempar sebagai exception. Pesannya diambil dari respons server, dan kode exception berisi status HTTP.

use Verifaid\Exception\QuotaExceededException;
use Verifaid\Exception\RateLimitException;
use Verifaid\Exception\UnprocessableEntityException;
use Verifaid\Exception\VerifaidException;

try {
    $ktp = $verifaid->ocr()->ktp($path);
} catch (UnprocessableEntityException $e) {
    // Gambar buram atau bukan KTP. Minta pengguna memfoto ulang.
    return back()->withErrors(['ktp' => $e->getMessage()]);
} catch (QuotaExceededException $e) {
    // Kuota habis, perlu top-up.
} catch (RateLimitException $e) {
    sleep($e->getRetryAfter() ?? 60);
} catch (VerifaidException $e) {
    // Semua error lain dari SDK ini.
    report($e);
}

Exception	Kapan terjadi
`BadRequestException` (400)	Gambar tidak terkirim, formatnya tidak didukung server, atau file-nya rusak sehingga tidak bisa dibaca
`AuthenticationException` (401)	API key salah atau tidak ditemukan
`QuotaExceededException` (402)	Kuota hit habis
`PermissionDeniedException` (403)	Key/akun dinonaktifkan atau dokumen di luar paket H2H
`NotFoundException` (404)	Endpoint tidak ada, biasanya karena `base_url` keliru
`UnprocessableEntityException` (422)	Gambar terlalu buram, bukan dokumen yang diminta, atau datanya tidak terbaca
`RateLimitException` (429)	Batas request per menit terlampaui; lihat `getRetryAfter()`
`ServerException` (5xx)	Gangguan sementara di server VerifAID
`ConnectionException`	Server tidak bisa dihubungi (DNS, timeout, SSL)
`InvalidArgumentException`	Input salah sebelum request dikirim, misalnya file tidak ada, format gambar tidak didukung, atau key dipakai di resource yang salah

Semua exception di atas mengimplementasikan Verifaid\Exception\VerifaidException. Exception dari API juga menyediakan getStatusCode(), getErrorData(), dan getResponse().

SDK tidak mengulang request secara otomatis. Request OCR yang terkena timeout bisa saja tetap selesai diproses di server, sehingga mengulangnya bisa memotong kuota dua kali.

Konfigurasi

$verifaid = new \Verifaid\Client('sv_live_xxx', [
    'timeout'         => 120,        // detik, total per request
    'connect_timeout' => 10,         // detik, untuk membuka koneksi
    'base_url'        => 'https://verifaid.my.id/api/v1/',
]);

Opsi	Bawaan	Keterangan
`timeout`	`120`	OCR dengan AI bisa butuh puluhan detik, jadi jangan terlalu kecil. Lihat Pertanyaan umum
`connect_timeout`	`10`
`base_url`	`https://verifaid.my.id/api/v1/`
`transport`	`CurlTransport`	Implementasi `Verifaid\Http\TransportInterface`, misalnya untuk testing

Contoh di Laravel

Daftarkan client di AppServiceProvider:

use Verifaid\Client;

public function register(): void
{
    $this->app->singleton(Client::class, fn () => new Client(config('services.verifaid.key')));
}

Tambahkan di config/services.php:

'verifaid' => [
    'key' => env('VERIFAID_API_KEY'),
],

Lalu pakai di controller:

use Verifaid\Client;
use Verifaid\Exception\UnprocessableEntityException;

public function verifikasi(Request $request, Client $verifaid)
{
    $request->validate(['ktp' => 'required|image|max:5120']);

    try {
        $ktp = $verifaid->ocr()->ktp($request->file('ktp'));
    } catch (UnprocessableEntityException $e) {
        return back()->withErrors(['ktp' => $e->getMessage()]);
    }

    $request->user()->update([
        'nik'  => $ktp['nik'],
        'nama' => $ktp['full_name'],
    ]);

    return back()->with('status', 'KTP berhasil diverifikasi.');
}

Memanggil endpoint lain

Untuk endpoint yang belum punya method khusus, gunakan request(). Autentikasi dan penanganan error tetap berlaku.

$response = $verifaid->request('POST', 'endpoint/baru', ['kunci' => 'nilai']);

$response->getStatusCode();
$response->getMessage();
$response->getData();

Pertanyaan umum

ConnectionException: SSL certificate problem: unable to get local issuer certificate

Instalasi PHP Anda belum punya daftar sertifikat CA, sering terjadi di XAMPP atau Laragon di Windows. Unduh cacert.pem, lalu isi curl.cainfo di php.ini dengan path file tersebut.

Request OCR timeout

Biasanya OCR selesai dalam beberapa puluh detik. Saat layanan AI sedang lambat, server mengulang pemrosesan secara otomatis sehingga satu request bisa butuh lebih dari 120 detik. Bila SDK berhenti menunggu lebih dulu, server tetap menyelesaikan request itu, dan kuota OCR bisa tetap terpotong walaupun hasilnya tidak sampai ke aplikasi Anda.

Untuk proses di background job atau queue, naikkan opsi timeout, misalnya ke 300. Pastikan juga max_execution_time PHP dan batas waktu worker Anda lebih besar dari nilai tersebut.

Pengembangan

composer install
composer test

Test integrasi menjalankan server bawaan PHP di localhost, jadi tidak memerlukan API key dan tidak menghubungi server VerifAID.

Lisensi

MIT. Lihat LICENSE.

verifaid / verifaid-php

Package info

Security

Statistics