search

klsheng / myinvois-php-sdk

MyInvois SDK for PHP
MIT License
43 stars 18 forks source link

readme

MyInvois SDK for PHP

Latest Version on Packagist Total Downloads License

Buy Me A Coffee

An object-oriented PHP library to create custom UBL v2.1 format supported by MyInvois System.

This SDK initially require UBL-Invoice package. However, MyInvois System doesn't fully support UBL v2.1 format, so UBL package re-create based on original author to support MyInvois System.

TODO

How to obtain Client ID and Client Secret for Sandbox?

To obtain your Client ID and Client Secret, please send an email request to sdkmyinvois@hasil.gov.my with the following information:

  1. Taxpayer TIN
  2. Business Registration Number
  3. Company Name
  4. Company Email Address
  5. ERP System Name

Installation and usage

This package requires PHP 7.4 or higher.

The preferred way to install this extension is through composer.

To install, either run

$ composer require klsheng/myinvois-php-sdk "*"

or add

"klsheng/myinvois-php-sdk": "*"

to the require section of your composer.json file.

Dependencies

This package require the following extensions in order to work properly:

If you use Composer, these dependencies should be handled automatically. If you install manually, you'll want to make sure that these extensions are available.

Usage

You may refer example to create UBL v2.1 document supported by MyInvois System at CreateDocumentExample.

Sample usage:

Login as Taxpayer System

use Klsheng\Myinvois\MyInvoisClient;

$prodMode = false;
$client = new MyInvoisClient('client_id', 'client_secret', $prodMode);

$client->login();
$access_token = $client->getAccessToken();
// Store $access_token somewhere to re-use it again within 1hour

// OR
$client->setAccessToken('access_token');

Login as Intermediary System

use Klsheng\Myinvois\MyInvoisClient;

$prodMode = false;
$client = new MyInvoisClient('client_id', 'client_secret', $prodMode);

$client->login($onbehalfof);
$access_token = $client->getAccessToken();
// Store $access_token somewhere to re-use it again within 1hour

// OR
$client->setAccessToken('access_token');
$client->setOnbehalfof($onbehalfof);

Get All Document Types

$response = $client->getAllDocumentTypes();

Get Document Type

$response = $client->getDocumentType($id);

Get Document Type Version

$response = $client->getDocumentTypeVersion($id, $versionId);

Get Notifications

$response = $client->getNotifications();
// OR
$dateFrom = new \DateTime('2015-02-13T14:20:10Z'); 
$dateTo = '2015-02-13T14:20:10Z';
$type = '2';
$language = 'en';
$status = 'delivered';
$channel = 'email';
$pageNo = 3;
$pageSize = 20;

$response = $client->getNotifications($dateFrom, $dateTo, $type, $language, $status, $channel, $pageNo, $pageSize);

Validate Taxpayer's TIN

$tin = 'C00000000000';
$idType = 'NRIC';
$idValue = '770625015324';

$response = $client->validateTaxPayerTin($tin, $idType, $idValue);

Submit JSON document

use Klsheng\Myinvois\Helper\MyInvoisHelper;
use Klsheng\Myinvois\Example\Ubl\CreateDocumentExample;
use Klsheng\Myinvois\Ubl\Constant\InvoiceTypeCodes;

$id = 'INV20240418105410';
$supplier = [
    'TIN' => 'C00000000000',
    'BRN' => '0000000-T',
];
$customer = [
    'TIN' => 'C00000000000',
    'BRN' => '0000000-T',
];
$delivery = [
    'TIN' => 'C00000000000',
    'BRN' => '0000000-T',
];

// Example contains hardcoded test data, you may need to modify it yourself
$example = new CreateDocumentExample();
$invoice = $example->createJsonDocument(InvoiceTypeCodes::INVOICE, $id, $supplier, $customer, $delivery, true, '/path/to/eInvoice.crt', '/path/to/eInvoice.key');

// If you are using p12 or pfx file, you may use following code to generate document
/*
$invoice = $example->createJsonDocument(InvoiceTypeCodes::INVOICE, $id, $supplier, $customer, $delivery, true, '/path/to/eInvoice.p12', null, 'passphrase');
*/

// In case there is DS326 error, you may use following code to re-arrange issuer key sequences
// Default sequence -> ['CN', 'E', 'OU', 'O', 'C']
/*
$invoice = $example->createJsonDocument(InvoiceTypeCodes::INVOICE, $id, $supplier, $customer, $delivery, true, '/path/to/eInvoice.p12', null, 'passphrase', ['C', 'O', 'OU', 'E', 'CN']);
*/

