Valvat 技术文档

1. 安装指南

Valvat 是一个用于验证欧洲增值税号（VAT）的 Ruby 库。它既可以作为独立的验证工具，也可以与 ActiveModel 集成使用。以下是安装 Valvat 的步骤：

通过 Bundler 安装

在你的 Gemfile 中添加以下内容：

gem 'valvat'

然后运行以下命令来安装依赖：

$ bundle

手动安装

你也可以通过以下命令手动安装 Valvat：

$ gem install valvat

2. 项目的使用说明

Valvat 提供了多种验证增值税号的方式，包括语法验证、通过 VIES 或 HMRC 网络服务进行验证，以及与 ActiveModel 的集成。

语法验证

你可以通过以下方式验证增值税号的语法：

Valvat.new("DE345789003").valid?
# => true 或 false

你也可以直接验证字符串：

Valvat::Syntax.validate("DE345789003")
# => true 或 false

通过网络服务验证

你可以通过 VIES 或 HMRC 网络服务验证增值税号是否存在：

Valvat.new("DE345789003").exists?
# => true 或 false 或 nil

或者直接验证字符串：

Valvat::Lookup.validate("DE345789003")
# => true 或 false 或 nil

对于英国（UK）的增值税号，你需要提供 HMRC 的认证信息：

Valvat::Lookup.validate(
  "GB553557881",
  uk: {
    client_id: '<client_id>',
    client_secret: '<client_secret>'
  }
)
# => true 或 false 或 nil

获取详细信息

你可以通过传递 {detail: true} 参数来获取更多详细信息：

Valvat.new("IE6388047V").exists?(detail: true)
=> {
  :country_code=> "IE", :vat_number => "6388047V", :valid => true,
  :request_date => Date.today, :name=> "GOOGLE IRELAND LIMITED",
  :address=> "1ST & 2ND FLOOR ,GORDON HOUSE ,BARROW STREET ,DUBLIN 4"
} or false or nil

处理维护错误

如果网络服务暂时不可用，exists? 或 Valvat::Lookup.validate 会返回 nil。你可以通过 raise_error 选项来抛出错误：

Valvat.new("IE6388047V").exists?(raise_error: true)

3. 项目 API 使用文档

Valvat::Syntax

用于验证增值税号的语法。

Valvat::Syntax.validate("DE345789003")
# => true 或 false

Valvat::Lookup

用于通过网络服务验证增值税号。

Valvat::Lookup.validate("DE345789003")
# => true 或 false 或 nil

Valvat::Checksum

用于验证增值税号的校验和（实验性功能）。

Valvat::Checksum.validate("DE345789003")
# => true 或 false

4. 项目安装方式

Valvat 可以通过 Bundler 或手动安装。

通过 Bundler 安装

在 Gemfile 中添加：

gem 'valvat'

然后运行：

$ bundle

手动安装

运行以下命令：

$ gem install valvat

5. 与 ActiveModel / Rails 集成

简单语法验证

在模型中添加以下内容：

class MyModel < ActiveRecord::Base
  validates :vat_number, valvat: true
end

通过网络服务验证

在模型中添加以下内容：

validates :vat_number, valvat: { lookup: true }

对于英国增值税号：

validates :vat_number, valvat: { lookup: { uk: { client_id: '<client_id>', client_secret: '<client_secret>' } } }

处理网络服务不可用的情况

如果网络服务不可用，默认情况下验证会通过。你可以通过 fail_if_down 选项使其失败：

validates :vat_number, valvat: { lookup: { fail_if_down: true } }

实验性校验和验证

在模型中添加以下内容：

validates :vat_number, valvat: { checksum: true }

6. 配置

你可以通过以下方式配置 Valvat 的默认行为：

Valvat.configure(
  raise_error: true,
  http: { read_timeout: 5 },
  uk: {
    sandbox: true, # 使用沙盒模式
    client_id: <client_id>, # HMRC API v2 认证所需
    client_secret: <client_secret> # HMRC API v2 认证所需
  }
)

通过以上配置，你可以全局设置 Valvat 的行为，而不需要在每次调用时传递相同的参数。

---

以上就是 Valvat 项目的技术文档，涵盖了安装指南、使用说明、API 文档以及安装方式。希望这篇文档能帮助你更好地理解和使用 Valvat。