README

This package makes it easy to work with ANAF services in Laravel applications.

Installation

You can install the package via composer:

composer require pristavu/laravel-anaf

You can publish and run the migrations with:

php artisan vendor:publish --tag="anaf-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="anaf-config"

What you can do with this package

OAuth2 - authentication/authorization.
- get authorization url
- retrieve access token
- refresh access token
eFactura - client/connector (Oauth2 token required) for interacting with the eFactura API.
- retrieve messages/invoices (regular and paginated)
- download invoices as zip
- extract invoice xml, signature and invoice dto from zip
- validate xml invoices
- upload xml invoices (B2B, B2C)
- convert xml invoices to PDF
- check message status
taxPayer - client/connector (public API / No need for Oauth2) for interacting with the taxpayer API.
- vat status check and other taxpayer information (by cif)
- balance sheet retrieval (by year)

Usage

You can use the package via the Anaf facade:

use Pristavu\Anaf\Facades\Anaf;

Anaf::oauth(...);
Anaf::eFactura(...);
Anaf::taxPayer(...);

or via helper function:

use function Pristavu\Anaf\anaf;

anaf()->oauth(...);
anaf()->eFactura(...);
anaf()->taxPayer(...);

Retries

ANAF endpoints are occasionally flaky (timeouts, 5xx). You can enable automatic retries for the eFactura and TaxPayer connectors via .env:

ANAF_RETRY_TRIES=3                     # total attempts (1 = no retries)
ANAF_RETRY_INTERVAL=500                # base delay in milliseconds
ANAF_RETRY_EXPONENTIAL_BACKOFF=true    # 500ms, 1s, 2s, ...

OAuth2 usage

Add the following to your .env file:

ANAF_CLIENT_ID=your-client-id
ANAF_CLIENT_SECRET=your-client-secret
ANAF_REDIRECT_URI=http://your-callback-url/auth/anaf/callback

or update config/anaf.php with your environment variables

[ 
  'oauth' => [
        'client_id' => env('ANAF_CLIENT_ID'),
        'client_secret' => env('ANAF_CLIENT_SECRET'),
        'redirect_uri' => env('ANAF_REDIRECT_URI', 'http://localhost/auth/anaf/callback'),
  ],
  ...
]

// you can pass the config values directly when initializing the oauth2 authenticator
$connector = Pristavu\Anaf\Facades\Anaf::oauth(
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    redirectUri: 'http://your-callback-url/auth/anaf/callback'
);

Redirect to authorization server

// In redirect controller method eg: '/auth/anaf/redirect'

public function __invoke(): RedirectResponse
{    
    $connector = Pristavu\Anaf\Facades\Anaf::oauth();            
    $state = Str::random(32);    
    // store the state in a scoped session (L12) or cache for later validation
    session()->cache()->put('anaf_oauth_state', $state, now()->addMinutes(5));
    
    $authorizationUrl = $connector->getAuthorizationUrl(
        state: $state, 
        additionalQueryParameters: ['token_content_type' => 'jwt']
    );
    
    return redirect()->away($authorizationUrl);
}

Token retrieval on auth callback

// In callback controller method eg: '/auth/anaf/callback'

public function __invoke(Request $request): ?RedirectResponse
{
    $code = $request->get('code');
    $state = $request->get('state');
    $expectedState = session()->cache()->get('anaf_oauth_state');
    
    if($request->has('error')){
        abort(400, 'Error from authorization server: '.$request->get('error'));
    }
    
    if (!$code || !$state) {
        abort(400, 'Invalid state or code');
    }
      
    try {
        $connector = Pristavu\Anaf\Facades\Anaf::oauth(); 
        $authenticator = $connector->getAccessToken($code, $state, $expectedState);
    } catch (\Exception $e) {
        abort(400, 'Failed to get access token: ' . $e->getMessage());
    }
    
  
    // you can store the serialized token in session or cache for later use
    session()->cache()->put('anaf_oauth_authenticator', $authenticator->serialize());
       
    // or store the token in database or other persistent storage
    Pristavu\Anaf\Models\AccessToken::create([
      'user_id' => auth()->id(),
      'provider' => Provider::ANAF,
      'access_token' => $authenticator->getAccessToken(),
      'refresh_token' => $authenticator->getRefreshToken(),
      'expires_at' => $authenticator->getExpiresAt(),
    ]);
    
    return redirect('/home'); // or wherever you want to redirect the user
}

Refreshing existing access token

// initialize the oauth2 authenticator
$connector = \Pristavu\Anaf\Facades\Anaf::oauth();
 
// get serialized authenticator from session or cache
$serialized = session()->cache()->get('anaf_oauth_authenticator');
$authenticator = \Saloon\Http\Auth\AccessTokenAuthenticator::unserialize($serialized);

