README

用于与 Flick API 交互的 PHP 接口。

安装
入门
文档
示例
为我们的 SDK 做贡献
许可协议
支持

安装

要在您的项目中使用 Flick Php SDK，您可以通过 composer 安装它

composer require flick/flick-php-sdk

入门

在开始使用此包之前，您需要使用您的 API 凭证进行配置。您应该有一个 apiKey，并指定您是否使用 'sandbox' 或 'production' 环境。

以下是如何在您的项目中初始化我们的 SDK 的示例

use Flick\FlickPhpSdk\Bills;
use Flick\FlickPhpSdk\Config;

// Initialize the Bills class with your API key and specify the environment ('sandbox' or 'production')
$bills = new Bills(new Config('sandbox', 'your-api-key-here'));

注意

您可能需要根据您选择的框架（或没有框架）导入自动加载文件

require 'vendor/autoload.php';

文档

有关可用方法和它们的使用方法，请参阅官方 API 文档。以下是我们的账单模块的一瞥。

账单客户端

账单客户端提供了管理账单的各种功能。您可以与以下 API 端点交互

将 EGS 启用到 ZATCA

$egs_data = [ /* your EGS data goes here*/ ]

$response = $bills->onboard_egs($egsData)->wait();
print($response->getBody()->getContents());

合规性检查

$egs_uuid = 'egs-uuid';

$response = $bills->do_compliance_check($egs_uuid);
print($response->getBody()->getContents());

在沙特阿拉伯第二阶段生成电子发票

$invoice_data = [ /* your Invoice data goes here*/ ]

$response = $bills->generate_invoice($egsData)->wait();
print($response->getBody()->getContents());

示例

以下是一个示例，说明您如何 将多个 EGS 启用到 ZATCA 门户 [如果您正在启用 PoS 设备或增值税集团成员，这将很有用]。
示例还包括在示例文件夹中

<?php

// Include the necessary dependencies
use Flick\FlickPhpSdk\Bills;
use Flick\FlickPhpSdk\Config;

// Initialize the Bills class with your API key and specify the environment ('sandbox' or 'production')
$bills = new Bills(new Config('sandbox', 'your-api-key-here'));

// Define the data for onboarding EGS
$egsData = [
  'vat_name' => 'Test Co.',
  'vat_number' => '300000000000003',
  'devices' => [
    [
      'device_name' => 'TestEGS1',
      'city' => 'Riyadh',
      'city_subdiv' => 'Test Dist.',
      'street' => 'Test St.',
      'plot' => '1234',
      'building' => '1234',
      'postal' => '12345',
      'branch_name' => 'Riyad Branch 1',
      // This will be a 10-digit TIN if you are onboarding a VAT-Group Member
      'branch_industry' => 'Retail',
      'otp' => '123321',
    ],
    [
      'device_name' => 'TestEGS2',
      'city' => 'Riyadh',
      'city_subdiv' => 'Test Dist.',
      'street' => 'Test St.',
      'plot' => '1234',
      'building' => '1234',
      'postal' => '12345',
      'branch_name' => 'Riyad Branch 2',
      // This will be a 10-digit TIN if you are onboarding a VAT-Group Member
      'branch_industry' => 'Retail',
      'otp' => '321123',
    ],
  ],
];

// Perform the EGS onboarding operation asynchronously and handle the result or error
$promise = $bills->onboard_egs($egsData);

$promise->then(function ($result) {
  // Handle the successful result
  print($result);
})->otherwise(function ($exception) {
  // Handle the error 
  print($exception->getResponse()->getBody()->getContents());
})->wait();

以下是一个示例，说明您如何 生成符合 ZATCA 标准的电子发票。

<?php
require '../vendor/autoload.php';

// Include the necessary dependencies

use Flick\FlickPhpSdk\Bills;
use Flick\FlickPhpSdk\Config;

// Initialize the Bills class with your API key and specify the environment ('sandbox' or 'production')
$bills = new Bills(new Config('sandbox', 'your-api-key-here'));

// Define the data for generating invoice

$invoiceData = [
  'egs_uuid' => '7b9cc231-0e14-4bff-938c-4603fe10c4bc',
  'invoice_ref_number' => 'INV-5',
  'issue_date' => '2023-01-01',
  'issue_time' => '01:40:40',
  'party_details' => [
    'party_name_ar' => 'شركة اختبار',
    'party_vat' => '300001111100003',
    'party_add_id' => [
      'crn' => 45463464,
    ],
    'city_ar' => 'جدة',
    'city_subdivision_ar' => 'حي الشرفية',
    'street_ar' => 'شارع الاختبار',
    'plot_identification' => '1234',
    'building' => '1234',
    'postal_zone' => '12345',
  ],
  'doc_type' => '388',
  'inv_type' => 'standard',
  'payment_method' => 10,
  'currency' => 'SAR',
  'total_tax' => 142.0,
  'has_advance' => true,
  'advance_details' => [
    'advance_amount' => 575,
    'total_amount' => 2875,
    'advance_invoices' => [
      [
        'tax_category' => 'S',
        'tax_percentage' => 0.15,
        'taxable_amount' => 500,
        'tax_amount' => 75,
        'invoices' => [
          [
            'id' => 'INV-1',
            'issue_date' => '2022-12-10',
            'issue_time' => '12:28:17',
          ],
        ],
      ],
    ],
  ],
  'lineitems' => [
    [
      'name_ar' => 'متحرك',
      'quantity' => 1,
      'tax_category' => 'S',
      'tax_exclusive_price' => 750,
      'tax_percentage' => 0.15,
    ],
    [
      'name_ar' => 'حاسوب محمول',
      'quantity' => 1,
      'tax_category' => 'S',
      'tax_exclusive_price' => 1750,
      'tax_percentage' => 0.15,
    ],
  ],
];



// Perform the EGS onboarding operation asynchronously and handle the result or error
$promise = $bills->generate_invoice($invoiceData);

$promise->then(function ($result) {
  // Handle the successful result
  print($result);
})->otherwise(function ($exception) {
  // Handle the error 
  print($exception->getResponse()->getBody()->getContents());
})->wait();

贡献

我们欢迎社区的贡献。如果您发现问题或有改进建议，请打开一个问题或创建一个 pull request。

许可协议

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

支持

如果您遇到任何问题或有疑问，请联系我们的支持团队 support@flick.network

关键词

电子发票，电子发票，zatca，phase2，saudi，ksa，fatoora，saudiarabia，egs

flick / flick-php-sdk

维护者

详细信息