PHP API SDK

Welcome to the Flick's PHP SDK Documentation, your essential companion for unlocking the powerful capabilities of Flick's Consign module within your applications. Our SDK empowers you with a range of features designed to simplify your billing processes, elevate your e-invoicing capabilities, optimize inventory management, and seamlessly integrate with cloud services. This reference guide is your go-to resource for harnessing the full potential of our Consign API, complete with endpoint descriptions, request parameters, and hands-on examples to facilitate programmatic interaction with our billing system.

Whether you're a seasoned developer or just getting started, this SDK will be your trusted partner in leveraging the rich functionality of Flick's Consign module. Let's dive in and discover how you can bring efficiency and innovation to your billing and invoicing workflows with our PHP SDK.

Installation

To use the Flick Php SDK in your project, you can install it via composer:

composer require flick/flick-php-sdk

Getting Started

Before using the package, you need to configure it with your API credentials. You should have an apiKey and specify whether you are using the 'sandbox' or 'production' environment.

Here's how you to initiate our SDK in your project:

use Flick\FlickPhpSdk\Consign;
use Flick\FlickPhpSdk\Config;

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

Note

You may need to import the autoload file depending on the framework (or lack thereof) you choose

require 'vendor/autoload.php';

Documentation

To learn about available methods and their usage, please refer to the official API documentation. Here's a glimpse to our Consign Module:

Consign Client

The Consign client provides access to various functionalities for managing Consign. You can interact with the following API endpoints:

Onboard EGS to ZATCA:

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

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

Compliance Check:

$egs_uuid = 'egs-uuid';

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

Generate E-Invoice for Phase-2 in Saudi Arabia:

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

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

Examples

Here's an Example of how you can onboard multiple EGS to ZATCA Portal [If you are onboarding PoS devices or VAT-Group members, this comes handy].
Examples are included in the examples folder as well

<?php

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

// Initialize the Consign class with your API key and specify the environment ('sandbox' or 'production')
$Consign = new Consign(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 = $Consign->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();

Here's an Example of how you can Genereate a ZATCA-Complied E-Invoice.

<?php
// Include the necessary dependencies
use Flick\FlickPhpSdk\Consign;
use Flick\FlickPhpSdk\Config;

// Initialize the Consign class with your API key and specify the environment ('sandbox' or 'production')
$Consign = new Consign(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 = $Consign->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();