API描述

文档将帮助您了解：

• 如何使用VK API广告数据运算符。
• 您的广告活动数据如何传输到互联网广告统一登记簿。

API简述：

• 请求主体和响应主体的媒体类型：
  • application/json。
  • multipart/form-data。

Base URL	描述
	集成的测试。您可以使用不传输到互联网广告统一登记簿的测试数据。
https://api.ord.vk.com	生产集成仅使用需要传递到互联网广告统一登记簿的数据。 记住，您对于提供虚假信息负有责任。

登录授权

任何注册用户都可以访问API。

所有对API的请求都使用API令牌。

获取API令牌

您可以在广告数据运算符的个人账号中获取API令牌：

• sandbox.ord.vk.com—用于开发环境（沙盒环境）。
• ord.vk.com—用于生产环境。

获取API令牌。API令牌无限期。您最多可以创建5个API令牌。

留心！

个人账号仅显示API令牌一次。如果API令牌丢失，需要创建一个新的。

发送请求

发送请求，请在标头中传递获得的API令牌：Authorization: Bearer <TOKEN>.

留心！

如果您收到服务器返回的401 Unauthorized错误代码，则可能是因为：

• 未传递API令牌。
• 传递了错误的API令牌。

使用

注意

• API区分大小写。所有参数、字段和可能的值都应按照文档中指定的方式传递，包括大小写。
• 如果字段或参数是可选的，请不要传递它们或将其值设置为null。

Swagger文档

Swagger文档中的方法包含特殊的标记：

• 如果参数或字段名称旁边有红色星号，则表示它是必填的。
• 如果没有红色星号，则表示该参数或字段是可选的。

参数或字段的描述可能包含条件文本，说明它们的应用条件。Swagger文档包含所有参数和字段的示例：包括必填和可选的标记，以及描述文本中的条件。如果您想使用这个示例执行请求，该请求可能是不正确的。有关正确的请求示例，请参阅API cookbook部分。

网页界面

您可以通过Swagger的网页界面使用API：

1. 在 Servers 部分选择服务器。
2. 点击Authorize按钮。
3. 在Available authorizations对话框中：
   1. 在Value字段中输入获得的API令牌。
   2. 点击Authorize按钮。
4. 选择API方法，然后点击其名称。
5. 点击Try it out按钮。
6. 输入参数值和请求体内容。
7. 点击Execute按钮。

软件工具

您可以使用任何允许发送 HTTPS 请求的软件工具来调用API。

请求例子：

curl -XGET -i -H 'Authorization: Bearer 948d799671533a2eb98e575aa96718e6' https://api-sandbox.ord.vk.com/v1/person/my

班本化

API有版本：

• v1.
• v2.

版本在方法的重大变更时进行更改：

• 更改请求格式。
• 更改字段集。
• 更改响应。

版本不会更改，如果：

• 字段值的验证规则发生变化。
• 添加可选字段。

每个方法属于特定的版本。这可以从方法的终端点中确定。例子：/v1/person/{external_id}.

留心！

v1 和 v2 方法并不总是兼容的。

响应格式

API响应包含通用的 HTTP 响应代码，用于指示请求的成功或错误。

API响应可能包含以 JSON 格式表示的响应主体。

成功的响应

如果请求成功执行，API将返回2xx类别的状态码：

• 200 OK.
• 201 Created.

响应例子：

201 Created

{
  "marker": "LgsiTCSaD"
}

错误的响应

如果请求出现错误，API将返回4xx和5xx类别的状态码：

• 400 Bad Request。
• 401 Unathorized。更多信息请参阅登录授权部分。
• 403 Forbidden。
• 404 Not found。
• 409 Conflict。
• 500 Internal Server Error。如果您遇到此错误，请稍后重试调用方法或联系技术支持。

此外，API将在响应主体中返回一个带有错误描述字段error的对象。

响应例子：

400 Bad request

{
  "error": "Wrong INN field"
}