税率 API | Lovat Compliance

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 的三字母大写国家/地区代码	required
arrival_zip	细绳	美国订单必填：订单发货地的邮政编码	required to the US orders
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 地址。数字服务所需	required for digital services
exemption_type	细绳	仅适用于美国订单	可选的
phone_number_of_buyer	细绳	可选的数字服务。至少前 5 位数字包含国家/地区代码	可选的
bank_country_of_buyer	细绳	可选的数字服务。符合 ISO 3166-1 alpha-3 的三字母大写国家/地区代码	可选的

Errors List

支持的 HTTP 错误列表：

200, 201, 204
没有错误

400 Bad Request
这通常表明缺少必需的参数。详情请参阅响应正文

401 Unauthorized
未提供有效的 API 密钥

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

403 Forbidden
没有权限。详情请参阅响应正文

404 Not Found
请求的项目不存在

409, 422
请求参数无效

412 Precondition Failed
项目尚未激活（在Get Token方法中使用）

415 Unsupported Media Type
HTTP 标头中缺少“Content-Type：application/json”

500, 502, 503, 504 Server Errors
出问题了

示例查询请求

来自控制台的示例请求：

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 晚八小时）。在后一种情况下，请务必考虑夏令时（如果适用）。

国家

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

数字服务的税收类别

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

通话限制

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

豁免类型

对于美国订单，仅限豁免类型：批发、政府、市场、其他、非豁免或无。