README

Sales Data Controller is the a device that is enforced by law to monitor all sales that takes place within a shop that pays VAT. This package controls SDC devices.

Structure

src/
tests/
vendor/

Installation

• Installation
  • Server Requirements
  • Installing KAMARO SDC

Installation

Server Requirements

KAMARO SDC has a few system requirements. Of course, most of these requirements are satisfied by the Laragon, so it's highly recommended that you use Laragon as your local Laravel development environment.

However, if you are not using Laragon, you will need to make sure your server meets the following requirements:

• PHP >= 7.1.0
• OpenSSL PHP Extension
• Mbstring PHP Extension
• Windows 10
• Php Serial extension for windows

Installing KAMARO SDC

KAMARO utilizes Composer to manage its dependencies. So, before using this package, make sure you have Composer installed on your machine.

Via Composer Create-Project

Alternatively, you may also install Laravel by issuing the Composer create-project command in your terminal:

    composer create-project kamaro/sdc your_project_name_here  dev-master  

Install in existing project

composer require Kamaro/Sdc

Usage

Register php serial extension.

Each time you are opening the port, You are required to register it with your license from the vendor or the Serial Port.

<?php
$device = new Kamaro\Sdc\SDCController('COM5','KAMARO LAMBERT #1','12345123'); // Assume your SDC is connect to COM Port 5
echo $device->isOpen(); // true

Get SDC id

<?php
$device = new Kamaro\Sdc\SDCController('COM5'); // Assume your SDC is connect to COM Port 5
echo $device->getID(); // SDC002001531 equivalent to the connected SDC

Get SDC status

<?php
$device = new Kamaro\Sdc\SDCController('COM5');
print_r($device->getStatus());

Results

array(6) {                                            
  ["SDC_SERIAL_NUMBER"]=>                                    
  string(12) "SDC002000173"                                  
  ["FIRMWARE_VERSION"]=>                                     
  string(10) "2.1302.2.8"                                    
  ["HARDWARE_REVISION"]=>                                    
  string(3) "530"                                            
  ["THE_NUMBER_OF_CURRENT_SDC_DAILY_REPORT"]=>               
  string(2) "37"                                             
  ["LAST_REMOTE_AUDIT_DATE_TIME"]=>                          
  string(19) "28/03/2014 11:14:08"                           
  ["LAST_LOCAL_AUDIT_DATE_TIME"]=>                           
  string(0) ""                                               
}                                                          

Send Receipt Data

This is is when you want to send tax information to the SDC, you will need to follow below format other wise The package will throw an exception.

Types of Invoice

Format

RtypeTTypeMRC,TIN,Date TIME, Rnumber,TaxRate1,TaxrRate2,TaxRate3,TaxRate4,Amount1,Amount2,Amount3,Amount4,Tax1,Tax2,Tax3,Tax4

Example

NS01012345,100600570,11/05/2016 12:35:20,23,0.00,18.00,0.00,0.00,11.00,12.00,0.00,0.00,0.00,1.83,0.00,0.00

<?php
// Set Data
$data = "NS01012345,100600570,14/04/2017 12:35:20,23,0.00,18.00,0.00,0.00,11.00,12.00,0.00,0.00,0.00,1.83,0.00,0.00";

// Get Device Instance on PORT 5
$device = new Kamaro\Sdc\SDCController('COM5');
echo $device->sendReceiptData($data); // P for success or ERROR

Get Signature

After sending receipt data to the device, You will need to send another request to get Internal Data and signature to Be put on the Invoice. You have to pass invoice Number as parameter

<?php
// Get Device Instance on PORT 5
$device = new Kamaro\Sdc\SDCController('COM5');
$results = $device->getSignature(23); // Previous Sent Invoice Number 23

var_dump($results);

Results

array(5) {                                                 
  ["date_time"]=>                                                     
  string(19) "14/04/2017 15:50:40"                                    
  ["SDC_ID"]=>                                                        
  string(12) "SDC002000173"                                           
  ["SDC_RECEIPT_NUMBER"]=>                                            
  string(12) "1127/1429/NS"                                           
  ["INTERNAL_DATA"]=>                                                 
  string(32) "6RUG-P4NR-7UIJ-EL7I-WS54-UN7R-MI"                       
  ["RECEIPT_SIGNATURE"]=>                                             
  string(19) "5T54-N5GG-B2WY-IY6S"
}                                                                                                                          

Send Electronic Journal

Now at this stage you have all information required to build a certified invoice, You will add Internal Data and signature you got from getSignature method to your invoice then build your invoice and send it line by line.

B mark for begin of the receipt or the first line of the receipt N mark for line into the body of receipt E mark for end of receipt or the last line of the receipt Read the file and display it line by line.

Assume our final receipt looks like below

B 				  Trade Name
N 				Gikondo, Kigali
N 				TIN: 100600570                        
N                      COPY                        
N -------------------------------------------------
N                    Normal Sale                       
N -------------------------------------------------
N           REFUND IS APPROVED ONLY FOr           
N              ORIGINAL SALES RECEIPT             
N                    400600570                    
N ------------------------------------------------
N Plain Bread            1000.00x 1.00 1000.00A-EX
N Wriggly gum                  60.00x 5.00 300.00B
N ------------------------------------------------
N         THIS IS NOT AN OFFICIAL RECEIPT         
N ------------------------------------------------
N TOTAL                                  -36139.50
N TOTAL                         B-18.00% -36139.50
N TOTAL                             TAX B -5512.81
N ------------------------------------------------
N CASH                                   -36139.50
N ITEMS NUMBER                                   1
N ------------------------------------------------
N               SDC INFORMATION                  
N Date: 14/04/2017                  Time: 11:48:27
N SDC ID:                            SDC001000001
N RECEIPT NUMBER:                       12/259 NR
N                Internal Data:                  
N         IR84-99TN-FCYY-CE22-4HWE-V5TA-EE       
N              Receipt Signature:                
N             669X-TBMM-GPE4-445D                
N -----------------------------------------------
N RECEIPT NUMBER:                             153
N DATE: 25/5/2012                  TIME: 11:50:24
N MRC:                                   01012345
N -----------------------------------------------
N                 THANK YOU                      
E         WE APPRECIATE YOUR BUSINESS     

Assume you are reading a file that has a receipt called receipt.txt You would do it like below.

	$receipt = __DIR__.'/stubs/A8.txt';
	$lines   = file($receipt);
	$endLine = count($lines) - 1;

	$sequence = 32;

	$device = new Kamaro\Sdc\SDCController('COM5');

	foreach ($lines as $key => $line) {
	    // Update sequence
	    if ($sequence > 127) {
			$sequence = 32;
		}
		switch ($key) {
			case 0:
				$results = $device->sendElectronicJournal('B'.$line,$sequence);
				break;
			case $endLine:
				$results = $device->sendElectronicJournal('E'.$line,$sequence);
				break;				
			default:
				$results = $device->sendElectronicJournal('N'.$line,$sequence);
				break;
		}
		$sequence++;
	}

Change log

Please see CHANGELOG for more information on what has changed recently.

Testing

Using composer and PHPUNIT

If you have phpunit installed globally then go to the project directory and run

$ composer test

Using traditional way.

Go to your the index.php from root directory of this package and update the port of the SDC then visit it from your browser. You should see a page like below

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Security

If you discover any security related issues, please email :author_email instead of using the issue tracker.

Credits

• KAMARO Lambert
• [All Contributors][link-contributors]

License

The MIT License (MIT). Please see License File for more information.