README

如果你使用 Symfony 4 或 5，可以使用我们的 Symfony 扩展包。

安装

composer require targito/targito-api

使用

通过创建一个新的 \Targito\Api\TargitoApi 实例并提供正确的凭证来访问 API。

<?php

use Targito\Api\TargitoApi;

$api = new TargitoApi($credentials);

// do stuff with api

获取凭证

凭证通过实现 \Targito\Api\Credentials\CredentialsInterface 的对象提供。

默认情况下有两个这样的类，分别是 \Targito\Api\Credentials\Credentials 和 \Targito\Api\Credentials\EnvironmentCredentials。

Credentials 类接受您的账户 ID 和 API 密码作为构造函数参数，而 EnvironmentCredentials 从环境变量中获取它们（默认为 TARGITO_ACCOUNT_ID 和 TARGITO_API_PASSWORD）。

<?php

use Targito\Api\TargitoApi;
use Targito\Api\Credentials\Credentials;
use Targito\Api\Credentials\EnvironmentCredentials;

// provide the credentials in constructor
$credentials = new Credentials('my-account-id', 'my-api-password');
$api = new TargitoApi($credentials);

// get them automatically from environment variables using default TARGITO_ACCOUNT_ID and TARGITO_API_PASSWORD variables
$credentials = new EnvironmentCredentials();
$api = new TargitoApi($credentials);

// customize the environment variables
$credentials = new EnvironmentCredentials('MY_CUSTOM_ACCOUNT_ID_VARIABLE', 'MY_CUSTOM_API_PASSWORD_VARIABLE');
$api = new TargitoApi($credentials);

发送请求

HTTP 请求是通过实现 \Targito\Api\Http\HttpRequestInterface 的对象发送的。

有两个类实现了该接口，分别是 \Targito\Api\Http\Request\CurlHttpRequest 和 \Targito\Api\Http\Request\StreamHttpRequest。

如果您没有提供 HTTP 请求的对象，则默认使用根据您的 PHP 设置选择的对象 - 如果启用了 curl 扩展，则使用 CurlHttpRequest，否则使用 StreamHttpRequest。

注意：如果可能的话，应始终使用 CurlHttpRequest，因为 StreamHttpRequest 只是一个后备实现。

注意：该接口被认为是半内部接口 - 如果您提供自己的实现，请注意，可能会定期添加新方法，这可能会破坏您的实现。否则将保持向后兼容。

TargitoApi 类包含访问单个 API 模块（例如联系人、交易等）的方法，这些模块反过来包含发送 API 请求的方法。

<?php

use Targito\Api\TargitoApi;
use Targito\Api\Credentials\EnvironmentCredentials;
use Targito\Api\DTO\Request\Contact\DeleteContactRequest;

// get credentials from env variables and use the default http request implementation
$api = new TargitoApi(new EnvironmentCredentials());

// get the contacts API module
$contactsApi = $api->contacts();

$result = $contactsApi->deleteContact(DeleteContactRequest::fromArray([
    'id' => 'contact_id',
    'origin' => 'contact_origin'
]));

echo $result->jobId;

每个 API 方法都接受数据作为数组或相应的 DTO 对象。每个 DTO 对象也可以从数组创建。这些都是有效且功能等效的。

<?php

use Targito\Api\TargitoApi;
use Targito\Api\Credentials\EnvironmentCredentials;
use Targito\Api\DTO\Request\Contact\DeleteContactRequest;

$api = new TargitoApi(new EnvironmentCredentials());

// provide data as array
$api->contacts()->deleteContact([
    'id' => 'contact_id',
    'origin' => 'contact_origin'
]);

// create the DeleteContactRequest from array
$api->contacts()->deleteContact(DeleteContactRequest::fromArray([
    'id' => 'contact_id',
    'origin' => 'contact_origin'
]));

// create the DeleteContactRequest manually
$deleteRequest = new DeleteContactRequest();
$deleteRequest->id = 'contact_id';
$deleteRequest->origin = 'contact_origin';

$api->contacts()->deleteContact($deleteRequest);

每个方法返回特定于该方法的结果（例如 AddContactResponse、DeleteContactResponse 等）。请参阅各个类以获取可用属性的列表。

模块

联系人

通过在 API 对象上调用 contacts() 或手动构建 \Targito\Api\Endpoint\TargitoContactEndpoint 来访问该模块。

方法

添加联系人
- 请求数据：\Targito\Api\DTO\Request\Contact\AddContactRequest
- 属性
  - string email - 要添加的联系人的电子邮件
  - string origin - 联系人来源
  - bool isOptedIn - 联系人是否已注册
  - bool forbidReOptIn （可选）- 是否禁止再次注册，如果联系人在数据库中已存在且已取消注册
  - bool forceDoubleReOptIn （可选）- 是否强制注册，如果联系人在数据库中已存在
  - array consents （可选）- 包含联系人已给予的同意的字符串数组
  - array columns （可选）- 任何其他列（必须在 Targito 中定义），其中数组键是列名
- 返回值
  - class: \Targito\Api\DTO\Response\Contact\AddContactResponse
  - 属性
    - string id - 联系人的 ID
    - bool isOptedIn - 联系人是否已注册
    - bool isOptedOut - 联系人是否已取消注册
    - bool isNew - 联系人是否是新创建的还是之前就存在的
    - object previousState - 如果联系人在之前存在，此属性将是 \Targito\Api\DTO\Contact\AddContactHistory 的实例，否则为 null。
      - AddContactHistory 包含以下属性：bool isOptedIn 和 bool isOptedOut
