API validasi nomor PPN: verifikasi nomor pajak UE dalam satu POST
Validasi nomor PPN untuk seluruh 27 negara anggota UE dengan satu panggilan API. Validitas pengembalian, kode negara, dan nomor yang diformat. Tingkat gratis, tanpa SOAP XML.
Anda menjual perangkat lunak ke bisnis di Eropa. Undang-undang perpajakan UE mengharuskan Anda memvalidasi PPN pembeli ID sebelum menerapkan biaya balik (PPN 0%). Layanan resmi VIES memiliki waktu aktif yang tidak dapat diandalkan dan mengembalikan SOAP XML. Anda memerlukan alternatif yang lebih cepat dan tenang.
Botoi itu /v1/validate/vat titik akhir memvalidasi nomor PPN untuk seluruh 27 anggota UE
negara bagian dan Inggris. Kirim POST, dapatkan respons JSON dengan validitas, kode negara, dan
nomor yang diformat. Tidak ada penguraian XML. Tidak ada file WSDL. Tidak ada batas waktu dari pemerintah yang kelebihan beban
server.
Panggilan API
Kirimkan nomor PPN dengan awalan negara dua huruf:
Tanggapan:
Itu valid bidang adalah true ketika nomornya cocok dengan format yang diharapkan
untuk negaranya. Itu country_code Dan country bidang memberitahu Anda
di yurisdiksi mana nomor tersebut berada.
Ketika nomor gagal validasi
Jika jumlahnya tidak sesuai dengan pola yang diharapkan, valid kembali
false. Responsnya masih mencakup negara yang terdeteksi:
Nomor PPN Jerman memerlukan tepat 9 digit setelahnya DE awalan. Yang ini punya 5.
Frontend Anda dapat menampilkan nama negara dan format yang diharapkan untuk membantu pengguna memperbaikinya
masukan.
Integrasi pembayaran Stripe
Sebelum membuat sesi checkout Stripe, validasi ID PPN pembeli. Jika valid, setel
pelanggan ke tax_exempt: "reverse" jadi Stripe mengenakan PPN 0%. Jika itu
tidak valid, tolak formulir dan minta pembeli memperbaikinya.
Hal ini mencegah dua masalah umum: membebankan PPN ke bisnis yang seharusnya dibebaskan (membuat pusing refund), dan memberikan pembebasan pajak kepada seseorang yang memiliki nomor PPN palsu (menciptakan masalah audit).
Pembuatan faktur dengan PPN bersyarat
Saat membuat faktur, Anda perlu menentukan tarif PPN. Aturannya:
- Penjualan B2B di negara yang sama: kenakan tarif PPN domestik Anda.
- Penjualan B2B lintas batas dengan ID PPN yang valid: berlaku biaya balik (0%).
- ID PPN tidak valid atau hilang: kenakan tarif lokal pembeli.
Itu country_code dari respons API mendorong logika ini:
Validasi formulir pendaftaran SaaS B2B
Tambahkan bidang nomor PPN ke formulir pendaftaran Anda dan validasi saat dikirimkan. Jika valid, isi otomatis tarik-turun negara. Jika tidak valid, tampilkan kesalahan sebelum formulir mencapai backend Anda.
Ini menjauhkan data buruk dari sistem penagihan Anda. Ini juga menyelamatkan tim keuangan Anda dari pekerjaan manual memverifikasi nomor PPN setelah pelanggan mendaftar dan mulai menggunakan produk.
Format PPN menurut negara
Setiap negara UE memiliki format nomor identifikasi PPN yang berbeda. API memvalidasi terhadap semua pola ini:
Daftar lengkapnya mencakup 27 negara anggota UE ditambah Inggris. Format berkisar dari 8 digit (Denmark, Luksemburg) hingga 12 digit (Swedia). Beberapa negara menyertakan huruf di badannya nomor (Prancis, Spanyol, Irlandia).
Validasi format vs pencarian VIES
API ini memvalidasi struktur dari nomor PPN. Ini mengkonfirmasi awalan, panjang, dan pola karakternya sesuai dengan aturan di negara tersebut. Ia tidak mempertanyakan Komisi Uni Eropa Database VIES untuk mengonfirmasi nomor tersebut aktif terdaftar.
Untuk sebagian besar alur pembayaran, validasi format adalah langkah pertama yang tepat. Ini menangkap kesalahan ketik, hilang awalan, dan nomor yang dibuat secara instan, tanpa bergantung pada layanan eksternal itu sering turun. Jika Anda juga memerlukan status pendaftaran, hubungi VIES setelah pemeriksaan format lolos. Pendekatan dua langkah ini mengurangi panggilan VIES sebesar 15-30% (semua format yang tidak valid tidak pernah mencapai layanan lambat).
Poin-poin penting
Tingkat gratis mencakup pengembangan dan penggunaan produksi bervolume rendah. Untuk pembayaran dengan lalu lintas tinggi
mengalir, tambahkan kunci API Anda di Authorization: Bearer tajuk. Periksa
dokumen API
untuk referensi titik akhir lengkap dan
taman bermain interaktif untuk menguji nomor PPN di browser Anda.
FAQ
- Negara manakah yang didukung oleh API validasi PPN?
- Seluruh 27 negara anggota UE, ditambah Inggris (awalan GB). Setiap negara memiliki pola formatnya sendiri. API mendeteksi negara dari awalan dua huruf dan memvalidasi berdasarkan ekspresi reguler yang benar untuk yurisdiksi tersebut.
- Apakah ini menggantikan layanan VIES SOAP?
- Ini menggantikan bagian validasi format. VIES mengonfirmasi apakah nomor tertentu terdaftar pada otoritas pajak nasional. API ini memvalidasi struktur dan format secara instan, tanpa bergantung pada waktu aktif VIES. Gunakan keduanya bersamaan: periksa format terlebih dahulu, lalu VIES mencari status terdaftar.
- Apakah nomor PPN disimpan setelah validasi?
- Tidak. Nomor tersebut diproses dalam memori dan dibuang setelah respons. Tidak ada yang ditulis ke disk atau sistem eksternal apa pun.
- Bisakah saya memvalidasi nomor PPN Inggris setelah Brexit?
- Nomor PPN Inggris (awalan GB) mengikuti pola yang diketahui dan dapat divalidasi secara struktural. Mereka tidak lagi menjadi bagian dari sistem EU VIES, namun pemeriksaan format masih berfungsi.
- Apa yang terjadi jika saya menghilangkan awalan negara?
- API memerlukan awalan negara yang terdiri dari dua huruf (misalnya, "DE", "FR", "NL"). Tanpanya, titik akhir akan menampilkan kesalahan yang menjelaskan bahwa kode negara tidak ada atau tidak didukung.
Mulai membangun dengan botoi
150+ endpoint API untuk pencarian, pemrosesan teks, pembuatan gambar, dan utilitas developer. Paket gratis, tanpa kartu kredit.