affixapi.com API 文档。# 简介 Affix API 是一个 OAuth 2.1 应用程序,允许开发者访问客户数据,无需开发者管理或维护集成;或从用户那里收集第三方系统的登录凭证或 API 密钥。
Requires
- php: >=7.2
- ext-curl: *
- ext-json: *
- ext-mbstring: *
- guzzlehttp/guzzle: ^6.2
Requires (Dev)
- friendsofphp/php-cs-fixer: ^2.12
- phpunit/phpunit: ^8.0 || ^9.0
This package is auto-updated.
Last update: 2024-10-02 02:24:58 UTC
README
affixapi.com API 文档。
简介
Affix API 是一个 OAuth 2.1 应用程序,允许开发者访问客户数据,无需开发者管理或维护集成;或从用户那里收集第三方系统的登录凭证或 API 密钥。
OAuth 2.1
Affix API 遵循OAuth 2.1 规范。
作为 OAuth 应用程序,Affix API 不仅处理敏感用户凭证或 API 密钥的收集,还构建和维护与提供商的集成,因此您无需这样做。
如何获取访问令牌
为了开始,您必须
- 注册一个
client_id
- 将您的用户引导到登录流程(
https://connect.affixapi.com
,带有适当的查询参数) - 捕获我们在登录流程完成后发送到您的重定向 URI 的
authorization_code
,并用该authorization_code
交换 Bearer 令牌
沙盒密钥(xhr 模式)
dev
eyJhbGciOiJFUzI1NiIsImtpZCI6Ims5RmxwSFR1YklmZWNsUU5QRVZzeFcxazFZZ0Zfbk1BWllOSGVuOFQxdGciLCJ0eXAiOiJKV1MifQ.eyJwcm92aWRlciI6InNhbmRib3giLCJzY29wZXMiOlsiLzIwMjMtMDMtMDEveGhyL2NvbXBhbnkiLCIvMjAyMy0wMy0wMS94aHIvZW1wbG95ZWUiLCIvMjAyMy0wMy0wMS94aHIvZW1wbG95ZWVzIiwiLzIwMjMtMDMtMDEveGhyL2dyb3VwcyIsIi8yMDIzLTAzLTAxL3hoci9pZGVudGl0eSIsIi8yMDIzLTAzLTAxL3hoci9wYXlydW5zIiwiLzIwMjMtMDMtMDEveGhyL3BheXJ1bnMvOnBheXJ1bl9pZCIsIi8yMDIzLTAzLTAxL3hoci90aW1lLW9mZi1iYWxhbmNlcyIsIi8yMDIzLTAzLTAxL3hoci90aW1lLW9mZi1lbnRyaWVzIiwiLzIwMjMtMDMtMDEveGhyL3RpbWVzaGVldHMiLCIvMjAyMy0wMy0wMS94aHIvd29yay1sb2NhdGlvbnMiXSwidG9rZW4iOiIzODIzNTNlMi05N2ZiLTRmMWEtOTYxYy0zZDI5OTViNzYxMTUiLCJpYXQiOjE3MTE4MTA3MTQsImlzcyI6InB1YmxpY2FwaS1pbnRlcm1lZGlhdGUuZGV2LmVuZ2luZWVyaW5nLmFmZml4YXBpLmNvbSIsInN1YiI6InhociIsImF1ZCI6IjNGREFFREY5LTFEQ0E0RjU0LTg3OTQ5RjZBLTQxMDI3NjQzIn0.zUJPaT6IxcIdr8b9iO6u-Rr5I-ohTHPYTrQGrgOFghbEbovItiwr9Wk479GnJVJc3WR8bxAwUMAE4Ul6Okdk6Q
employees
端点示例
curl --fail \\
-X GET \\
-H 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6Ims5RmxwSFR1YklmZWNsUU5QRVZzeFcxazFZZ0Zfbk1BWllOSGVuOFQxdGciLCJ0eXAiOiJKV1MifQ.eyJwcm92aWRlciI6InNhbmRib3giLCJzY29wZXMiOlsiLzIwMjMtMDMtMDEveGhyL2NvbXBhbnkiLCIvMjAyMy0wMy0wMS94aHIvZW1wbG95ZWUiLCIvMjAyMy0wMy0wMS94aHIvZW1wbG95ZWVzIiwiLzIwMjMtMDMtMDEveGhyL2dyb3VwcyIsIi8yMDIzLTAzLTAxL3hoci9pZGVudGl0eSIsIi8yMDIzLTAzLTAxL3hoci9wYXlydW5zIiwiLzIwMjMtMDMtMDEveGhyL3BheXJ1bnMvOnBheXJ1bl9pZCIsIi8yMDIzLTAzLTAxL3hoci90aW1lLW9mZi1iYWxhbmNlcyIsIi8yMDIzLTAzLTAxL3hoci90aW1lLW9mZi1lbnRyaWVzIiwiLzIwMjMtMDMtMDEveGhyL3RpbWVzaGVldHMiLCIvMjAyMy0wMy0wMS94aHIvd29yay1sb2NhdGlvbnMiXSwidG9rZW4iOiIzODIzNTNlMi05N2ZiLTRmMWEtOTYxYy0zZDI5OTViNzYxMTUiLCJpYXQiOjE3MTE4MTA3MTQsImlzcyI6InB1YmxpY2FwaS1pbnRlcm1lZGlhdGUuZGV2LmVuZ2luZWVyaW5nLmFmZml4YXBpLmNvbSIsInN1YiI6InhociIsImF1ZCI6IjNGREFFREY5LTFEQ0E0RjU0LTg3OTQ5RjZBLTQxMDI3NjQzIn0.zUJPaT6IxcIdr8b9iO6u-Rr5I-ohTHPYTrQGrgOFghbEbovItiwr9Wk479GnJVJc3WR8bxAwUMAE4Ul6Okdk6Q' \\
'https://dev.api.affixapi.com/2023-03-01/xhr/employees'
prod
eyJhbGciOiJFUzI1NiIsImtpZCI6Ims5RmxwSFR1YklmZWNsUU5QRVZzeFcxazFZZ0Zfbk1BWllOSGVuOFQxdGciLCJ0eXAiOiJKV1MifQ.eyJwcm92aWRlciI6InNhbmRib3giLCJzY29wZXMiOlsiLzIwMjMtMDMtMDEveGhyL2NvbXBhbnkiLCIvMjAyMy0wMy0wMS94aHIvZW1wbG95ZWUiLCIvMjAyMy0wMy0wMS94aHIvZW1wbG95ZWVzIiwiLzIwMjMtMDMtMDEveGhyL2dyb3VwcyIsIi8yMDIzLTAzLTAxL3hoci9pZGVudGl0eSIsIi8yMDIzLTAzLTAxL3hoci9wYXlydW5zIiwiLzIwMjMtMDMtMDEveGhyL3BheXJ1bnMvOnBheXJ1bl9pZCIsIi8yMDIzLTAzLTAxL3hoci90aW1lLW9mZi1iYWxhbmNlcyIsIi8yMDIzLTAzLTAxL3hoci90aW1lLW9mZi1lbnRyaWVzIiwiLzIwMjMtMDMtMDEveGhyL3RpbWVzaGVldHMiLCIvMjAyMy0wMy0wMS94aHIvd29yay1sb2NhdGlvbnMiXSwidG9rZW4iOiIzYjg4MDc2NC1kMGFmLTQ5ZDAtOGM5OS00YzIwYjE2MTJjOTMiLCJpYXQiOjE3MTE4MTA4NTgsImlzcyI6InB1YmxpY2FwaS1pbnRlcm1lZGlhdGUucHJvZC5lbmdpbmVlcmluZy5hZmZpeGFwaS5jb20iLCJzdWIiOiJ4aHIiLCJhdWQiOiIwOEJCMDgxRS1EOUFCNEQxNC04REY5OTIzMy02NjYxNUNFOSJ9.n3pJmmfegU21Tko_TyUyCHi4ITvfd75T8NFFTHmf1r8AI8yCUYTWdfNjyZZWcZD6z50I3Wsk2rAd8GDWXn4vlg
employees
端点示例
curl --fail \\
-X GET \\
-H 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6Ims5RmxwSFR1YklmZWNsUU5QRVZzeFcxazFZZ0Zfbk1BWllOSGVuOFQxdGciLCJ0eXAiOiJKV1MifQ.eyJwcm92aWRlciI6InNhbmRib3giLCJzY29wZXMiOlsiLzIwMjMtMDMtMDEveGhyL2NvbXBhbnkiLCIvMjAyMy0wMy0wMS94aHIvZW1wbG95ZWUiLCIvMjAyMy0wMy0wMS94aHIvZW1wbG95ZWVzIiwiLzIwMjMtMDMtMDEveGhyL2dyb3VwcyIsIi8yMDIzLTAzLTAxL3hoci9pZGVudGl0eSIsIi8yMDIzLTAzLTAxL3hoci9wYXlydW5zIiwiLzIwMjMtMDMtMDEveGhyL3BheXJ1bnMvOnBheXJ1bl9pZCIsIi8yMDIzLTAzLTAxL3hoci90aW1lLW9mZi1iYWxhbmNlcyIsIi8yMDIzLTAzLTAxL3hoci90aW1lLW9mZi1lbnRyaWVzIiwiLzIwMjMtMDMtMDEveGhyL3RpbWVzaGVldHMiLCIvMjAyMy0wMy0wMS94aHIvd29yay1sb2NhdGlvbnMiXSwidG9rZW4iOiIzYjg4MDc2NC1kMGFmLTQ5ZDAtOGM5OS00YzIwYjE2MTJjOTMiLCJpYXQiOjE3MTE4MTA4NTgsImlzcyI6InB1YmxpY2FwaS1pbnRlcm1lZGlhdGUucHJvZC5lbmdpbmVlcmluZy5hZmZpeGFwaS5jb20iLCJzdWIiOiJ4aHIiLCJhdWQiOiIwOEJCMDgxRS1EOUFCNEQxNC04REY5OTIzMy02NjYxNUNFOSJ9.n3pJmmfegU21Tko_TyUyCHi4ITvfd75T8NFFTHmf1r8AI8yCUYTWdfNjyZZWcZD6z50I3Wsk2rAd8GDWXn4vlg' \\
'https://api.affixapi.com/2023-03-01/xhr/employees'
压缩
我们支持 brotli
、gzip
和 deflate
压缩算法。
要启用,请传递 Accept-Encoding
标头,其中包含一个或所有以下值:br
、gzip
、deflate
或 identity
(不压缩)
在响应中,您将收到一个 Content-Encoding
响应标头,该标头指示在数据负载中使用的数据压缩算法,以便您可以对结果进行解压缩。如果传递了 Accept-Encoding: identity
标头,则不会发送 Content-Encoding
响应标头,因为没有使用压缩算法。
Webhooks
对于人力资源/薪酬模式,Webhooks 是一个令人兴奋的功能。
如果启用,您的 webhook_uri
将在相应环境(dev | prod
)的 client_id
上设置
Webhooks 配置为每小时向底层集成发送一次实时请求,如果在最后一次请求之后检测到差异,我们将向您的 webhook_uri
发送此形状的请求
{
added: <api.v20230301.Employees>[
<api.v20230301.Employee>{
...,
date_of_birth: '2010-08-06',
display_full_name: 'Daija Rogahn',
employee_number: '57993',
employment_status: 'pending',
employment_type: 'other',
employments: [
{
currency: 'eur',
effective_date: '2022-02-25',
employment_type: 'other',
job_title: 'Dynamic Implementation Manager',
pay_frequency: 'semimonthly',
pay_period: 'YEAR',
pay_rate: 96000,
},
],
first_name: 'Daija',
...
}
],
removed: [],
updated: [
<api.v20230301.Employee>{
...,
date_of_birth: '2009-11-09',
display_full_name: 'Lourdes Stiedemann',
employee_number: '63189',
employment_status: 'leave',
employment_type: 'full_time',
employments: [
{
currency: 'gbp',
effective_date: '2023-01-16',
employment_type: 'full_time',
job_title: 'Forward Brand Planner',
pay_frequency: 'semimonthly',
pay_period: 'YEAR',
pay_rate: 86000,
},
],
first_name: 'Lourdes',
}
]
}
以下标头将与 Webhooks 请求一起发送
x-affix-api-signature: ab8474e609db95d5df3adc39ea3add7a7544bd215c5c520a30a650ae93a2fba7
x-affix-api-origin: webhooks-employees-webhook
user-agent: affixapi.com
在信任负载之前,您应该对负载进行签名并验证签名是否与 affixapi.com
服务发送的签名匹配。
这确保了发送到您的 webhook_uri
的数据来自 affixapi.com
服务器。
签名是通过将签名密钥(您的 client_secret
)与使用标准 HMAC-SHA256 密钥散列发送的请求体组合来创建的。
签名可以通过以下方式创建
- 使用您的
client_secret
创建一个HMAC
- 使用负载更新
HMAC
- 获取十六进制摘要 -> 这就是签名
遵循此方案的示例 typescript
代码
import { createHmac } from 'crypto';
export const computeSignature = ({
str,
signingSecret,
}: {
signingSecret: string;
str: string;
}): string => {
const hmac = createHmac('sha256', signingSecret);
hmac.update(str);
const signature = hmac.digest('hex');
return signature;
};
尽管验证 Affix API 签名标头应该是您确认有效性的主要方法,但您也可以将我们的出站 Webhooks 静态 IP 地址列入白名单。
dev:
- 52.210.169.82
- 52.210.38.77
- 3.248.135.204
prod:
- 52.51.160.102
- 54.220.83.244
- 3.254.213.171
速率限制
公开端点(不受 API 密钥的限制)(在端点级别应用)
- 每分钟 15 个请求(按 IP 地址计)
- 每 5 分钟 25 个请求(按 IP 地址计)
门控端点(需要API密钥)(在端点级别应用)
- 每分钟40个请求
- 每5分钟40个请求(通过
client_id
)
注意事项
- 开放的端点(不由API密钥门控)可能由您的用户调用,而不是您自己调用,因此通常不会对您应用速率限制。
- 作为开发者,速率限制应用于端点粒度。
- 例如,以下速率限制是每分钟10个IP请求。从同一IP地址,在1分钟内,您可以得到:
- 每分钟10个请求在
/orders
上, - 另外每分钟10个请求在
/items
上, - 还有另外每分钟10个请求在
/identity
上, - 总共每分钟30个请求。
- 每分钟10个请求在
- 例如,以下速率限制是每分钟10个IP请求。从同一IP地址,在1分钟内,您可以得到:
安装与使用
需求
PHP 7.2及更高版本。
Composer
要通过Composer安装绑定,请将以下内容添加到composer.json
中:
{ "repositories": [ { "type": "vcs", "url": "https://github.com/GIT_USER_ID/GIT_REPO_ID.git" } ], "require": { "GIT_USER_ID/GIT_REPO_ID": "*@dev" } }
然后运行composer install
手动安装
下载文件并包含autoload.php
<?php require_once('/path/to/OpenAPIClient-php/vendor/autoload.php');
入门指南
请遵循安装程序,然后运行以下命令:
<?php require_once(__DIR__ . '/vendor/autoload.php'); // Configure API key authorization: access-token $config = OpenAPI\Client\Configuration::getDefaultConfiguration()->setApiKey('Authorization', 'YOUR_API_KEY'); // Uncomment below to setup prefix (e.g. Bearer) for API key, if needed // $config = OpenAPI\Client\Configuration::getDefaultConfiguration()->setApiKeyPrefix('Authorization', 'Bearer'); $apiInstance = new OpenAPI\Client\Api\Class20230301Api( // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`. // This is optional, `GuzzleHttp\Client` will be used as default. new GuzzleHttp\Client(), $config ); try { $result = $apiInstance->xhrCompanies20230301(); print_r($result); } catch (Exception $e) { echo 'Exception when calling Class20230301Api->xhrCompanies20230301: ', $e->getMessage(), PHP_EOL; }
API端点
所有URI都是相对于https://api.affixapi.com
模型
- AddressNoNonNullRequest
- AddressResponse
- ClientRequest
- ClientResponse
- CompanyResponse
- CompensationHistoryNoNonNullRequest
- CompensationHistoryResponse
- CreateEmployeeRequest
- CreateEmployeeRequestBankAccount
- CreateEmployeeRequestDependents
- CreateEmployeeRequestEmergencyContacts
- CreateEmployeeRequestManager
- CurrencyNotNullRequest
- CurrencyNotNullResponse
- CurrencyResponse
- DisconnectResponse
- EmployeeResponse
- EmployeeResponseManager
- EmploymentHistoryNoNonNullRequest
- EmploymentHistoryResponse
- EmploymentStatusNotNullNotNullable
- EmploymentStatusNotNullRequest
- EmploymentStatusResponse
- GroupNoNullEnumRequest
- GroupResponse
- IdAndMessageResponse
- IdentityResponse
- InlineResponse400
- InlineResponse401
- InlineResponse409
- IntrospectResponse
- LocationNoNonNullRequest
- LocationResponse
- MessageResponse
- ModeRequest
- ModeResponse
- PayrunResponse
- PayrunTypeResponse
- PayslipResponse
- PayslipResponseContributions
- PayslipResponseDeductions
- PayslipResponseEarnings
- PayslipResponseReimbursements
- PayslipResponseTaxes
- PolicyTypeResponse
- ProviderRequest
- ProviderResponse
- ScopesRequest
- ScopesResponse
- TimeOffBalanceResponse
- TimeOffEntryResponse
- TimesheetResponse
- TokenRequest
- TokenResponse
授权
access-token
- 类型: API密钥
- API密钥参数名: Authorization
- 位置: HTTP头
basic
- 类型: API密钥
- API密钥参数名: Authorization
- 位置: HTTP头
测试
要运行测试,请使用
composer install vendor/bin/phpunit
作者
关于此包
此PHP包由OpenAPI Generator项目自动生成
- API版本:
2023-03-01
- 包版本:
1.1.94
- 包版本:
- 构建包:
org.openapitools.codegen.languages.PhpClientCodegen