addContactWithCheck
- 请求数据：\Targito\Api\DTO\Request\Contact\AddContactWithCheckRequest
- 属性
  - 与 addContact 相同的属性
  - 字符串 contactListId - 要检查联系人是否已存在的联系人列表的 UUID
  - 字符串 isInContactListMailingId - 要发送给在 contactListId 中已存在的联系人的交易消息的 UUID
- 返回值
  - 类：\Targito\Api\DTO\Response\Contact\AddContactWithCheckResponse
  - 属性
    - 与 addContact 相同的属性
    - bool isInContactList - 联系人是否在请求中指定的联系人列表中
editContact
- 请求数据：\Targito\Api\DTO\Request\Contact\EditContactRequest
- 属性
  - 字符串 email - 正在编辑的联系人邮箱
  - string origin - 联系人来源
  - bool isOptedIn（可选）- 联系人是否已订阅
  - array consents （可选）- 包含联系人已给予的同意的字符串数组
  - array columns （可选）- 任何其他列（必须在 Targito 中定义），其中数组键是列名
- 返回值
  - 类：\Targito\Api\DTO\Response\Contact\EditContactResponse
  - 属性
    - bool success - 编辑是否成功
deleteContact
- 请求数据：\Targito\Api\DTO\Request\Contact\DeleteContactRequest
- 属性
  - 字符串 id - 联系人 ID
  - string origin - 联系人来源
- 返回值
  - 类：\Targito\Api\DTO\Response\Contact\DeleteContactResponse
  - 属性
    - 字符串 jobId - 执行删除操作的作业 ID
optOutContact
- 请求数据：\Targito\Api\DTO\Request\Contact\OptOutContactRequest
- 属性
  - 字符串 email - 正在删除的联系人邮箱
  - string origin - 联系人来源
- 返回值
  - 类：\Targito\Api\DTO\Response\Contact\OptOutContactResponse
  - 属性
    - bool success - 取消订阅是否成功
exportContactById
- 请求数据：\Targito\Api\DTO\Request\Contact\ExportContactByIdRequest
- 属性
  - 字符串 id - 联系人 ID
  - string origin - 联系人来源
- 返回值
  - 类：\Targito\Api\DTO\Response\Contact\ExportContactByIdResponse
  - 属性
    - 字符串 jobId - 执行导出的作业 ID
changeContactEmailAddress
- 请求数据：\Targito\Api\DTO\Request\Contact\ChangeContactEmailAddressRequest
- 属性
  - string origin - 联系人来源
  - 字符串 oldEmail - 原始邮箱地址
  - 字符串 newEmail - 新邮箱地址
  - bool mergeIfExists - 如果设置为 true，并且新邮箱地址已存在，则将旧联系人和新联系人的所有事件合并为一个
- 返回值
  - 类：\Targito\Api\DTO\Response\Contact\ChangeContactEmailAddressResponse
  - 属性
    - bool success - 更改邮箱是否成功

Transact

通过在 api 对象上调用 transact() 或手动构造 \Targito\Api\Endpoint\TargitoTransactEndpoint 来访问此模块。

方法

sendEmail
- 请求数据：\Targito\Api\DTO\Request\Transact\SendEmailRequest
- 属性
  - 字符串 origin - 网站源
  - 字符串 email - 收件人邮箱
  - 字符串 mailingId - 来自 Targito 的邮件 ID
  - 字符串 fromName（可选）- 发件人姓名
  - 字符串 fromEmail（可选）- 发件人邮箱地址
  - 字符串 replyTo（可选）- 在邮件中用作 Reply-To 的邮箱地址
  - DateTime sendDateTime（可选）- 邮件发送的日期和时间
  - 数组 columns（可选）- 变量名 => 值对的哈希表
  - 数组 attachments -（可选）要么是数组的数组，要么是 \Targito\Api\DTO\Transact\Attachment 类的实例数组
    - Attachment 类构造函数参数
      - 字符串 name - 文件名
      - 字符串 mediaType - 文件的媒体类型（也称为 MIME 类型）
      - StreamInterface|stream|string - 文件内容，可以是字符串（文件的原始内容）、PHP 流（例如使用 fopen() 打开的文件）或 StreamInterface 的实例（如果您的应用程序使用 PSR-7 流的实现）
    - 如果您以数组的形式提供附件，其结构如下
      - 字符串 name - 文件名
      - 字符串 type - 文件的媒体类型
      - 字符串 data - 文件内容的 base64 编码
- 返回值
  - 类：\Targito\Api\DTO\Response\Transact\SendEmailResponse
  - 属性
    - bool success - 操作是否成功
sendMassEmail
- 请求数据：\Targito\Api\DTO\Request\Transact\SendMassEmailRequest
- 属性
  - 字符串 origin - 网站源
  - 数组 recipients - 可以是数组数组的数组或者 \Targito\Api\DTO\Transact\Recipient 类的实例数组
    - 收件人属性
      - 字符串 email - 收件人的电子邮件地址
      - 数组 columns（可选）- 变量名 => 值对的哈希表
  - 字符串 mailingId - 来自 Targito 的邮件 ID
  - 字符串 fromName（可选）- 发件人姓名
  - 字符串 fromEmail（可选）- 发件人邮箱地址
  - 字符串 replyTo（可选）- 在邮件中用作 Reply-To 的邮箱地址
  - DateTime sendDateTime（可选）- 邮件发送的日期和时间
- 返回值
  - 类: \Targito\Api\DTO\Response\Transact\SendMassEmailResponse
  - 属性
    - bool success - 操作是否成功

targito / targito-api

维护者

详细信息

README

安装

使用

获取凭证

发送请求

模块

联系人

方法

Transact

方法