// or retrieve it from database access token model
$accessToken = Pristavu\Anaf\Models\AccessToken::query()->where('user_id', auth()->id())->first();
$authenticator = $accessToken->authenticator();

if ($authenticator->hasExpired()) {
    // We'll refresh the access token which will return a new authenticator   
    $authenticator = $connector->refreshAccessToken($authenticator);    
    
    // Store the new token serialized in session or cache
    session()->cache()->put('anaf_oauth_authenticator', $authenticator->serialize());
    
    // or update the existing token model in database
    $accessToken->update([
        'access_token' => $authenticator->getAccessToken(),
        'refresh_token' => $authenticator->getRefreshToken(),
        'expires_at' => $authenticator->getExpiresAt(),
    ]);
}

Efactura usage (Oauth2 required)

Initializing the client

// You need a valid access token to initialize the efactura connector

// retrieve access token from database or other storage
$accessToken = Pristavu\Anaf\Models\AccessToken::query()->where('user_id', auth()->id())->first()->access_token;

// initialize the efactura connector / client
$connector = Pristavu\Anaf\Facades\Anaf::eFactura(accessToken: $accessToken);

Automatic token refresh

Instead of a plain string you can pass an AccessTokenAuthenticator or the AccessToken model. When the token has expired (and a refresh token is available), the connector refreshes it transparently before the request using Anaf::oauth() (so ANAF_CLIENT_ID / ANAF_CLIENT_SECRET must be set):

// AccessToken model: refreshed tokens are persisted on the model automatically
$model = Pristavu\Anaf\Models\AccessToken::query()->where('user_id', auth()->id())->firstOrFail();
$connector = Pristavu\Anaf\Facades\Anaf::eFactura($model);

// Saloon authenticator: persist the refreshed token yourself
$authenticator = \Saloon\Http\Auth\AccessTokenAuthenticator::unserialize(session()->cache()->get('anaf_oauth_authenticator'));
$connector = Pristavu\Anaf\Facades\Anaf::eFactura($authenticator)
    ->onTokenRefresh(fn ($refreshed) => session()->cache()->put('anaf_oauth_authenticator', $refreshed->serialize()));

Switching to test mode (sandbox)

// Live (production) endpoint is used by default and is forced for certain operations eg: validateInvoice, convertInvoice
// Test mode can be used only for uploading, messages ,messagesPaginated, uploadInvoice, messageStatus, downloadInvoice
$connector->inTestMode();

Debugging Request & Response

// enable logging of requests and responses
// die will stop execution after logging the response
$connector->debug();  // $connector->debug(die: true); 

// Separate Debuggers
$connector->debugRequest(); // connector->debugRequest(die: true);
$connector->debugResponse(); // connector->debugResponse(die: true);

Caching

For certain operations like downloading invoices, cache is enabled by default to avoid hitting ANAF download limit rate (10 downloads/day for same $downloadId).

// If you want to disable caching for all operations you can do it like this:
$connector->disableCaching()->downloadInvoice(downloadId: $downloadId);
// or for invalidating cached content before downloading again:
$connector->invalidateCache()->downloadInvoice(downloadId: $downloadId);

Rate limiting

ANAF enforces daily quotas per endpoint and bans clients that exceed them. The connector keeps client-side counters (shared between processes through a Laravel cache store) and throws Saloon\RateLimitPlugin\Exceptions\RateLimitReachedException instead of sending a request that would exceed a quota. Counters are scoped per access token.

ANAF_EFACTURA_RATE_LIMIT_ENABLED=true
ANAF_EFACTURA_RATE_LIMIT_STORE=redis      # defaults to ANAF_EFACTURA_CACHE_STORE
ANAF_EFACTURA_RATE_LIMIT_MESSAGES=1000    # listaMesaje / listaMesajePaginatie, per day
ANAF_EFACTURA_RATE_LIMIT_UPLOAD=1000      # upload / uploadb2c, per day
ANAF_EFACTURA_RATE_LIMIT_STATUS=1000      # stareMesaj, per day
ANAF_EFACTURA_RATE_LIMIT_DOWNLOAD=10      # descarcare, per day and download id

The defaults are conservative; adjust them to the limits published by ANAF for your integration.

Retrieving messages/invoices

You need to use paginated messages if you expect more than 500 messages/invoices for specified period.

// days - number of days between 1 and 60
// type can be one of: MessageType::{SENT/RECEIVED/ERROR/MESSAGE} -  if none provided, all types are retrieved

// eg: retrieve sent messages/invoices for cif 123456 from last 60 days
$response = $connector->messages(cif: 123456, days: 60, type: MessageType::SENT); // returns a MessagesResponse 

