README

Laravel client SDK for the MyInvois Middleware Gateway (MyInvois API 1.0). Provides a clean PHP integration layer for submitting e-invoices, managing sessions, tracking submissions, polling status, and validating TINs via Zahid Aramai's MyInvois Middleware.

Features

• Simple and intuitive API for MyInvois operations
• Facade and dependency injection support
• Configurable via environment variables
• Zero business logic duplication - purely a middleware client
• Full support for Laravel 10 and 11
• Auto-discovery ready

Requirements

• PHP 8.1 or higher
• Laravel 10.x or 11.x
• Guzzle HTTP 7.x

Installation

Install the package via Composer:

composer require zahidaramai/laravel-myinvois-middleware

The package will auto-register its service provider and facade.

Publish Configuration

Publish the configuration file:

php artisan vendor:publish --tag=myinvois-config

This will create a config/myinvois.php file in your application.

Configuration

Add the following environment variables to your .env file:

MYINVOIS_MIDDLEWARE_BASE_URL=https://your-middleware-server.com
MYINVOIS_MIDDLEWARE_API_KEY=your-api-key-here
MYINVOIS_MIDDLEWARE_TIMEOUT=30
MYINVOIS_MIDDLEWARE_CONNECT_TIMEOUT=10
MYINVOIS_MIDDLEWARE_VERIFY_SSL=true

Configuration Options

Usage

Using the Facade

use ZahidAramai\MyInvoisMiddleware\Facades\MyInvois;

// Create a session
$session = MyInvois::createSession();

// Submit documents (e-invoices)
$documents = [
    [
        'type' => 'invoice',
        'data' => [
            'invoiceNumber' => 'INV-001',
            'amount' => 1000.00,
            // ... other invoice fields
        ],
    ],
];

$submission = MyInvois::submitDocuments($documents);

// Get submission status
$status = MyInvois::getSubmission($submission['submission_id']);

// Validate a TIN
$validation = MyInvois::validateTin(
    tin: 'C12345678901',
    idType: 'BRN',
    idValue: '202001012345'
);

// Get all submissions with filters
$submissions = MyInvois::getSubmissions([
    'status' => 'completed',
    'page' => 1,
]);

// Cancel a document
$result = MyInvois::cancelDocument('document-uuid', 'Customer requested cancellation');

Using Dependency Injection

use ZahidAramai\MyInvoisMiddleware\MyInvoisClient;

class InvoiceController extends Controller
{
    public function __construct(
        protected MyInvoisClient $myInvois
    ) {}

    public function submit(Request $request)
    {
        $documents = $this->prepareDocuments($request);

        $result = $this->myInvois->submitDocuments($documents);

        return response()->json([
            'submission_id' => $result['submission_id'],
            'status' => $result['status'],
        ]);
    }

    public function status(string $submissionId)
    {
        $status = $this->myInvois->getSubmission($submissionId);

        return response()->json($status);
    }
}

Available Methods

Error Handling

The client throws Guzzle exceptions for HTTP errors. Handle them appropriately:

use GuzzleHttp\Exception\ClientException;
use GuzzleHttp\Exception\ServerException;
use ZahidAramai\MyInvoisMiddleware\Facades\MyInvois;

try {
    $result = MyInvois::submitDocuments($documents);
} catch (ClientException $e) {
    // 4xx errors - client-side issue
    $response = $e->getResponse();
    $body = json_decode($response->getBody()->getContents(), true);

    Log::error('MyInvois client error', [
        'status' => $response->getStatusCode(),
        'body' => $body,
    ]);
} catch (ServerException $e) {
    // 5xx errors - server-side issue
    Log::error('MyInvois server error', [
        'message' => $e->getMessage(),
    ]);
}

Testing

Run the test suite:

composer test

Changelog

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Security

If you discover any security-related issues, please email zahid@aramai.com instead of using the issue tracker.

Credits

• Zahid Aramai
• All Contributors

License

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