mailercheck/quaderno

Quaderno REST API 的 PHP 封装

维护者

详细信息

github.com/mailercheck/quaderno-php

主页

源代码

安装次数: 3,120

依赖者: 0

建议者: 0

安全: 0

星标: 0

关注者: 0

分支: 12

3.0.2 2022-05-24 09:49 UTC

Requires

  • php: >=5.2.0
  • ext-curl: *

MIT 9808ac0d20bde680d1568d1fee36ba8dbeafcf21

vattaxbillinginvoicesgstreceiptssales taxtax calculationcredit notes

This package is not auto-updated.

Last update: 2024-09-25 19:26:22 UTC

README

此库是一个 PHP 封装库，用于以更优雅的方式连接和处理 Quaderno API。它与您的 PHP 应用程序连接，因此您需要有效的 Quaderno 账户才能使用它。

您可以使用我们的 沙盒环境 在上线前测试您的流程。

为什么使用它？

如果您想从您的 PHP 应用程序连接到 Quaderno API 而无需处理令人烦恼的低级 HTTP 请求和 JSON 编码的数据，则需要此工具。

要求

  • PHP 5 或更高版本
  • cURL（最近 PHP 版本默认包含）

安装

通过 Composer 安装，或者只需将所有文件复制到项目中的单个文件夹。

使用方法

在使用封装库时，需要记住的一个经验法则是，API 调用实际上仅使用以下方法：'find()', 'save()', 'delete()', 'deliver()' 和 'ping()'。

加载

require_once 'quaderno_load.php';

设置

QuadernoBase::init('YOUR_API_KEY', 'YOUR_API_URL', API_VERSION); // API_VERSION is optional as it defaults to the account API version

测试连接

QuadernoBase::ping();   // returns true (success) or false (error)

分页

⚠️ 当前版本的 PHP 封装库存在一个已知限制，不允许轻松检查响应头，例如用于从版本 20210316（X-Pages-NextPage 和 X-Pages-HasMore）进行分页的头部。目前，您可以通过使用更小的数据范围和更高的 limit 来获取更多文档（最多 100）来解决这个问题；或者，用任何查询获取第一次 find 数据，然后使用 created_before 参数和最后一个返回文档的 ID 进行另一个分页请求，直到响应为空。

// Simple example to request all pages from the given dates until all invoices have been returned:
$invoices = [];
$filters['limit'] = '50'; // bunches of 50 invoices per request
$filters['date']= "$from,$to"; // please use dates to avoid always getting all invoices
do {
  $data = QuadernoInvoice::find($filters);
  if (is_array($data) && !empty($data)) {
    $invoices = array_merge($invoices, $data);
    $last_invoice = end($data); // advances array's internal pointer to the last element, and returns its value
    $filters['created_before'] = $last_invoice->id; // paginate from there
  }
} while (!empty($data));

税费

Quaderno 允许您计算税率并验证税务识别号。

计算税费

查看我们的 API 文档 了解所有有效参数。

$params = array(
  'to_country' => 'ES',
  'to_postal_code' => '08080'
);

$tax = QuadernoTaxRate::calculate($params);   // returns a QuadernoTax
$tax->name;  // 'IVA'
$tax->rate;  // 21.0


// A non-processable request (due to invalid data, outages, etc.) returns false boolean
QuadernoBase::init('fakeApiKey', 'https://fake-subdomain.quadernoapp.com/api/');

$tax = QuadernoTaxRate::calculate($params);
$tax // false

// Example using a callback to get the specific error response
$tax = QuadernoTaxRate::calculate($params, function($apiErrorResponse) use (&$errorResponse) {
  $errorResponse = $apiErrorResponse;
});

$tax; // false
$errorResponse['http_code']; // 401
$errorResponse['data']['error']; // "Wrong API key or the user does not exist."

验证税务识别号

查看我们的 API 文档 了解支持的税务管辖区域。

$params = array(
  'country' => 'ES',
  'tax_id' => 'ESA58818501'
);

QuadernoTaxId::validate($params);   // returns boolean (true or false)

联系人

联系人是指出现在您的发票、贷项通知和费用中的任何客户或供应商。

查找联系人

如果请求失败，则返回 false。

$contacts = QuadernoContact::find();                              // returns an array of QuadernoContact
$contacts = QuadernoContact::find(array('created_before' => 2));  // returns an array of QuadernoContact
$contact = QuadernoContact::find('ID_TO_FIND');                   // returns a QuadernoContact

创建和更新联系人

$params = array('first_name' => 'Joseph',
                'last_name' => 'Tribbiani',
                'email' => 'joseph@friends.com',
                'contact_name' => 'Joey');
$contact = new QuadernoContact($params);
$contact->save(); // returns true (success) or false (error)

$contact->first_name = '';
$contact->save(); // returns false - first_name is a required field

// print errors
foreach($contact->errors as $field => $errors) {
  print "{$field}: ";
  foreach ($errors as $e) print $e;
}

$contact->first_name = 'Joey';
$contact->save();

通过支付处理器 ID 检索联系人

$gateway = 'stripe';
$customer_id = 'cus_Av4LiDPayM3nt_ID';

$contact = QuadernoContact::retrieve($id, $gateway);  // returns a QuadernoContact (success) or false (error)

产品

产品是指您向客户销售的商品或服务。

查找产品

如果请求失败，则返回 false。

$items = QuadernoProduct::find();              // returns an array of QuadernoProduct
$items = QuadernoProduct::find('ID_TO_FIND');  // returns a QuadernoProduct

创建和更新产品

$params = array('name' => 'Jelly pizza',
                'code' => 'Yummy',
                'unit_cost' => '15.00');
$item = new QuadernoProduct($params);
$item->save();  // returns true (success) or false (error)

