README

Laravel InvoiceXpress API

Laravel 包，用于与 InvoiceXpress API 交互

已测试与 Laravel 5.5 一起使用。*

目录

• 1 - 安装
  • 1.1 - 发布配置
  • 1.2 - 迁移
• 2 - 配置
• 3 - 使用
  • 3.1 - Eloquent 模型
  • 3.1.1 - 与 Laravel::Auth() 的一对一关系
  • 3.2 - 与 API 交互
• 4 - 测试
• 5 - 消息
  • 5.1 - 错误消息
  • 5.2 - 成功消息

1 - 安装

通过 Composer

$ composer require rpsimao/invoicexpress-api

在你的 config/app.php 中，注册 Providers 和 Facade（对于 Laravel 5.5 及以上版本不需要）

'providers' => [
....

rpsimao\InvoiceXpressAPI\InvoiceXpressAPIServiceProvider::class,

.....

'aliases' => [

.....

'InvoiceXpressClients' =>  rpsimao\InvoiceXpressAPI\InvoiceXpressAPIFacade::class,

.....

1.1 - 发布配置

$ php artisan vendor:publish --tag=ivxapi-config

在配置文件中，所有 API 端点都可以访问，例如，你需要生成一个发票 PDF

config(invoicexpress.enpoints.invoice.generate_pdf);

所有端点都是通用的，如：'api/pdf/{invoice-id}.xml'，因此有一个帮助函数可以将通用端点替换为实际值

endpoint_replace(['the-real-value'], config(invoicexpress.enpoints.invoice.generate_pdf));

第一个参数必须是数组，并且要替换的项目数必须与端点中要替换的项目数匹配。如果不匹配，将抛出异常并引发致命错误。

1.2 - 迁移

$ php artisan vendor:publish --tag=ivxapi-migrations
$ php artisan migrate

2 - 配置

将你的 API 密钥和账户名称添加到 .env 文件中

INVOICEXPRESS_API_KEY=
INVOICEXPRESS_ACCOUNT_NAME=

这些将由配置文件读取

....

'api_key'      => env('INVOICEXPRESS_API_KEY'),
'account_name' => env('INVOICEXPRESS_ACCOUNT_NAME'),

....

如果你不想在 .env 文件中放置你的 API 密钥，或者更愿意在每次请求时获取它，你可以调用 getAPIKey() 方法。这样你就可以频繁地更改账户中的 API 密钥，而无需更新应用程序。

在配置文件 invoicexpress 中，有两个空字段 ['username', 'password']，因此你可以将用户名/密码放在那里，如果你愿意的话。

$client = new InvoiceXpressAPI();
$api_key = $client->getAPIKey('my-username', 'my-password');
....
//later in the query
....
$client->setQuery(['api_key' => $api_key]);
....

3 - 使用

请参阅文档以获取操作的参数。

请参阅： https://invoicexpress.com/api/overview

有两个类用于处理 API

3.1 - Eloquent 模型

它有一个自定义函数，用于检索所有客户并将它们放入数据库中。

你可以为定期检索它们设置 cron 作业。

//Accepts a flag (true or false[default])
InvoiceXpressClients::getAllClientsFromAPI(true);

如果传递 true 标志，函数将客户插入到数据库中。False 或无，返回包含所有客户的数组。

如果客户已存在，则更新值。

3.1.1 - 与 Laravel::Auth() 的一对一关系

如果您希望在 InvoiceXpress 和您的应用程序用户之间建立关系，请执行以下操作

$ php artisan vendor:publish --tag=ivxapi-migrateauth
$ php artisan migrate

在您的 Users 模型中添加以下方法

class User extends Model
{
.......

//Get the InvoiceXpress Client record associated with the user.

public function invoicexpress()
{
	return $this->hasOne('InvoiceXpressClients');
}

现在您有一个一对一关系。现在您只需将 user_id 插入到 InvoiceXpress 表中。

3.2 - 与 API 交互

use rpsimao\InvoiceXpressAPI\Service\InvoiceXpressAPI;

//Making a GET REQUEST

$client = new InvoiceXpressAPI();
$client->setMethod('GET');
$client->setUrl(config('invoicexpress.my_url'));
$client->setEndpoint(config('invoicexpress.endpoints.clients.list_all'));
$client->setQuery(['api_key' => config('invoicexpress.api_key')]);

$response = $client->talkToAPI();

.....



// Another GET Request to generate a PDF for an invoice

$client = new InvoiceXpressAPI();
$client->setMethod('get');
$client->setUrl(config('invoicexpress.my_url'));
$client->setEndpoint(
    endpoint_replace(['12759480'], config('invoicexpress.endpoints.invoices.generate_pdf'))
);
$client->setQuery([
        'api_key' => config('invoicexpress.api_key'),
        'invoice-id' => '12759480',
        'second_copy' => true
    ]);
$response = $client->talkToAPI();



//Making a POST REQUEST
// Creating a new Client

client = new InvoiceXpressAPI();
$client->setMethod('post');
$client->setUrl(config('invoicexpress.my_url'));
$client->setEndpoint( config('invoicexpress.endpoints.clients.create'));
$client->setQuery([
        'api_key' => config('invoicexpress.api_key'),
        'client' => [
        	'name' => 'My name',
        	'code' => 'My Client Code',
        	'email' => 'client@email.com'
        	//.... insert more values ....
        ]
    ]);
$response = $client->talkToAPI();


//Do whatever you need with the response

//Making a PUT REQUEST

$client = new InvoiceXpressAPI();
$client->setMethod('put');
$client->setUrl(config('invoicexpress.my_url'));
$client->setEndpoint(endpoint_replace(['123456789'], config('invoicexpress.endpoints.clients.update')));
$client->setQuery([
	'api_key' => config('invoicexpress.api_key'),
	'client-id' => '123456789',
	'client' => [
		'name' => 'My awesome Client',
		'code' => '123',
		'phone' =>  999888777
		//.... insert more values ....
		]
	]);
$response = $client->talkToAPI();


//Do whatever you need with the response

4 - 测试

目前有 4 个测试可用。

1. 一个获取所有客户的 GET 请求
2. 一个更新客户信息的 PUT 请求
3. 一个获取您的 API 密钥的 GET 请求
4. 一个生成发票 PDF 的 GET 请求

为了使它们正常工作，您必须用自己的凭据/数据填充

class GetTest extends TestCase {

// Use your own credentials|data to run the tests

	protected $url          = '';
	protected $api_key      = '';
	protected $username     = '';
	protected $password     = '';
	protected $client_id    = '';
	protected $client_name  = '';
	protected $client_code  = '';
	protected $client_phone = '';
	protected $invoice      = '';

.......

然后您可以运行测试

$ cd your-laravel-project-folder
$ vendor/bin/phpunit vendor/rpsimao/invoicexpress-api

如果一切顺利，您应该会收到

OK (4 tests, 4 assertions)

5 - 消息

默认情况下，所有错误/成功消息都以 XML 格式返回。如果您想更改为 JSON，只需添加 setMsgFormat() 方法并传递 JSON 标志

.....
$client = new InvoiceXpressAPI();
$client->setMsgFormat('json');
......

5.1 - 错误消息

api_code 和 api_msg 是 InvoiceXpress API 返回的实际消息，其他只是用于调试。

调试标签仅在 .env 文件中的 APP_DEBUG=true 时出现

这是错误消息的返回方式

XML

<?xml version="1.0"?>
<response>
	<api_code>500</api_code>
	<api_msg>Server error: `GET https://mycompany.app.invoicexpress.com/api/pdf/1234567.xml?api_key=11111abc2222def33333&amp;invoice-id=1234567` resulted in a `500 Internal Server Error` response: An error occured on the server. We have been notified.</api_msg>
	<file>/Code/testapi/vendor/rpsimao/invoicexpress-api/src/Service/InvoiceXpressAPI.php</file>
	<line>408</line>
	<message>simplexml_load_string(): Entity: line 1: parser error : Start tag expected, '&amp;lt;' not found</message>
</response>

JSON

{
"api_code":"500",
"api_msg":"Server error: `GET https:\/\/mycompany.app.invoicexpress.com\/api\/pdf\/1234567.xml?api_key=11111abc2222def33333&invoice-id=1234567` resulted in a `500 Internal Server Error` response:\nAn error occured on the server. We have been notified.\n\n",
"file":"\/Code\/testapi\/vendor\/rpsimao\/invoicexpress-api\/src\/Service\/InvoiceXpressAPI.php",
"line":385,
"message":"simplexml_load_string(): Entity: line 1: parser error : Start tag expected, '<' not found"
} 

5.2 - 成功消息

这是成功消息的返回方式

XML

<?xml version="1.0"?>
<response>
	<api_code>200</api_code>
	<api_msg>OK</api_msg>
	<api_values><pdfUrl>https://invoicexpress-downloads.s3.amazonaws.com/store_00000_Factura-0000-a.pdf?AWSAccessKeyId=AAKKAAKKK&amp;Expires=1501762080&amp;Signature=vmePXICWhUBRLygwVO6y2Lx6x4M%3D&amp;response-content-disposition=attachment%3B%20filename%3DFactura-0000-a.pdf&amp;response-content-type=application%2Fpdf</pdfUrl></api_values>
</response>

JSON

{
  "response": {
    "api_code": "200",
    "api_msg": "OK",
    "api_values": { "pdfUrl": "https://invoicexpress-downloads.s3.amazonaws.com/store_00000_Factura-0000-a.pdf?AWSAccessKeyId= AAKKAAKKK&Expires=1501762080&Signature=vmePXICWhUBRLygwVO6y2Lx6x4M%3D&response-content-disposition=attachment%3B%20filename%3DFactura-0000-a.pdf&response-content-type=application%2Fpdf" }
  }
}