JoFotara PHP SDK: Open Source E-Invoicing Integration for Jordan

🇯🇴 JoFotara PHP SDK: Open Source E-Invoicing Integration for Jordan

Starting April 1st, 2025, every business operating in Jordan is required to issue electronic invoices through the national tax system: JoFotara.

The goal is clear — digital transformation and real-time tax compliance.
But the road to get there? Not so smooth.

😤 The Reality of JoFotara Integration

Ever since I started woeking with JoFotara (Cause I have to), I was shocked by the amount of chaos around it! Honestly.

  • The API documentation isn’t available online I had to lobby around to get it
  • There’s no sandbox or test environment
  • You’re forced to test using real tax credentials and submit live invoices. I was told to test with old dates, and still don't know if that is going to cause me problems or not!
  • Many vendors are taking advantage of the confusion to overcharge for integration

That’s not what digital transformation should look like. I think we deserve better, both as developers who integrate systems as well as a country that is trying to move forward.

✅ A Better Path: The JoFotara PHP SDK

To fix that, I built the JoFotara PHP SDK — an open-source package that simplifies this integration and makes it accessible to developers across Jordan.

✨ Features

  • 🧾 Supports Income, General Sales, and Special Sales invoice types
  • 🔐 Handles UBL-compliant XML generation, Base64 encoding, and API submission
  • ✅ Provides full validation of invoice data before sending
  • 🧪 Includes unit tests for every section, and full invoice scenario coverage
  • 🧰 Fluent, developer-friendly API

🚀 Quick Start Example

$invoice = new JoFotaraService($clientId, $clientSecret);

$invoice->basicInformation()
    ->setInvoiceType('income')
    ->setInvoiceId('INV-001')
    ->setUuid('...')
    ->setIssueDate('16-02-2023')
    ->cash();

$invoice->sellerInformation()
    ->setTin('12345678')
    ->setName('Your Company');

$invoice->customerInformation()
    ->setId('987654321', 'TIN')
    ->setName('Customer Name');

$invoice->supplierIncomeSource('987654321');

$invoice->items()
    ->addItem('PROD-001')
    ->setQuantity(2)
    ->setUnitPrice(100.00)
    ->setDescription('Sample Product')
    ->taxExempted();

$invoice->invoiceTotals();
$response = $invoice->send();

🔄 Issuing Credit Invoices (Returns)

The SDK supports Credit Invoices, allowing you to issue compliant return invoices that reference a previously submitted invoice.

JoFotara requires:

  • The same invoice type and payment method as the original
  • Reference to the original invoice ID, UUID, and total
  • A valid return reason
  • InvoiceTypeCode set to 381 (automatically handled)

Here’s how to issue a credit invoice using the SDK:

use JBadarneh\JoFotara\JoFotaraService;

$invoice = new JoFotaraService(
    'your-client-id',
    'your-client-secret'
);

$invoice->basicInformation()
    ->setInvoiceType('income') // Must match original
    ->setInvoiceId('CR-001')
    ->setUuid('credit-invoice-uuid')
    ->setIssueDate('26-03-2025')
    // Set as credit invoice with the original invoice ID and UUID
    ->asCreditInvoice('INV-001', 'original-invoice-uuid', 150.00)
    ->cash();

$invoice->setReasonForReturn('Customer returned damaged item');

...

// The rest of the invoice is the same as the original invoice and 
//must match with the original invoice

$invoice->send();

Full documentation and config details are available in the GitHub Readme

📤 Handling SDK Output

Once you call $invoice->send(), the SDK takes care of:

  • Validating your data
  • Generating a compliant UBL XML invoice
  • Encoding it as Base64
  • Sending it to the JoFotara API
  • Returning the response with all essential details

After a successful submission, the SDK gives you everything you need to. Here's what you can do with it:

✅ 1. Check if the Submission Was Successful

$response = $invoice->send();

if ($response->isSuccess()) {
    // Great — the invoice was accepted
} else {
    // Handle errors or warnings
}

Behind the scenes, the SDK checks if the invoice was marked as SUBMITTED or ALREADY_SUBMITTED and passed validation.

💾 2. Store the Final XML Version Sent to JoFotara

This is useful for auditing, re-submission, or issuing credit invoices later.

$xml = $response->getInvoiceAsXml();
storeXml('invoices/123e4567-e89b-12d3....', $xml);

🆔 3. Store the Assigned Invoice ID and UUID

You’ll need both if you want to issue a credit invoice in the future.

$invoiceId = $response->getInvoiceNumber();  // e.g., "INV-001"
$uuid = $response->getInvoiceUuid();         // e.g., "123e4567-e89b-12d3..."

📱 4. Generate and Display the QR Code

For invoicing apps, you can generate a QR code for the invoice:

$qrCodeString = $response->getQrCode();

then display it in your app using a library like qrcodejs or phpqrcode.

🛠️ 5. Debug Errors, Warnings, and Validation Info

If you encounter issues, the SDK provides detailed error handling:

$errors = $response->getErrors();
$warnings = $response->getWarnings();
$info = $response->getInfoMessages();

if ($response->hasErrors()) {
    echo $response->getErrorSummary();
}

🧪 Here is an example for handling an invoice:

$response = $invoice->send();

if ($response->isSuccess()) {
    Log::info('Invoice submitted successfully');
    saveXml($response->getInvoiceAsXml());
    storeQrCode($response->getQrCode());
    storeJoFotaraIds(
        $response->getInvoiceNumber(),
        $response->getInvoiceUuid()
    );
} else {
    Log::error('Invoice failed', $response->getErrors());
}

🧾 How to Get Your JoFotara Integration Credentials

Before using the SDK, you’ll need to set up your integration credentials on the official JoFotara portal.

1. Register Your Business

Visit the JoFotara portal:

https://portal.jofotara.gov.jo/ar/login

JoFotara login/signup screen

You’ll need:

  • A registered business
  • A valid Tax Identification Number (TIN)

2. Create an Integration Device

Once logged in:

  1. Click "Integrate Device"
  2. Click "Create New Integration"
  3. The system will generate:
    • client_id
    • client_secret
    • supplier_income_source (تسلسل مصدر الدخل)
Integration setup screen in JoFotara portal

You’ll use these credentials to configure the SDK.

🧪 Real Testing

Because there is no test environment, all of this was tested live using actual tax accounts.

  • ✅ Income invoices are fully tested and validated
  • ⚠️ General Sales and Special Sales invoice logic is implemented and covered by unit tests but not yet tested due to lack of a VAT-registered business

If you’re able to test and validate these invoice types, I’d love to collaborate and improve this SDK together.

🙌 How You Can Support

If you’re a developer, business owner, or just want to help move digital infrastructure forward in Jordan:

  1. ⭐ Star the GitHub repo
  2. 🧪 Try out the SDK
  3. 🐛 Submit issues or bug reports
  4. 🤝 Contribute with code or documentation
  5. 📝 Share your feedback and suggestions
  6. 💬 Spread the word
  7. ❤️ Sponsor the project

Every bit of support makes a difference — and pushes this forward as a community-driven solution.

🧑‍💻 Why This Matters

This SDK isn’t just about code — it’s about giving equal access to Jordan’s digital systems.

If we want real digital transformation, our public APIs must be well-documented, testable, and developer-friendly.

This project is one small but meaningful step in that direction. Eid Mubarak ❤️

📦 Repo

https://github.com/jafar-albadarneh/jofotara

💬 Feedback is always welcome — Let’s build this together!