Matt-di/ethiopia-eims
Domain:
digital infrastructureRecord type:
software
Creator:
Mat
Host:
# Ethiopia EIMS PHP Client
A framework-agnostic PHP client for the **Ethiopian Ministry of Revenue (MoR) Electronic Invoice Management System (EIMS)**, with an optional Laravel bridge.
It lets any ERP register invoices, receipts, and query/verify/cancel documents against the EIMS API. The package speaks **plain DTOs and returns result objects** — it does not touch your database, models, or tenancy. Mapping your domain (sales, customers, products) to an `InvoiceRequest` and persisting results is your application's job.
> **Status:** `0.x`, API may change. Ethiopian e-invoicing is pre-mandate; the request/response shapes reflect the current EIMS API and may evolve.
## Requirements
- PHP 8.2+
- `guzzlehttp/guzzle` ^7.5
- A PSR-16 cache (optional, for token caching) — Laravel's cache works out of the box.
## Installation
```bash
composer require mattdi/ethiopia-eims
```
## Plain PHP usage
```php
use Mattdi\Eims\EimsClient;
use Mattdi\Eims\Config\EimsCredentials;
use Mattdi\Eims\Config\SellerConfig;
use Mattdi\Eims\Data\{InvoiceRequest, BuyerDetails, InvoiceItem, ValueDetails, DocumentDetails, SourceSystem};
use Mattdi\Eims\Enums\TransactionType;
$client = new EimsClient(
credentials: new EimsCredentials(
clientId: getenv('EIMS_CLIENT_ID'),
clientSecret: getenv('EIMS_CLIENT_SECRET'),
apiKey: getenv('EIMS_API_KEY'),
baseUrl: 'core.mor.gov.et',
),
seller: new SellerConfig(
tin: '0001234567',
legalName: 'Acme Pharmacy PLC',
regionCode: '14',
city: 'Addis Ababa',
vatNumber: 'VAT-123',
),
// cache: $psr16Cache, // optional
// cacheNamespace: 'store_42', // optional; defaults to the TIN
);
$result = $client->register(new InvoiceRequest(
buyer: BuyerDetails::walkIn(),
items: [
new InvoiceItem(
productDescription: 'Paracetamol 500mg',
quantity: 2,
unitPrice: 25.00,
preTaxValue: 50.00,
taxAmount: 0.00,
totalLineAmount: 50.00,
),
],
values: new ValueDetails(totalValue: 50.00, taxValue: 0.00),
document: new DocumentD …