$documents = [];
$document = MyInvoisHelper::getSubmitDocument($id, $invoice);
$documents[] = $document;

$response = $client->submitDocument($documents);

Submit XML document

use Klsheng\Myinvois\Helper\MyInvoisHelper;
use Klsheng\Myinvois\Example\Ubl\CreateDocumentExample;
use Klsheng\Myinvois\Ubl\Constant\InvoiceTypeCodes;

$id = 'INV20240418105410';
$supplier = [
    'TIN' => 'C00000000000',
    'BRN' => '0000000-T',
];
$customer = [
    'TIN' => 'C00000000000',
    'BRN' => '0000000-T',
];
$delivery = [
    'TIN' => 'C00000000000',
    'BRN' => '0000000-T',
];

// Example contains hardcoded test data, you may need to modify it yourself
$example = new CreateDocumentExample();
$invoice = $example->createXmlDocument(InvoiceTypeCodes::INVOICE, $id, $supplier, $customer, $delivery, true, '/path/to/eInvoice.crt', '/path/to/eInvoice.key');

// If you are using p12 or pfx file, you may use following code to generate document
/*
$invoice = $example->createXmlDocument(InvoiceTypeCodes::INVOICE, $id, $supplier, $customer, $delivery, true, '/path/to/eInvoice.p12', null, 'passphrase');
*/

// In case there is DS326 error, you may use following code to re-arrange issuer key sequences
// Default sequence -> ['CN', 'E', 'OU', 'O', 'C']
/*
$invoice = $example->createXmlDocument(InvoiceTypeCodes::INVOICE, $id, $supplier, $customer, $delivery, true, '/path/to/eInvoice.p12', null, 'passphrase', ['C', 'O', 'OU', 'E', 'CN']);
*/

$documents = [];
$document = MyInvoisHelper::getSubmitDocument($id, $invoice);
$documents[] = $document;

$response = $client->submitDocument($documents);

Cancel Document

$reason = 'Customer refund';
$response = $client->cancelDocument($id, $reason);

Reject Document

$reason = 'Customer reject';
$response = $client->rejectDocument($id, $reason);

Get Recent Documents

$response = $client->getRecentDocuments();
// OR
$pageNo = 3;
$pageSize = 20;
$submissionDateFrom = '2022-11-25T01:59:10Z';
$submissionDateTo = new \DateTime('2022-12-22T23:59:59Z');
$issueDateFrom = null;
$issueDateTo = null;
$direction = 'Sent';
$status = 'Valid';
$documentType = '01';
$receiverId = 'A12345678';
$receiverIdType = 'PASSPORT';
$receiverTin = 'C2584563200';
$issuerId = null;
$issuerIdType = null;
$issuerTin = null;

$response = $client->getRecentDocuments($pageNo, $pageSize, $submissionDateFrom, $submissionDateTo, $issueDateFrom, $issueDateTo, $direction, $status, $documentType, $receiverId, $receiverIdType, $receiverTin, $issuerId, $issuerIdType, $issuerTin);

Get Submission

$response = $client->getSubmission($tid);

Get Document

$response = $client->getDocument($id);

Get Document Details

$response = $client->getDocumentDetail($id);

Search Documents

$response = $client->searchDocuments();
// OR
$id = 'F9D425P6DS7D8IU';
$submissionDateFrom = null;
$submissionDateTo = null;
$continuationToken = 'Y4RWK9617T0TJNRBF4CSVGQG10';
$pageSize = 100;
$issueDateFrom = null;
$issueDateTo = null;
$direction = 'Sent';
$status = 'Valid';
$documentType = '01';
$receiverId = null;
$receiverIdType = null;
$receiverTin = null;
$issuerTin = null;

$response = $client->searchDocuments($id, $submissionDateFrom, $submissionDateTo, $continuationToken, $pageSize, $issueDateFrom, $issueDateTo, $direction, $status, $documentType, $receiverId, $receiverIdType, $receiverTin, $issuerTin);

Get Document's QR Code URL

use Klsheng\Myinvois\MyInvoisClient;

$prodMode = false;
$client = new MyInvoisClient('client_id', 'client_secret', $prodMode);

$id = '0000000000000'; // Document's UUID
$longId = '11111111111111'; // Document's Long Id
$url = $client->generateDocumentQrCodeUrl($id, $longId);