php可通过invoice ninja v5的get /api/v1/clients读取客户列表,使用x-api-token传递账户生成的api令牌,并按接口要求发送x-requested-with: xmlhttprequest。列表默认每页20条,可用page和per_page翻页。以下示例只读取第一页,不创建、修改或删除客户,适用于已开通api权限并提供https入口的托管或自托管账户。
生成令牌并设置自己的API根地址
在Settings → Account Management → Integrations → API tokens管理令牌,按实际账户权限使用。自托管填写自己的服务域名,托管账户按其实际服务入口填写,不把文档演示站当生产账户。将两个值放入运行环境,避免把令牌写进网页、版本库或错误日志。

官方客户接口的两个必需请求头
发送GET并先检查传输和HTTP状态
准备PHP cURL扩展,将下面保存为list-clients.php。INVOICE_NINJA_BASE_URL使用完整HTTPS站点根地址,INVOICE_NINJA_TOKEN为自己的令牌;示例不关闭证书验证,也不自动跟随重定向把令牌发送到其他地址。
<?php $base = rtrim(getenv('INVOICE_NINJA_BASE_URL') ?: '', '/');
$token = getenv('INVOICE_NINJA_TOKEN') ?: '';
if (parse_url($base, PHP_URL_SCHEME) !== 'https' || $token === '') {
throw new RuntimeException('请设置HTTPS根地址和API令牌');
}
$query = http_build_query(['page' => 1, 'per_page' => 20]);
$ch = curl_init($base . '/api/v1/clients?' . $query);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [
'Accept: application/json',
'X-API-TOKEN: ' . $token,
'X-Requested-With: XMLHttpRequest',
],
]);
$raw = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error = curl_error($ch);
curl_close($ch);
if ($raw === false) {
throw new RuntimeException('网络请求失败:' . $error);
}
if ($status !== 200) {
throw new RuntimeException('API返回HTTP ' . $status);
}
$data = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if (!isset($data['data']) || !is_array($data['data'])) {
throw new RuntimeException('响应未包含预期的data数组');
}
echo '本页客户数:' . count($data['data']) . PHP_EOL;
分页、筛选和异常各自处理

客户列表的分页参数
验证第一页返回data数组后,再根据自己的同步需求改变page。官方支持per_page与page组合,例如每页15条的第2页;不要把第一次拿到的20条当全部客户。若使用响应meta中的分页信息,应先核对实际结构和最后一页,再控制循环,避免无止境请求。
使用官方Model Context Protocol PHP SDK将PHP应用程序功能暴露为MCP工具、资源和提示,用于代理工作流。
客户接口支持name、balance和sort等过滤;排序参数按官方参数说明使用column|asc或column|desc。参数值用http_build_query编码,不拼接未转义输入。401优先检查令牌,403检查账户授权,422检查参数,429按限流策略退避,5xx保留错误并稍后处理。不要输出完整响应来调试,以免客户联系方式进入公开日志。
php免费学习视频:立即使用
踏上前端学习之旅,开启通往精通之路!从前端基础到项目实战,循序渐进,一步一个脚印,迈向巅峰!










