Download the PHP package bee-coded/laravel-efactura-sdk without Composer

Laravel e-Factura SDK

A Laravel package for integrating with Romania's ANAF e-Factura (electronic invoicing) system.

Features

• OAuth 2.0 Authentication - Complete OAuth flow with JWT tokens and automatic token refresh
• Document Operations - Upload, download, and check status of invoices
• UBL 2.1 XML Generation - Generate CIUS-RO compliant invoice XML
• Company Lookup - Query ANAF for company details (VAT status, addresses, etc.)
• Validation - Validate XML against ANAF schemas before upload
• PDF Conversion - Convert XML invoices to PDF format
• Rate Limiting - Built-in protection against exceeding ANAF API quotas

Requirements

• PHP 8.4+
• Laravel 11.0+
• Valid ANAF OAuth credentials

Installation

Publish the configuration file:

Configuration

Add the following to your .env file:

Configuration Options

Logging Channel (Recommended)

Add a dedicated logging channel in config/logging.php:

Rate Limiting Configuration

The SDK includes built-in rate limiting to prevent exceeding ANAF API quotas. All defaults are set to 50% of ANAF's actual limits for safety.

ANAF Official Rate Limits:

Usage

OAuth Authentication Flow

The SDK provides a stateless OAuth implementation. You are responsible for storing tokens in your database.

Step 1: Redirect User to ANAF Authorization

Step 2: Handle OAuth Callback

Manual Token Refresh

API Operations

Creating the Client

Upload Invoice

Check Processing Status

Download Document

List Messages

Paginated Messages

Validate XML

Convert to PDF

Verify Signature

Automatic Token Refresh

The SDK automatically refreshes tokens when they're about to expire (120-second buffer before expiration).

Important: ANAF uses rotating refresh tokens. When a token is refreshed, both the access token AND refresh token are replaced. The old refresh token becomes invalid.

Recommended Pattern:

Rate Limiting

The SDK automatically enforces rate limits before each API call. When a limit is exceeded, a RateLimitExceededException is thrown.

Checking Remaining Quota

Before making API calls, you can check remaining quota:

Disabling Rate Limiting

For testing or special cases, you can disable rate limiting:

Or check status in code:

Generating Invoice XML

Using the UBL Builder

Creating a Credit Note

Credit Note Quantity Handling (Breaking Change in v1.1)

The SDK automatically negates quantities for credit notes. ANAF treats the <CreditNote> document type as inherently negative, so line quantities must be positive in the XML. The SDK handles this sign-flip internally.

How it works: pass quantities with their business meaning, and the SDK converts them for ANAF:

Example — credit note with a discount reversal:

Upgrading from v1.0: If your code was passing positive quantities for credit note lines and relying on them going to ANAF as-is, you must now pass negative quantities instead (the SDK will negate them to positive). If you were already passing negative quantities (as documented), no changes are needed — the SDK now correctly converts them for ANAF.

Invoice Calculations

Why taxAmount is Required (Breaking Change in v2.0)

In v1.x, the SDK calculated VAT amounts internally by grouping lines by tax rate and multiplying sum_of_base_amounts × tax_rate. This caused rounding discrepancies when your application used tax-included pricing.

The problem:

When a line item has a tax-included price (e.g., 100.00 RON including 19% VAT), your application extracts the base price by subtraction:

But when the SDK grouped multiple such lines and recalculated VAT from the grouped base:

Your application computed 15.97 + 15.97 = 31.94. The SDK computed 31.93. This 0.01 RON difference meant the XML total sent to ANAF didn't match your local invoice total.

The fix:

Starting in v2.0, taxAmount is a required parameter on InvoiceLineData. You pass the VAT amount you already computed for each line, and the SDK uses it directly instead of recalculating. This guarantees the XML total matches your application's total exactly.

How to compute taxAmount:

The key rule: whatever VAT amount your application stores for the line item, pass that exact value as taxAmount. The SDK will use it as-is.

taxAmount sign convention:

The taxAmount sign must follow the quantity:

• Positive quantity → positive taxAmount
• Negative quantity (credit note lines) → negative taxAmount

The SDK's credit note sign-flip (negating quantities for ANAF) also applies to taxAmount internally — you don't need to handle this yourself.

Upgrading from v1.x: Add taxAmount to every new InvoiceLineData(...) call. If you were using net pricing (tax-exclusive unitPrice), compute it as round(round(quantity * unitPrice, 2) * taxPercent / 100, 2). If you were using tax-included pricing, pass the VAT amount you already extracted from the gross total.

Address Sanitization

Romanian addresses are automatically sanitized to ISO 3166-2:RO format:

Company Lookup

Query ANAF for company information (no authentication required):

Note (v2.2.0): a lookup whose CUIs are all not-found now returns success === true with the CUIs in $result->notFound (previously a single not-found CUI returned a failure result). Branch on hasNotFound() / hasCompanies(), not on success, to distinguish outcomes. ANAF returns this case as HTTP 404 with a {found, notFound} body — the SDK treats that documented "none found" response as a not-found result, not an error.

Detecting radiated (struck-off) companies: ANAF reports trade-registry strike-off in date_generale.stare_inregistrare ("RADIERE din data ..."), which the SDK maps to registrationStatus, flips isDeregistered to true, and makes isActive() return false. This is distinct from fiscal inactivity (isInactive) and from leaving the TVA-la-încasare registry (rtvaiDetails->actType === 'Radiere').

Rate limit: ANAF limits the company-lookup endpoint to 1 request/second. The SDK enforces this and throws BeeCoded\EFacturaSdk\Exceptions\RateLimitExceededException (HTTP 429, with ->retryAfterSeconds) when exceeded. This is independent of the per-request payload cap of 100 CUIs. Disable via efactura-sdk.rate_limits.enabled = false.

Validators

VAT Number Validation

CNP Validation

Date Helpers

Enums

StandardType

DocumentStandardType

MessageFilter

InvoiceTypeCode

Valid codes per ANAF BR-RO-020 schematron rule:

Note: The SDK automatically generates the correct UBL document type. Code 381 generates a <CreditNote> document with <CreditNoteTypeCode> and <CreditNoteLine> elements, while all other codes generate an <Invoice> document.

Exception Handling

Testing

When testing your application, you can mock the SDK services:

AI Assistant Integration (MCP)

This package includes an MCP server that helps AI coding assistants understand the SDK's DTOs, API methods, and conventions.

Setup: Add to your AI tool's MCP configuration:

Requires Node.js 18+.

The MCP server provides these tools:

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.