if($response->success){
    $response->messages->each(function(Message $message){
        // do something with $message
        $message->cif; // the cif associated with the message/invoice
        $message->upload_id; // the upload id for the message/invoice
        $message->download_id; // the download id for the message/invoice
        $message->type; // the type of message/invoice    
        $message->created_at; // Carbon instance of creation date
        $message->description; // description/details of the message/invoice
    });
} else {
    // handle error
    $response->error;

// eg: retrieve any type of messages/invoices for cif 123456 from last 10 days
$response = $connector->messages(cif: 123456, days: 10);

Retrieving paginated messages/invoices

Somehow even if the paginated response should provide 500 messages per page and total messages are less than 500, messages are divided into two pages (eg: total 95 messages are returned as 2 pages, first with 49 and second with 46 messages).

// period - interval must not exceed 60 days
// type can be one of: MessageType::{SENT/RECEIVED/ERROR/MESSAGE} -  if none provided, all types are retrieved

// retrieve sent messages/invoices for cif 123456 from last 60 days (paginated page 1)
$period = \Carbon\CarbonPeriod::create(now()->subDays(60), now());
$response = $connector->messagesPaginated(cif: 123456, period: $period, page: 1, type: MessageType::SENT); // returns a PaginatedMessagesResponse

if($response->success){
    $response->messages->each(function(Message $message){
        // do something with $message
        $message->cif; // the cif associated with the message/invoice
        $message->upload_id; // the upload id for the message/invoice
        $message->download_id; // the download id for the message/invoice
        $message->type; // the type of message/invoice    
        $message->created_at; // Carbon instance of creation date
        $message->description; // description/details of the message/invoice
    });
    
    // paginated response metadata
    $response->meta->total; // number of messages in selected period
    $response->meta->per_page; // messages per page (default 500)
    $response->meta->current_page; // current page number
    $response->meta->last_page; // last page number
} else {
    // handle error
    $response->error;
}


// or using the toPeriod method
// retrieve any messages/invoices  for cif 123456 from last 10 days (paginated page 2)
$period = now()->subDays(10)->toPeriod(now());
$response = $connector->messagesPaginated(cif: 123456, period: $period, page: 2);

Iterating over all messages/invoices

allMessages() returns a LazyCollection that fetches pages on demand:

$period = Carbon\CarbonPeriod::create(now()->subDays(30), now());

$connector->allMessages(cif: 123456, period: $period, type: MessageType::RECEIVED)
    ->each(function (Message $message): void {
        // pages are requested as you iterate
    });

Debugging from the console

php artisan anaf:messages 123456 --days=7 --type=received --token=<access-token>
php artisan anaf:messages 123456 --user=1   # uses the token stored for user_id 1 in access_tokens
php artisan anaf:messages 123456 --user=1 --test

Downloading messages/invoices

$downloadId = 987654321; // the download_id of the message/invoice
$response = $connector->downloadInvoice(downloadId: $downloadId);

if($response->success){
    // save the zip content to a file
    Storage::disk('private')->put("/invoices/{$downloadId}.zip",$response->content);
    
    // optionally you can extract files from the zip message/invoice using the Extract helper without saving archive to disk    
    $message = Pristavu\Anaf\Support\Extract::from($response->content);
    
    // get xml invoice, signature and dto invoice objects
    $message->xmlInvoice();
    $message->signature();
    // dto invoice will be null if unzipping a non invoice message (eg: xml response error message)
    $message->dtoInvoice();       
}
else {
    // handle error
    $response->error; // array of download errors
}

Validating messages/invoices

$xml = Storage::disk('private')->get('invoices/12345/987654321.xml'); 
// optionally you can pass the full path to xml
$xml = Storage::disk('private')->path('invoices/12345/987654321.xml');

$response = $connector->validateInvoice(
    xml: $xml,
    standard: \Pristavu\Anaf\Enums\DocumentStandard::FCN, // optional, default is FACT1  
);

if($response->success){
   // do something with $response 
} else {
   // handle errors
   $response->errors; // array of validation errors
}

Uploading an invoice

$xml = Storage::disk('private')->get('invoices/12345/987654321.xml');
// optionally you can pass the full path to xml
$xml = Storage::disk('private')->path('invoices/12345/987654321.xml');
$response = $connector->uploadInvoice(
    cif: 123456,
    xml: $xml,
    standard: \Pristavu\Anaf\Enums\XmlStandard::UBL, // optional, default is UBL
    isExternal:  false, // optional, default is false
    isSelfInvoice: false, // optional, default is false
    isLegalEnforcement: false // optional, default is false
);

if($response->success){
    // do something with $response
    $response->upload_id; // the upload id of the invoice
    
}
else {
    // handle error
    $response->error; 
}

Converting invoice to PDF

$xml = Storage::disk('private')->get('invoices/12345/987654321.xml'); 
// optionally you can pass the full path to xml
$xml = Storage::disk('private')->path('invoices/12345/987654321.xml');
$response = $connector->convertInvoice(xml: $xml, standard: DocumentStandard::FACT1, withoutValidation: true);

if($response->success){
    // save the pdf content to a file
    Storage::disk('private')->put("/invoices/12345/987654321.pdf",$response->content);
}

Message status

$uploadId = 987654321; // the message id to check status for
$response = $connector->messageStatus(uploadId: $uploadId);

if($response->success){
   // do something with $response
   $response->status
   $response->download_id; // download id if available
}
else {
   // handle error
   $response->error;
}

TaxPayer usage

Initializing the client

// initialize the taxPayer connector / client
$connector = Pristavu\Anaf\Facades\Anaf::taxPayer();

Checking VAT status

$response = $connector->vatStatus(cif: 123456, date: '2023-12-31'); // VatStatusResponse

if ($response->success && $response->data) {
    $status = $response->data; // Pristavu\Anaf\Dto\TaxPayer\VatStatus
    $status->name;                // denumire
    $status->address;             // adresa
    $status->registration_number; // nrRegCom
    $status->caen_code;
    $status->vat_payer;           // inregistrare_scop_Tva.scpTVA
    $status->vat_on_collection;   // inregistrare_RTVAI.statusTvaIncasare
    $status->split_vat;
    $status->inactive;            // stare_inactiv.statusInactivi
    $status->efactura_registered; // statusRO_e_Factura
    $status->raw;                 // full ANAF payload for anything not mapped
} else {
    $response->error;
}

You can also validate CIFs in form requests with the bundled rule:

use Pristavu\Anaf\Rules\Cif;

$request->validate(['cif' => ['required', new Cif()]]);

Checking VAT status in batch

Up to 100 CIFs per request (ANAF's documented limit, alongside 1 request/second):

$response = $connector->vatStatuses(cifs: [123456, 654321], date: '2023-12-31'); // VatStatusBatchResponse

$response->found;    // Collection<int, VatStatus> keyed by CIF
$response->notFound; // Collection<int, int> — CIFs unknown to ANAF
$response->found->get(123456)?->vat_payer;

Routing through a proxy

Requests (both the public web services and eFactura) can be routed through an HTTP(S) proxy (e.g. a static egress IP) by setting ANAF_PROXY in your .env:

ANAF_PROXY=http://user:pass@proxy.example.com:8080

Retrieving balance sheet

$response = $connector->balanceSheet(cif: 123456, year: 2022); // BalanceSheetResponse

$sheet = $response->data; // Pristavu\Anaf\Dto\TaxPayer\BalanceSheet
$sheet->name;
$sheet->caen_code;
$sheet->indicators;             // Collection<int, BalanceSheetIndicator> (code, name, value)
$sheet->indicator('I13')?->value; // e.g. cifra de afaceri neta

Testing

composer test          # lint, phpstan (level 8), type coverage, unit tests
composer test:mutate   # mutation testing (requires a coverage driver such as xdebug or pcov)

Using the fake client

You can use the mock client to simulate API responses during testing in your laravel application.

use Saloon\Http\Faking\MockClient;
use Requests\Efactura\MessagesRequest;

test('my test', function () {
    // arrange
    $mockClient = new MockClient([
        MessagesRequest::class => MockResponse::make(
        body: [
            'mesaje' => [
                [
                    'data_creare' => 202508291153,
                    'cif' => 123456,
                    'id_solicitare' => 999999999,
                    'detalii' => 'Factura cu id_incarcare=999999999 emisa de cif_emitent=123456 pentru cif_beneficiar=987654',
                    'tip' => 'FACTURA TRIMISA',
                    'id' => 888888888,
                ],
                ...              
            ]
        ],
        status: 200
        ),
    ]);
    
    // act
    $connector = Anaf::eFactura(accessToken: 'TEST_TOKEN');
    $messages = $connector->withMockClient($mockClient)->messages(cif: 123456, days: 60);
    
    // assert
    expect($messages)->toBeInstanceOf(Pristavu\Anaf\Responses\Efactura\MessagesResponse::class);
});

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

pristavu / laravel-anaf

Maintainers

Package info

Fund package maintenance!

Statistics

Security

README

Installation

What you can do with this package

Usage

Retries

OAuth2 usage

Redirect to authorization server

Token retrieval on auth callback

Refreshing existing access token

Efactura usage (Oauth2 required)

Initializing the client

Automatic token refresh

Switching to test mode (sandbox)

Debugging Request & Response

Caching

Rate limiting

Retrieving messages/invoices

Retrieving paginated messages/invoices

Iterating over all messages/invoices

Debugging from the console

Downloading messages/invoices

Validating messages/invoices

Uploading an invoice

Converting invoice to PDF

Message status

TaxPayer usage

Initializing the client

Checking VAT status

Checking VAT status in batch

Routing through a proxy

Retrieving balance sheet

Testing

Using the fake client

Changelog

Contributing

Security Vulnerabilities

Credits

License