Node.js client library for interacting with the Benin e-MCF API for normalized invoicing
npm install @ikarha/emecef- Billing API:
- Create,
- finalize,
- and retrieve invoice details.
- Info API:
- Fetch e-MCF status,
- tax groups,
- invoice types,
- and payment types.
- TypeScript Support: Fully typed with TypeScript interfaces for robust development.
Environment Configuration: Configurable via environment variables for security and flexibility.
Error Handling: Comprehensive error handling with meaningful messages.
``bash`
npm install @ikarha/emecef
- Node.js (>= 14.x)
- A valid JWT token provided by the DGI for e-MCF API access
- An active internet connection :)
`bash
EMECEF_BASE_URL=https://developer.impots.bj/sygmef-emcf/api
EMECEF_TOKEN=your-jwt-token
`
Ensure you have dotenv installed and load it at the start of your application:
`bash``
npm install dotenv
Then, load the environment variables in your application:
`typescript
import * as dotenv from 'dotenv';
dotenv.config();
`
`typescript
import { BillingService, InfoService } from '@ikarha/emecef';
// Initialize services (environment variables must be set)
const billingService = new BillingService();
const infoService = new InfoService();
`
#### Example: Create and Finalize an Invoice
`typescript
import { BillingService } from '@ikarha/emecef';
import { InvoiceRequestDataDto, InvoiceTypeEnum, PaymentTypeEnum, TaxGroupTypeEnum } from 'emcf-api-client/dist/types/billing';
import * as dotenv from 'dotenv';
dotenv.config();
async function main() {
const billingService = new BillingService();
try {
// Check API status
const status = await billingService.getStatus();
console.log('API Status:', status);
// Create an invoice
const invoiceData: InvoiceRequestDataDto = {
ifu: '9999900000001',
type: InvoiceTypeEnum.FV,
items: [
{
name: 'Jus d\'orange',
price: 1800,
quantity: 2,
taxGroup: TaxGroupTypeEnum.B
},
{
name: 'Lait 1/1 EX',
price: 450,
quantity: 3,
taxGroup: TaxGroupTypeEnum.A
}
],
client: {
contact: '45661122',
ifu: '9999900000002',
name: 'Nom du client',
address: 'Rue d\'ananas 23'
},
operator: {
id: '',
name: 'Jacques'
},
payment: [
{
name: PaymentTypeEnum.ESPECES,
amount: 4950
}
]
};
const invoiceResponse = await billingService.createInvoice(invoiceData);
console.log('Invoice Response:', invoiceResponse);
// Finalize the invoice
const finalizeResponse = await billingService.finalizeInvoice(invoiceResponse.uid, 'confirm');
console.log('Finalization:', finalizeResponse);
} catch (error) {
console.error('Error:', error instanceof Error ? error.message : 'Unknown error');
}
}
main().catch(console.error);
`
#### Available Methods
- BillingService
- getInvoiceStatus(): Retrieves the API status and pending invoice requests.
- createInvoice(data: InvoiceRequestDataDto): Submits a new invoice and retrieves calculated totals.
- finalizeInvoice(uid: string, action: 'confirm' | 'annuler'): Confirms or cancels an invoice.
- getInvoiceDetails(uid: string): Retrieves details of a pending invoice.
- InfoService
- getEmeCefInfo(): Retrieves information about e-MCF instances.
- getTaxGroups(): Retrieves available tax groups and their rates.
- getInvoiceTypes(): Retrieves available invoice types.
- getPaymentTypes(): Retrieves available payment types.
| Variable | Description | Required | Example |
|---------------|--------------------------------------|----------|---------------------------------------------|
| EMECEF_BASE_URL | Base URL of the e-MCF API | Yes | https://developer.impots.bj/sygmef-emcf/api |
| EMECEF_TOKEN | JWT token for API authentication | Yes | your-jwt-token |
`bash`
npm run build
#### Run Tests
Tests are implemented with Jest. Run them with:
`bash`
npm test
#### Project Structure
- `src/api/`: Contains service classes for billing and info APIs.`
- src/types/`: TypeScript interfaces for API data transfer objects (DTOs).`
- src/errors/`: Custom error handling logic.`
- dist/``: Compiled JavaScript and TypeScript declaration files.