laravel-verifactu maintained by vlec
Laravel Verifactu
Issue VERI*FACTU invoices from a Laravel app through the Verifactu service.
Your invoice model describes the sale. The package sends it to the service, which numbers it and sends its record to AEAT, and keeps the model's table up to date with AEAT's answer through signed webhooks. It also issues batches, fixes and cancels invoices, and checks a customer's tax ID.
This package is built for the company's own apps.
- Requirements
- Installation
- Configuration
- The invoice model
- Issuing invoices
- Batches
- Fixing and cancelling
- Events
- Webhooks
- Tax-ID checks
- Calling the API directly
- Testing
- Commands
- Upgrading
Requirements
- PHP 8.4+ with
ext-bcmath - Laravel 13
- A queue worker on a real queue connection, such as
databaseorredis - An app on the Verifactu service: its API token and webhook signing secret
Installation
composer require vlec/laravel-verifactu
php artisan verifactu:install
Run the wizard once the invoice model's table is migrated:
- Publishes
config/verifactu.php. - Adds
VERIFACTU_URL,VERIFACTU_TOKENandVERIFACTU_WEBHOOK_SECRET, empty, to.envand.env.example. A key already set keeps its value. - Asks which model is the invoice, and which of its columns already hold the number, date, status and QR code.
- Writes those choices into the config, and a migration that adds only the missing columns. It also publishes the migration of the package's own
verifactu_invoice_batchestable. - Lists the columns of an earlier AEAT setup of your own (a hash, a chain, XML), which the service keeps now, and prints a migration to drop them if you want to. It never drops anything.
- Prints the lines to add to the model, the schedule line and the webhook URL.
Then fill the three keys and run the migrations:
php artisan migrate
The wizard's migration runs on the default database connection, as every app's own migrations do. If the invoice model lives on another connection, move the columns there by hand.
Configuration
VERIFACTU_URL=https://verifactu.example.com
VERIFACTU_TOKEN=vf_test_...
VERIFACTU_WEBHOOK_SECRET=whsec_...
An administrator of the service gives you these on your app's page, under Apps. The token decides the environment: a vf_test_ token works in Test (AEAT's pre-production), a vf_prod_ token in Live.
Give each database its own app and token on the service: each developer, staging and production. The package finds an invoice on the service by its model key (invoice:42), so two databases sharing a token would both claim invoice:1.
Everything else lives in config/verifactu.php:
| Key | Default | What it does |
|---|---|---|
model |
App\Models\Invoice |
The invoice model |
columns |
verifactu_* |
The model's columns for the service's answer (below) |
exemption_reason |
E1 |
The reason TaxLine::exempt() uses when given none |
webhook_path |
verifactu/webhook |
The path the service posts its webhooks to |
queue |
null |
The queue of the package's jobs; null for the default one |
retries |
2 |
Retries of a direct call after no answer, a 429, a 5xx |
connect_timeout |
5 |
Seconds to wait for a connection |
timeout |
30 |
Seconds to wait for the whole answer |
The columns, each of which you may rename:
| Field | Column | Holds |
|---|---|---|
uuid |
verifactu_uuid |
The invoice's id on the service |
status |
verifactu_status |
Its status at AEAT, cast to Vlec\Verifactu\InvoiceStatus |
invoice_number |
verifactu_invoice_number |
The number to print, such as FACT42 |
number |
verifactu_number |
The bare number a corrective invoice refers to, such as 42 |
issue_date |
verifactu_issue_date |
The issue date, cast to a date unless the model casts it |
verification_url |
verifactu_url |
AEAT's verification URL |
qr_code |
qr_code |
The QR code, a base64 PNG without a data: prefix |
Every column must exist before the first invoice is sent: the package stores the service's answer the moment it arrives.
The invoice model
The model implements VerifactuInvoice, uses IssuesVerifactuInvoices, and describes the sale in toVerifactu(). Amounts are whole cents, never floats.
use Illuminate\Database\Eloquent\Model;
use Vlec\Verifactu\Contracts\VerifactuInvoice;
use Vlec\Verifactu\InvoiceData;
use Vlec\Verifactu\IssuesVerifactuInvoices;
use Vlec\Verifactu\Recipient;
use Vlec\Verifactu\TaxLine;
class Invoice extends Model implements VerifactuInvoice
{
use IssuesVerifactuInvoices;
public function toVerifactu(): InvoiceData
{
return InvoiceData::make("Order {$this->id}")
->to(Recipient::spanish($this->customer_tax_id, $this->customer_name))
->lines([TaxLine::vat($this->subtotal_cents, rate: 21)]);
}
}
Tax lines
A line subject to VAT takes its base in cents and the rate in percent, as an int or a numeric string:
TaxLine::vat(10000, rate: 21);
An exempt line takes its base and, optionally, the reason. Without one it uses config('verifactu.exemption_reason'), E1 (article 20 of the VAT law: education, health…):
use Vlec\Verifactu\ExemptionReason;
TaxLine::exempt(30000);
TaxLine::exempt(20000, ExemptionReason::Exports);
The reasons are InternalOperations (E1), Exports (E2), ExportLikeOperations (E3), CustomsAndTaxWarehouses (E4), IntraEuSupplies (E5) and Other (E6).
An invoice may mix VAT and exempt lines. An order with an exempt course and a book at 21% VAT:
public function toVerifactu(): InvoiceData
{
$lines = [];
if ($this->exempt_cents !== 0) {
$lines[] = TaxLine::exempt($this->exempt_cents);
}
if ($this->taxable_cents !== 0) {
$lines[] = TaxLine::vat($this->taxable_cents, rate: 21);
}
return InvoiceData::make("Order {$this->id}")
->to(Recipient::spanish($this->customer_tax_id, $this->customer_name))
->lines($lines);
}
protected function casts(): array
{
return [
'exempt_cents' => 'integer',
'taxable_cents' => 'integer',
];
}
Cast the cent columns to integer, so a 0 read from the database or a request is the integer 0.
Pass your own items as they are: lines with the same VAT rate, or the same exemption reason, become one line with their bases added up. The tax is worked out once per grouped line, rounded half away from zero to the cent (-52.5 cents is -53). The service takes 1 to 12 grouped lines.
taxLines() and totalCents() give back exactly what AEAT receives, to print on the invoice:
$data = $invoice->toVerifactu();
foreach ($data->taxLines() as $line) {
$line->baseCents;
$line->rate; // a BcMath\Number, or null for an exempt line
$line->exemptionReason; // an ExemptionReason, or null
$line->taxCents();
}
$data->totalCents();
The recipient
A Spanish customer goes by their tax ID (NIF) and the name AEAT knows. A foreign one goes by a document:
use Vlec\Verifactu\ForeignIdType;
Recipient::spanish('A15022510', 'Acme S.L.');
Recipient::foreign('Jean Dupont', 'FR', ForeignIdType::EuVatNumber, 'FR40303265045');
The document types are EuVatNumber, Passport, NationalId, ResidenceCertificate, OtherDocument and NotRegistered.
Other kinds of invoice
// A simplified invoice (F2): no recipient.
InvoiceData::make('Coffee')->simplified()->lines([TaxLine::vat(150, rate: 10)]);
// A full invoice (F3) that replaces simplified invoices already issued.
InvoiceData::make('Order 7, with your details')
->to(Recipient::spanish('A15022510', 'Acme S.L.'))
->lines([TaxLine::vat(20000, rate: 21)])
->replacing($simplifiedInvoice);
// A corrective invoice for the difference: R1, or R5 when the original is simplified.
InvoiceData::make('Refund of 10.00 on order 42')
->to(Recipient::spanish('A15022510', 'Acme S.L.'))
->lines([TaxLine::vat(-1000, rate: 21)])
->correcting($original);
A corrective invoice is a new invoice: a new row of your invoice model whose toVerifactu() calls correcting(). Its lines are the change, negative to lower the original. replacing() and correcting() take your issued models and read their number and issue date.
The package doesn't judge the invoice: the service does. It sends what toVerifactu() describes, and whatever the service refuses comes back with the service's error code: an invoice with no lines or more than 12 (invalid_lines), a recipient on a simplified invoice (recipient_not_allowed), a reference to an original not issued yet… Sent with sendToVerifactu(), that is InvoiceNotIssued with the code; from a direct call, a VerifactuException.
Issuing invoices
$invoice->sendToVerifactu();
The invoice is sent from a queued job once the database transaction around the call commits, so it carries everything the transaction saved. When the service answers, the job stores the number, date, QR code and verification URL in the model's columns, sets the status to pending and fires InvoiceIssued. AEAT's answer arrives later by webhook.
The job retries a service that is down or busy for up to 24 hours, with the same Idempotency-Key, so an invoice is never issued twice. Sending an invoice that is already on the service stores the invoice the service holds instead of issuing a second one. If the service refuses the invoice, the job fires InvoiceNotIssued with the service's error code and message.
Run the jobs on a real queue. On the sync queue a job can't wait to retry, so a failure is lost.
$invoice->isOnVerifactu(); // issued on the service
$invoice->verifactu_status; // InvoiceStatus::Pending, Accepted, AcceptedWithErrors, Rejected or Cancelled
$invoice->refreshFromVerifactu(); // reads the invoice from the service and stores it
To print the QR code in HTML:
<img src="data:image/png;base64,{{ $invoice->qr_code }}" alt="QR">
Batches
use Vlec\Verifactu\Facades\Verifactu;
Verifactu::sendBatch($invoices);
Sends the invoices as one batch from a queued job, after the transaction commits. Invoices already on the service, and an invoice passed twice, are left out. When the batch is done, each issued invoice is stored and fires InvoiceIssued, each one the service refused fires InvoiceNotIssued with its error code, and the batch fires InvoiceBatchCompleted.
The service judges each invoice on its own: one it refuses doesn't stop the others.
Don't change the invoices while their batch is being sent. If the first answer is lost and an invoice changed before the retry, the service refuses the retry, and every invoice of the batch fires InvoiceNotIssued. Sending them again stores the invoices the service did issue.
A batch whose completion webhook is missed, or arrives before the job has stored the batch, is applied by the next verifactu:refresh-pending.
Fixing and cancelling
$invoice->correctOnVerifactu('Spanish course, B2');
$invoice->cancelOnVerifactu();
correctOnVerifactu() sends AEAT a new record of the same invoice, which keeps its number, date and amounts. It fixes the description after a rejection or an acceptance with errors. Without a description it sends the same record again, after a technical rejection. Wrong amounts, a wrong rate or the wrong customer need a corrective invoice instead.
cancelOnVerifactu() tells AEAT the invoice should never have been issued, such as a duplicate. A refunded sale is not cancelled: it needs a corrective invoice.
Both call the service at once, not from a queue, and store the status pending. AEAT's answer arrives by webhook. Call them after your database transaction commits: a call inside a transaction that rolls back would leave the service changed and your app not.
A refusal throws a VerifactuException. Branch on its errorCode, never on the message:
use Vlec\Verifactu\Exceptions\VerifactuException;
try {
$invoice->cancelOnVerifactu();
} catch (VerifactuException $exception) {
// invoice_awaiting_aeat: AEAT has not answered for the last record yet; try again later.
// invoice_cancelled: the invoice is cancelled already.
return back()->withErrors(['invoice' => $exception->getMessage()]);
}
The exception carries status, errorCode, errors (the fields the service refused) and retryAfter. A service that doesn't answer throws too, after the configured retries, and the stored status stays as it was. The next webhook settles what happened, or call $invoice->refreshFromVerifactu().
Events
| Event | Fires when | Carries |
|---|---|---|
InvoiceIssued |
The service issued the invoice and its columns are stored | invoice |
InvoiceNotIssued |
The service refused the invoice, or never answered in 24 hours | invoice, errorCode, message |
InvoiceAccepted |
AEAT accepted it | invoice |
InvoiceAcceptedWithErrors |
AEAT registered it with errors: it counts, but needs a fix | invoice, errorCode, errorMessage |
InvoiceRejected |
AEAT rejected it: fix it, or issue it again | invoice, errorCode, errorMessage |
InvoiceCancelled |
AEAT registered its cancellation | invoice |
InvoiceBatchCompleted |
A batch is done and each of its invoices was stored | batch, total, succeeded, failed |
They live in Vlec\Verifactu\Events. A status event fires only when the stored status changes. AEAT's error code and message (in Spanish) stay on the event, not in a column.
use Illuminate\Support\Facades\Event;
use Vlec\Verifactu\Events\InvoiceIssued;
use Vlec\Verifactu\Events\InvoiceRejected;
Event::listen(InvoiceIssued::class, SendInvoicePdf::class);
Event::listen(InvoiceRejected::class, NotifyAccounts::class);
Make listeners queued (ShouldQueue), so one that fails doesn't stop the events after it, and safe to run twice:
- When an invoice sent again is already decided by AEAT, its status event (
InvoiceAccepted…) fires beforeInvoiceIssued. - If storing a batch's results fails halfway, the batch is applied again later, and its refused invoices fire
InvoiceNotIssueda second time. - If storing an issued invoice keeps failing for 24 hours (a missing column),
InvoiceNotIssuedfires for an invoice AEAT has. Running the migration before sending avoids it.
Webhooks
The package registers POST /verifactu/webhook (config('verifactu.webhook_path')), named verifactu.webhook. Give its full URL to an administrator of the service, who sets it on your app's page. verifactu:install and php artisan about print it.
The route is outside the web group, so it needs no CSRF exemption. Each delivery's signature is checked against VERIFACTU_WEBHOOK_SECRET; a wrong or stale one gets 403. For each invoice in the delivery, the package reads the invoice from the service and stores it, so the newest state always wins, whatever order deliveries arrive in. Invoices it doesn't know are skipped.
A webhook can be missed, such as while the app is down. Schedule the catch-up in routes/console.php:
use Illuminate\Support\Facades\Schedule;
Schedule::command('verifactu:refresh-pending')->hourly();
Tax-ID checks
Check a Spanish customer's tax ID and name with AEAT before issuing to them:
use Vlec\Verifactu\TaxIdCheckResult;
$check = Verifactu::checkTaxId('A15022510', 'Acme S.L.');
$check->result; // TaxIdCheckResult::Identified, Similar, NotIdentified, Deregistered, Revoked, NotProcessed or NotChecked
$check->officialName; // the name AEAT holds, when the result is Similar
Or validate a form with the KnownToAeat rule, naming the field that holds the customer's name:
use Vlec\Verifactu\Rules\KnownToAeat;
$request->validate([
'legal_name' => ['required', 'string', 'max:120'],
'tax_id' => ['bail', 'required', 'string', new KnownToAeat(nameField: 'legal_name')],
]);
- It refuses a tax ID AEAT doesn't know under that name, or knows as deregistered or revoked, and one the service finds malformed.
- When AEAT holds a similar name, it fails on the name field, with the official name.
- When AEAT or the service can't answer, it passes: the invoice is checked again when it is issued. A refusal that isn't an outage, such as a refused token, passes too, and is reported.
- Put it last, after
bail, so it calls the service only once the rest of the field is valid. Other fields' rules don't stop it. - The name field is a top-level field, or a fixed dotted one (
customer.legal_name). A wildcard (customers.*.legal_name) checks nothing.
Its messages go through Laravel's translator. For Spanish, add them to lang/es.json:
{
"AEAT does not accept this tax ID with this name.": "AEAT no acepta este NIF con este nombre.",
"AEAT holds this tax ID as: :name": "AEAT tiene este NIF como: :name",
"This is not a valid Spanish tax ID.": "Este NIF no es válido.",
"AEAT does not take this name.": "AEAT no admite este nombre."
}
Calling the API directly
The Verifactu facade has a method for each operation the package uses. They take the API's arrays, retry as the config says, and throw VerifactuException. An invoice or a batch comes back as the resource itself (['uuid' => …, 'status' => …]); listInvoices() and listInvoiceBatchItems() return the page, with data and meta; checkTaxId() returns a TaxIdCheck.
Verifactu::createInvoice($body);
Verifactu::getInvoice($uuid);
Verifactu::listInvoices(['filter' => ['external_reference' => 'invoice:42']]);
Verifactu::correctInvoice($uuid, $body);
Verifactu::cancelInvoice($uuid);
Verifactu::createInvoiceBatch($body);
Verifactu::getInvoiceBatch($uuid);
Verifactu::listInvoiceBatchItems($uuid, page: 2);
Verifactu::checkTaxId($taxId, $name);
For the other endpoints, such as a month's AEAT XML, Verifactu::http() gives Laravel's HTTP client with the base URL, token, timeouts and retries set. It doesn't throw on its own:
$submissions = Verifactu::http()
->get('exports/xml', ['year' => 2026, 'month' => 11])
->throw()
->json('data');
Testing
Verifactu::fake() replaces the service with an in-memory one that answers as the service does: it numbers invoices in order (FACT1, FACT2…), completes batches at once, and refuses what the service refuses. Your tests run the package's real jobs, model methods and events, with no HTTP.
use Illuminate\Support\Facades\Event;
use Vlec\Verifactu\Events\InvoiceAccepted;
use Vlec\Verifactu\Facades\Verifactu;
use Vlec\Verifactu\InvoiceStatus;
it('issues the invoice and stores AEAT\'s acceptance', function () {
Event::fake([InvoiceAccepted::class]);
Verifactu::fake();
$invoice = Invoice::factory()->create();
$invoice->sendToVerifactu();
Verifactu::decide($invoice, InvoiceStatus::Accepted);
Verifactu::assertIssued($invoice);
Event::assertDispatched(InvoiceAccepted::class);
expect($invoice->fresh()->verifactu_status)->toBe(InvoiceStatus::Accepted);
});
- The jobs must run inside the test, on the
syncqueue (the default inphpunit.xml), not withQueue::fake(). CallVerifactu::fake()before any catch-allHttp::fake(). decide($invoice, $status, errorCode: '1105', errorMessage: '…')plays AEAT's answer, as a webhook would:Accepted,AcceptedWithErrorsorRejected, orCancelledaftercancelOnVerifactu().taxIdCheck(TaxIdCheckResult::NotIdentified)sets the answer to every later tax-ID check (Similartakes the official name too). WithNotIdentified, issuing to a Spanish tax ID is refused withrecipient_not_identified, as the service does.- Assertions:
assertIssued($invoice, ?fn (array $body): bool),assertNothingIssued(),assertBatchSent(),assertCorrected($invoice)andassertCancelled($invoice).
Verifactu::assertIssued($invoice, fn (array $body): bool => $body['total_amount'] === '300.00');
Commands
| Command | What it does |
|---|---|
verifactu:install |
The install wizard. Running it again adds no second set of keys or migration |
verifactu:status |
Checks the connection and the token's environment, and counts the invoices by status |
verifactu:refresh-pending |
Refreshes invoices pending for over an hour, and applies batches not applied yet. Schedule it hourly |
verifactu:correct {invoice} {--description=} |
correctOnVerifactu() from the command line, by the invoice's key |
php artisan about shows the service's URL, the environment, the invoice model and the webhook URL. It never shows the token or the secret.
Upgrading
Until 1.0.0, a minor version (0.1 → 0.2) may change the public API: require ^0.1 and read the changelog before moving up. When a release adds a migration or a config key, its changelog entry says how to add it. Don't publish verifactu-migrations again: publishing renames the migration to the time it runs, so it would add a second copy of the batches table.
License
The MIT License (MIT). Please see License File for more information.