README

Moneybird API 的 PHP 客户端。此客户端允许您与 Moneybird 集成，例如通过

• 创建并发送发票
• 创建和更新联系人
• 上传采购发票
• 创建手动会计分录

此库由 Picqer 创建和维护。我们正在寻找加入我们团队的 PHP 开发者！

安装

此项目可以通过 Composer 轻松安装。

composer require picqer/moneybird-php-client

使用方法

您需要准备以下凭据和信息。您可以从 Moneybird 账户中获取这些信息。

• 客户端 ID
• 客户端密钥
• 回调 URL

您需要能够本地存储一些数据

• 上述三个凭据
• 授权码
• 访问令牌

授权码

如果您还没有授权码，您需要先获取此信息。客户端支持以下方式获取授权码。

<?php

require __DIR__ . '/vendor/autoload.php';

$connection = new \Picqer\Financials\Moneybird\Connection();
$connection->setRedirectUrl('REDIRECTURL');
$connection->setClientId('CLIENTID');
$connection->setClientSecret('CLIENTSECRET');
$connection->redirectForAuthorization();

这将执行重定向到 Moneybird，您可以在那里登录并授权应用程序。登录后，Moneybird 将将您重定向到回调 URL，带有请求参数 "code"，您应将其保存为授权码。

设置管理 ID

大多数方法都需要您设置管理 ID 以获取正确数据。您可以从 MoneyBird 的 URL 获取管理 ID，但您也可以在连接后运行以下方法来列出用户可访问的管理。以下代码示例展示了如何从以下调用结果中设置第一个管理

$administrations = $moneybird->administration()->getAll();

常规操作

在您获得上述授权码后，您可以执行常规请求。客户端将自动处理访问令牌。

<?php

require __DIR__ . '/vendor/autoload.php';

$connection = new \Picqer\Financials\Moneybird\Connection();
$connection->setRedirectUrl('REDIRECTURL');
$connection->setClientId('CLIENTID');
$connection->setClientSecret('CLIENTSECRET');

// Get authorization code as described in readme (always set this when available)
$connection->setAuthorizationCode('AUTHORIZATIONCODE');

// Set this in case you got the access token, otherwise client will fetch it (always set this when available)
$connection->setAccessToken('ACCESSTOKEN');

try {
    $connection->connect();
} catch (\Exception $e) {
    throw new Exception('Could not connect to Moneybird: ' . $e->getMessage());
}

// After connection save the last access token for reuse 
$connection->getAccessToken(); // will return the access token you need to save

// Set up a new Moneybird instance and inject the connection
$moneybird = new \Picqer\Financials\Moneybird\Moneybird($connection);

// Example: Get administrations and set the first result as active administration
$administrations = $moneybird->administration()->getAll();
$connection->setAdministrationId($administrations[0]->id);

// Example: Fetch list of salesinvoices 
$salesInvoices = $moneybird->salesInvoice()->get();
var_dump($salesInvoices); // Array with SalesInvoice objects

// Example: Fetch a sales invoice
$salesInvoice = $moneybird->salesInvoice()->find(3498576378625);
var_dump($salesInvoice); // SalesInvoice object

// Example: Get sales invoice PDF contents
$pdfContents = $salesInvoice->download();

// Example: Create credit invoice based on existing invoice
$creditInvoice = $salesInvoice->duplicateToCreditInvoice();
var_dump($creditInvoice); // SalesInvoice object

// Example: Create a new contact
$contact = $moneybird->contact();

$contact->company_name = 'Picqer';
$contact->firstname = 'Stephan';
$contact->lastname = 'Groen';
$contact->save();
var_dump($contact); // Contact object (as saved in Moneybird)

// Example: Update existing contact, change email address
$contact = $moneybird->contact()->find(89672345789233);
$contact->email = 'example@example.org';
$contact->save();
var_dump($contact); // Contact object (as saved in Moneybird)

// Example: Use the Moneybird synchronisation API
$contactVersions = $moneybird->contact()->listVersions();
var_dump($contactVersions); // Array with ids and versions to compare to your own

// Example: Use the Moneybird synchronisation API to get new versions of specific ids
$contacts = $moneybird->contact()->getVersions([
  2389475623478568,
  2384563478959922
]);
var_dump($contacts); // Array with two Contact objects

// Example: List sales invoices that are in draft (max 100)
$salesInvoices = $moneybird->salesInvoice()->filter([
  'state' => 'draft'
]);
var_dump($salesInvoices); // Array with filtered SalesInvoice objects

// Example: Get import mappings for contacts
$mappings = $moneybird->importMapping()->setType('contact')->get();
var_dump($mappings); // Array with ImportMapping objects

// Example: Register a payment for a sales invoice
$salesInvoicePayment = $moneybird->salesInvoicePayment();
$salesInvoicePayment->price = 153.75;
$salesInvoicePayment->payment_date = '2015-12-03';

$salesInvoice = $moneybird->salesInvoice()->find(3498576378625);
$salesInvoice->registerPayment($salesInvoicePayment);

// How to add SalesInvoiceDetails (invoice lines) to a SalesInvoice
$salesInvoiceDetailsArray = [];

foreach ($invoiceLines as $invoiceLine) { // Your invoice lines
   $salesInvoiceDetail = $moneybird->salesInvoiceDetail();
   $salesInvoiceDetail->price = 34.33;
   ...

   $salesInvoiceDetailsArray[] = $salesInvoiceDetail;
}

$salesInvoice = $moneybird->salesInvoice();
$salesInvoice->details = $salesInvoiceDetailsArray;

代码示例

例如：请参阅 example/example.php

待办事项

• 接收 Webhooks 支持（将会很棒）
• 一些关联/嵌套实体（例如注释、附件等）
• 针对 RateLimit 超额和返回 Retry-After 值的专用异常