$item->name = '';
$item->save();  // returns false - name is a required field

foreach($item->errors as $field => $errors) {
  print "{$field}: ";
  foreach ($errors as $e) print $e;
}

$item->name = 'Jelly Pizza';
$item->save();

交易

创建一个交易对象，以便轻松地从您的应用程序向 Quaderno 发送销售和退款。我们将使用它们来开具发票和贷项通知，以及自动更新税务报告。

创建交易

$params = array(
  'type' => 'sale',
  'customer' => array(
    'id' => $contact->id
  ),
  'date' => date('Y-m-d'),
  'currency' => 'EUR',
  'processor' => 'YOUR_APP_NAME',
  'processor_id' => 'TRANSACTION_ID_IN_YOUR_APP',
  'payment' => array(
    'method' => 'credit_card',
    'processor' => 'stripe',
    'processor_id' => 'ch_1IMFwhB2xq6voISLLk4I1KeE'
  ),
  'notes' => 'With mobile version'
);

$transaction = new QuadernoTransaction($params);

$items = array();
array_push( $items, array('description' => 'Pizza bagles', 'quantity' => 10, 'amount' => 99.90));
$transaction->items = $items;

$transaction->save(); // returns true (success) or false (error)

账单文件

账单文件可以是 发票、费用、贷项 或 预估。

查找文件

$invoices = QuadernoInvoice::find();                              // returns an array of QuadernoInvoice
$invoices = QuadernoInvoice::find(array('created_before' => 2));  // returns an array of QuadernoInvoice
$invoice = QuadernoInvoice::find('ID_TO_FIND');                   // returns a QuadernoInvoice

注意：为了查找编号、联系人名称或 P.O. 编号字段，必须在 params 数组中设置 'q' 参数。

$invoices = QuadernoInvoice::find(array('q' => '0001')); // search filtering

通过支付处理器 ID 检索文件

$gateway = 'stripe';
$payment_id = 'ch_Av4LiDPayM3nt_ID';
$refund_id = 'ch_Av4LiDR3fuNd_ID';

$invoice = QuadernoInvoice::retrieve($payment_id, $gateway); // returns a QuadernoInvoice (success) or false (error)
$credit_note = QuadernoCredit::retrieve($refund_id, $gateway); // returns a QuadernoCredit (success) or false (error)

创建和更新文件

$params = array('currency' => 'EUR',
                'notes' => 'With mobile version');

$estimate = new QuadernoEstimate($params);
$estimate->addContact($contact);

$item = new QuadernoDocumentItem(array('description' => 'Pizza bagles', 'unit_price' => 9.99, 'quantity' => 20));
$estimate->addItem($item);

$estimate->save();  // returns true (success) or false (error)

$estimate->notes = 'Finally, no mobile version will be necessary';
$estimate->save();

发送文件

仅在发票、贷项通知和估计中可行。联系信息必须包含一个电子邮件地址。

$invoice->deliver();  // returns true (success) or false (error)

付款

在Quaderno-lingo中的付款表示成功付款的记录。

向文档添加付款

您只能向发票和费用添加付款。输入应为QuadernoPayment对象。

$payment = new QuadernoPayment(array('date' => date('Y-m-d'), 'payment_method' => 'credit_card'));
$invoice->addPayment($payment);   // returns true (success) or false (error)
$invoice->save();                 // returns true (success) or false (error)

获取付款

$payments = $invoice->getPayments();  // returns an array of QuadernoPayment

删除付款

$invoice->removePayment($payments[2]);  // returns true (success) or false (error)

证据

位置证据是客户位置的证明，应存储以符合某些税务管辖区的税法规定（例如欧盟增值税）。

创建位置证据

$evidence = new QuadernoEvidence(array('document_id' => $invoice->id, 'billing_country' => $contact->country, 'ip_address' => '127.0.0.1', 'bank_country' => 'ES'));
$evidence->save();  // returns true (success) or false (error)

Webhooks

Webhooks指的是一组元素，它们共同创建了一个更大集成中的通知和反应系统。

查找webhooks

如果请求失败，则返回 false。

$sessions = QuadernoCheckoutSession::find();                    // returns an array of QuadernoCheckoutSession
$sessions = QuadernoCheckoutSession::find('ID_TO_FIND');          // returns a QuadernoCheckoutSession

会话

Checkout会话代表客户通过Quaderno Checkout进行一次性购买或订阅时的会话。

创建和更新Checkout会话

$params = array('cancel_url' => 'http://myapp.com/back',
                'success_url' => 'http://myapp.com/thank-you',
                'items' => array(array('product' => 'prod_123456'));

$session = new QuadernoCheckoutSession($params);
$session->save();              // returns true (success) or false (error)

$session->success_url = '';
$session->save();              // returns false - url is a required field

foreach($session->errors as $field => $errors) {
  print "{$field}: ";
  foreach ($errors as $e) print $e;
}

$session->success_url = 'http://mapp.com/thank-you?product=xxxxx';
$session->save();

更多信息

请注意，这只是一个原始API的PHP包装器。如果您想了解有关API本身的更多信息，请访问原始的API文档。

许可证

(MIT许可证)

版权所有 © 2013-2021 Quaderno

在此特此授予任何人无代价获得此软件及其相关文档副本（以下简称“软件”）的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本，并允许将软件提供给获得软件的人，但受以下条件约束

上述版权声明和本许可声明应包含在所有副本或软件的大量部分中。

软件按“原样”提供，不提供任何形式的保证，无论是明示的、暗示的还是其他的，包括但不限于适销性、特定用途的适用性和非侵权性保证。在任何情况下，作者或版权所有者不对任何索赔、损害或其他责任负责，无论是因为合同、侵权或其他方式引起的，无论是在软件或其使用或其他交易中产生的。