README

安装

添加 Invoice Ninja SDK

composer require invoiceninja/sdk-php

设置

use InvoiceNinja\Sdk\InvoiceNinja;
   
$ninja = new InvoiceNinja("your_token");
$invoices = $ninja->invoices->all();

• 要连接到自托管的版本，请在 $ninja 对象上使用 ->setUrl()。

支持

• 客户
• 发票
• 报价
• 产品
• 付款
• 税率
• 统计
• 费用
• 费用类别
• 周期性发票
• 信贷
• 项目
• 任务
• 供应商
• 公司
• 订阅
• 采购订单
• 银行集成
• 银行交易

检索模型

检索所有客户

    $clients = $ninja->clients->all();

您可以在 ->all() 方法上执行复杂筛选。

查询参数可以链接在一起形成复杂查询。当前支持的值包括

per_page：每页返回的客户数
page：页码
include：要包含的关联关系的逗号分隔列表，例如 contacts,documents,gateway_tokens
balance：返回具有余额的客户的查询，使用运算符和值

• 例如 ?balance=lt:10 返回余额小于10的客户
• 支持的运算符：lt, lte, gt, gte, eq

between_balance：返回余额在两个值之间的客户

• 例如 ?between_balance=10:20 - 返回余额在10和20之间的客户

email：返回 contacts.email 字段等于电子邮件的客户
id_number：按 id_number 搜索
number：按编号搜索
filter：跨多个列（名称、id_number、first_name、last_name、email、custom_value1、custom_value2、custom_value3、custom_value4）搜索
created_at：按创建时间（Unix时间戳）搜索
is_deleted：使用 is_deleted 布尔标志进行搜索

例如，

$clients = $ninja->clients->all([
    'balance' => 'lt:10', // get all clients with a balance less than 10
    'per_page' => 10, // return 10 results per page
    'page' => 2, // paginate to page 2
    'include' => 'documents', // include the documents relationship
]);

通过主键检索客户。

    $client = $ninja->clients->get("CLIENT_HASHED_ID");

通过编号检索发票

    $client = $ninja->invoices->all(['number' => '0001']);

插入和更新模型

创建新客户

    $client = $ninja->clients->create(['name' => 'A new client']);

创建带有联系人的新客户

    $clients = $ninja->clients->create([
        'name' => 'Brand spanking new client',
        'contacts' => [
            [
                'first_name' => 'first',
                'last_name' => 'last',
                'send_email' => true,
                'email' => 'gi-joe@example.com',
            ],

        ]
    ]);
    

更新现有客户

    $client = $ninja->clients->update("CLIENT_HASHED_ID",['name' => 'A client with a updated name']);

请注意

在更新客户时，必须始终包括当前的联系人数组（array），如果不包含联系人数组，则系统将擦除客户记录中的联系人。

创建发票

    $invoice = $ninja->invoices->create([
        'client_id' => $client_hashed_id,
        'date' => '2022-10-31',
        'due_date' => '2022-12-01',
        'terms' => 'These are your invoice terms.',
        'footer' => 'Invoice footer text',
        'line_items' => [
            [
                'product_key' => 'some_product_key',
                'notes' => 'description',
                'quantity' => 1,
                'cost' => 10
            ],
            [                
                'product_key' => 'another_product_key',
                'notes' => 'description',
                'quantity' => 1,
                'cost' => 10
            ],
        ],
    ]);

在创建发票时，您可以在单个调用中对发票执行操作，例如，假设您希望创建发票并应用付款到发票

    $invoice = $ninja->invoices->create([
        'client_id' => $client_hashed_id,
        'date' => '2022-10-31',
        'due_date' => '2022-12-01',
        'terms' => 'These are your invoice terms.',
        'footer' => 'Invoice footer text',
        'line_items' => [
            [
                'product_key' => 'some_product_key',
                'notes' => 'description',
                'quantity' => 1,
                'cost' => 10
            ],
            [                
                'product_key' => 'another_product_key',
                'notes' => 'description',
                'quantity' => 1,
                'cost' => 10
            ],
        ],
    ], 
    ['paid' => true] //the second parameter in this method is an array of actions ie paid,mark_sent_send_email,auto_bill
);

或者，如果您希望应用部分付款

    $invoice = $ninja->invoices->create(['client_id'=> 'CLIENT_HASHED_ID'], ['amount_paid' => 10]);

或者您可能想要自动发送和收费发票 注意需要文件中的付款方式

    $invoice = $ninja->invoices->create(['client_id'=> 'CLIENT_HASHED_ID'], ['auto_bill' => true, 'send_email' => true]);

批量操作

您可以针对一个或多个实体执行批量操作。例如，如果您想批量存档一系列发票，您会这样做

  $bulk = $ninja->invoices->archive(["hash_1","hash_2"]);

您可以使用以下方式访问原始批量方法

$bulk = $ninja->invoices->bulk("archive", ["hash_1","hash_2"]);

如果您想下载发票PDF

    $pdf = $ninja->invoices->bulk("download", ["hash_1"]);

以下是发票可用的批量操作列表

• mark_sent
• download
• restore
• archive
• delete
• paid
• clone_to_quote
• clone_to_invoice
• cancel
• reverse
• email

有关使用SDK能实现哪些功能的更多示例，请检查本存储库中的测试文件夹。如果您需要澄清或更明确的SDK使用示例，请创建一个问题。