税率 API

LOVAT 税率 API 技术集成说明

简介

以下文档涵盖了 OMP API 元素的信息，包括请求、响应和错误代码。

要集成 OMP 税率 API：

注册一个 Lovat OMP 帐户。
填写公司资料。
选择计划。
设置 Webhook。
获取令牌。
设置税收规则。

术语和缩写

API – 应用程序编程接口。系统提供的一组调用，用于与外部软件产品集成。

商家 – 在线商店的所有者。

客户 – 为商品或服务付款的个人。

交易 – 客户从商家处收到的商品或服务的资金转移。

令牌 – 系统用来识别商家和注册交易的网站的秘密字符串。

API 参考

Lovat API 使用 REST 架构。该 API 具有可预测的面向资源的 URL，并使用 HTTP 响应代码来指示 API 错误。API 始终以 JSON 格式响应，包括错误情况。

身份验证

对税率 API 的身份验证通过 HTTP 标头基本身份验证执行。订阅者需要提供令牌作为基本身份验证值。如果您是 Lovat 的新用户，则需要注册一个帐户以获取您的 API 密钥。该 API 使用内置 HTTP 功能，例如 HTTP 身份验证和 HTTP 动词，这些功能可以由现成的 HTTP 客户端进行解释。它还支持跨源资源共享，允许您从客户端 Web 应用程序安全地访问它。

URL

Lovat API 使用以下端点路径：

生产区域:

https://merchant.vatcompliance.co/api/1/tax_rate  — Tax Rate API

测试区域:

sandbox.vatcompliance.co/api/1/tax_rate

方法

请求类型：POST

https://merchant.vatcompliance.co/api/1/tax_rate/{access_token}

JSON 参数

范围	类型	描述	必需的
transaction_id	细绳	最多 255 个字符	选修的
сurrency	细绳	交易货币。符合 ISO 4217 的三字母货币代码	选修的
If_digital	波尔	数字服务必需	选修的
transaction_sum	漂浮	购物订单总金额	选修的
delivery_fee	漂浮	订单运费总额	选修的
arrival_country	细绳	订单发货到的国家/地区。符合 ISO 3166-1 alpha-3 标准的三个大写字母的国家/地区代码	必需的
arrival_zip	细绳	美国订单必填：订单发货地邮政编码	需要美国订单
arrival_state	细绳	对于美国、加拿大和英国：订单发货地的两字母 ISO 州代码	选修的
departure_country	细绳	订单发货国家/地区的三个字母 ISO 国家/地区代码。所有国家/地区均按照 ISO 3166-1 alpha-3 指定为字符串	选修的
departure_zip	细绳	对于美国订单：订单发货地的邮政编码	选修的
departure_state	细绳	对于美国、加拿大：订单发货地的两字母 ISO 州代码	选修的
service_code	细绳	对于以数字方式提供的服务，需要缴纳税款。数字服务的税收类别	选修的
good_code	细绳	根据欧盟八位编码系统联合命名法 (CN) 编制的商品代码	选修的
vat_number_of_buyer	细绳	买家税号	选修的
buyer_ip	细绳	买家的 IP 地址。数字服务必填	数字服务所需
exemption_type	细绳	仅适用于美国订单	选修的
phone_number_of_buyer	细绳	数字服务可选。前 5 位数字至少包含国家代码	选修的
bank_country_of_buyer	细绳	数字服务可选。符合 ISO 3166-1 alpha-3 标准的三个大写字母的国家/地区代码	选修的

错误列表

支持的 HTTP 错误列表：

200、201、204
无错误

400 错误请求
这通常表示缺少必需参数。请参阅响应正文了解详情

401 未授权
未提供有效的 API 密钥

402 请求失败
尽管参数有效，但请求失败

403 禁止
没有权限。请参阅响应正文了解详情

404 未找到
请求的项目不存在

409、422
请求参数无效

412 先决条件失败
项目尚未激活（用于获取令牌方法）

415 不支持的媒体类型
HTTP 标头中缺少“Content-Type：application/json”

500、502、503、504 服务器错误
出现问题

示例查询请求

来自控制台的示例请求：

curl-v GET https://merchant.vatcompliance.net/api/1/VAT_rate/get/5aae918d97964ff88df64b059c2cc0f8
--header "Content-Type: application/json" \
-d '{
   "arrival_country": "ITA",
  "departure_country": "GBR",
   "transaction_id": "7668999765",
  "transaction_sum": 10,
  "vat_number_of_buyer": "IT8996543"
}'
{
  "arrival_country": "GBP",
  "currency": "EUR",
  "delivery_fee": 0,
  "departure_country": "HUN",
"vat_number_of_buyer": "IT8996543",
  "transaction_datetime": "2021-01-09",
  "transaction_id": "45000098"
}
{
  "arrival_country": "USA",
  "arrival_state": "NY",
  "arrival_zip": "10034",
  "departure_country": "USA",
  "departure_state": "TX",
  "departure_zip": "77554",
  "transaction_datetime": "2021-01-01",
  "transaction_id": "788654333"
}

响应元素

范围	类型/示例	描述
transaction_type	“export/import”, “b2c_distance_sales”, “reverse_charge”
transaction_jurisdiction	“ITA”, “GBR”	订单应纳税国家/地区的三位 ISO 国家/地区代码。所有国家/地区均根据 ISO 3166-1 alpha-3 指定为字符串
taxable_state	“NY”	对于美国、加拿大、英国：订单应纳税的两字母 ISO 州代码
sales_tax_rate	8	销售税率
vat_rate	20	增值税税率
export_country	“USA”, “GBR”	交易类型为出口/进口的订单的出口国家
import_country	“USA”, “GBR”	交易类型为出口/进口的订单的进口国家

响应示例

{
  "transaction_type": "b2c_distance_sales",
  "taxable_jurisdiction": "USA",
  "taxable_state": "NY",
  "sales_tax_rate": 8.25
}
{
  "transaction_type": "export/import",
  "taxable_jurisdiction": "GBR",
  "vat_rate": 0,
  "export_country": "GBR",
  "import_country": "ITA"
}
{
  "transaction_type": "reverse_charge",
  "taxable_jurisdiction": "FRA",
  "vat_rate": 0
}

日期格式

所有日期均按照 ISO 8601 指定为字符串。您可以指定 UTC 日期字符串（例如 2013-01-15T00:00:00Z），也可以指定 UTC 偏移量（例如 2013-01-15T00:00:00-08:00，比 UTC 晚 8 小时）。在后一种情况下，请务必考虑夏令时（如果适用）。

国家

我们支持全球以下国家/地区：美国、欧盟国家、英国、俄罗斯、乌克兰、白俄罗斯、挪威、加拿大、澳大利亚、日本。

数字服务的税收类别

音频/视频内容	1
直播	2
电话服务	3
互联网电话服务	4
呼叫管理服务	5
寻呼服务	6
互联网接入	7
图片	8
音乐	9
游戏	10
电子报纸	11
网站托管	12
远程维护程序	13
网站上的广告空间	14
电子书	15
许可证	16
约会	17
远程教育	18
赌博	19

呼叫限制

对于商户计划，我们将 API 请求限制为每分钟 1,000 次。您的呼叫次数可能超过每月计划限制。如果您在下个月超出计划限制，则将单独收取超额费用。

豁免类型

仅适用于美国订单的豁免类型：批发、政府、市场、其他、非豁免或零。