Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Eseperio/verifactu-php/llms.txt

Use this file to discover all available pages before exploring further.

InvoiceQuery (XSD base: ConsultaFactuSistemaFacturacionType) defines the filter parameters for querying invoice records from AEAT. It extends the abstract Model class directly (not InvoiceRecord). 
use eseperio\verifactu\models\InvoiceQuery;

$query = new InvoiceQuery();
Pass a populated instance to Verifactu::queryInvoices(), which returns a QueryResponse.

​
Properties

​
Required fields

​
year
string
required
The fiscal year to query (Ejercicio). Four-digit year string. Example: '2025'
​
period
string
required
The period within the year (Periodo). Typically a two-digit month string. Example: '01' for January, '12' for December.

​
Optional filter fields

​
seriesNumber
string
Filters results to invoices matching this series + number (NumSerieFactura, optional). Example: 'A-2025/001'
​
issueDate
string
Filters results to invoices with this issue date (FechaExpedicionFactura, optional). Format: YYYY-MM-DD.
​
externalRef
string
Filters by the external reference stored on the record (RefExterna, optional). Must match the value set via InvoiceSubmission::$externalRef at submission time.

​
Methods

​
setIssuerparty(string $nif, string|null $name = null): static

Sets the issuer party (ObligadoEmision) for the query header. This method must be called before submitting the query — the XML serialiser includes the issuer party unconditionally and will fail without it. The $name parameter is optional but recommended. 
$query->setIssuerparty('B12345678');

// With name
$query->setIssuerparty('B12345678', 'Mi Empresa S.L.');
​
nif
string
required
The NIF of the issuing party to filter on.
​
name
string
Optional name of the issuing party.
Use getIssuerparty() to read back the stored array.

​
setCounterparty(string $nif, string|null $name = null): static

Sets the counterparty (recipient) filter (Contraparte, optional). Restricts results to invoices issued to the specified recipient NIF. 
$query->setCounterparty('A87654321');

// With name
$query->setCounterparty('A87654321', 'Client Corp S.A.');
​
nif
string
required
The NIF of the recipient to filter on.
​
name
string
Optional name of the recipient.
Use getCounterparty() to read back the stored array.

​
setSystemInfo(string $system, string $version): static

Restricts the query to records from a specific billing software (SistemaInformatico, optional). Both the system name and version must match what was submitted with the original records. 
$query->setSystemInfo('MyERP', '2.0.0');
​
system
string
required
The billing system name (NombreSistemaInformatico).
​
version
string
required
The billing system version (Version).
Use getSystemInfo() to read back the stored array.

​
setPaginationKey(int $page, int $size): static

Sets the pagination control values (ClavePaginacion) for retrieving subsequent pages of results. Pass the page number and page size to advance through large result sets. 
// First page
$result = Verifactu::queryInvoices($query);

// If more results exist, fetch the next page
if ($result->paginationIndicator === 'S') {
    $query->setPaginationKey(1, 10); // page number and page size
    $nextResult = Verifactu::queryInvoices($query);
}
​
page
int
required
The page number to retrieve (1-based).
​
size
int
required
The number of records per page.
Use getPaginationKey() to read back the stored array.

​
validate(): array

Validates the query properties. Returns an empty array when year and period are present and all other set properties are the correct types. Returns an error array otherwise.

​
QueryResponse fields

Verifactu::queryInvoices() returns a QueryResponse object. The most important properties are:
​
queryResult
string
Overall result of the query (ResultadoConsulta). Common values:
ValueMeaning
'ConDatos'Records were found matching the query
'SinDatos'No records matched the query criteria
​
foundRecords
array
Array of matching invoice record objects (RegistroRespuestaConsultaFactuSistemaFacturacion). Each element is an associative array of the raw AEAT response fields. May be null or empty when queryResult is 'SinDatos'.
​
paginationIndicator
string
Pagination indicator (IndicadorPaginacion). Set to 'S' when there are more pages of results available.
​
paginationKey
array
Raw pagination cursor data (ClavePaginacion) returned by AEAT. This is the raw XML-to-array representation of the last record seen. Only present when paginationIndicator is 'S'. To fetch the next page, call $query->setPaginationKey($nextPage, $pageSize) with your desired page number and size.
​
header
array
Response header data (Cabecera) from AEAT. Contains metadata about the query response.
​
period
array
Period to which the found records belong (PeriodoImputacion).

​
Complete example

<?php

use eseperio\verifactu\Verifactu;
use eseperio\verifactu\models\InvoiceQuery;

// Basic query — all invoices for January 2025
$query = new InvoiceQuery();
$query->year   = '2025';
$query->period = '01';
$query->setIssuerparty('B12345678', 'Mi Empresa S.L.');

$result = Verifactu::queryInvoices($query);

if ($result->queryResult === 'SinDatos') {
    echo 'No invoices found for this period.';
} else {
    echo 'Found ' . count($result->foundRecords ?? []) . " invoices:\n";
    foreach ($result->foundRecords as $record) {
        echo '  - ' . ($record['IDFactura']['NumSerieFactura'] ?? '?') . "\n";
    }
}

// Paginated iteration
$allRecords = $result->foundRecords ?? [];
$page = 1;
$pageSize = 10;

while ($result->paginationIndicator === 'S') {
    $page++;
    $query->setPaginationKey($page, $pageSize);
    $result = Verifactu::queryInvoices($query);
    $allRecords = array_merge($allRecords, $result->foundRecords ?? []);
}

echo 'Total records retrieved: ' . count($allRecords) . "\n";

<?php
// Filtered query — specific invoice + counterparty
$query = new InvoiceQuery();
$query->year         = '2025';
$query->period       = '03';
$query->seriesNumber = 'A-2025/042';
$query->setIssuerparty('B12345678');
$query->setCounterparty('A87654321');

$result = Verifactu::queryInvoices($query);

Build docs developers (and LLMs) love

Get started for freeTalk to us