Getting started with REST API

Mautic 提供了多个 REST API 端点，用于操作和检索 Mautic 中各种实体的信息。您可以在左侧的导航菜单中找到可用的端点。

Warning

默认情况下，Mautic 会禁用 REST API。Mautic 管理员可以在 Mautic UI 的 配置 > API 设置 下启用 API，或者直接在 config/local.php 中设置 'api_enabled' => 1。 在 Mautic 5 之前的版本中，此设置位于 app/config/local.php。

Error handling

如果出现 OAuth 错误，您应该看到一个类似于以下 JSON 编码的数组：

{
   "error": "invalid_grant",
   "error_description": "The access token provided has expired."
}

如果发生系统错误，您应该看到一个类似于以下示例的 JSON 编码的数组：

{
   "error": {
     "message": "You do not have access to the requested area/action.",
     "code": 403
   }
}

Mautic version verification

如果您的 API 服务支持多个 Mautic 版本，并且这些版本具有不同的功能，则需要验证您正在使用的 Mautic 版本。从 Mautic 2.4.0 开始，版本号会出现在所有 API 响应头中，名称为 Mautic-Version。

您可以使用 Mautic API 库检索 Mautic 版本：

// Make any API request:
$api = $this->getContext('contacts');
$response = $api->getList('', 0, 1);

// Get the version number from the response header:
$version = $api->getMauticVersion();

$version 的格式为语义版本号 [major].[minor].[patch]，例如 2.4.0。 如果您在最新的 GitHub 版本上尝试，则版本将具有后缀 -dev，例如 2.5.1-dev。

API endpoints

所有响应都采用 JSON 编码。

基本 API 端点是 https://mautic.example.com/api。

Mautic API library

Mautic 有一个 Mautic API Library，您可以在您的 PHP 项目中使用 - 推荐。其他语言需要使用自定义工具或第三方库来处理 OAuth 或请求处理。

Install via Composer

要使用 Composer 安装，请运行 composer require mautic/api-library。

Install manually

从 GitHub 下载 Mautic API library package，解压缩它，然后在您的项目中包含以下代码，如果需要，请更改路径：

require_once __DIR__ . '/lib/Mautic/MauticApi.php';

Note

有关使用该库的更多说明，请参阅 GitHub 存储库中的 README 文件，或查看本文档中的代码示例。

API rate limiter cache

Attention

速率限制器缓存在 Mautic 版本 7 及更高版本中不可用。

您可以在 local.php 文件中配置速率限制器缓存。默认配置使用文件系统，如下所示：

api_rate_limiter_cache => [
   'type'      => 'file_system',
],

您可以根据 :xref: 的 DoctrineCacheBundle docs 文档中的描述配置任何类型的缓存，或者像下面这样配置一个 memcached 服务器：

'api_rate_limiter_cache' => [
   'memcached' => [
      'servers' =>
      [
         [
            'host' => 'localhost',
            'port' => 11211
         ]
      ]
   ]
],