Skip to main content

Documentation Index

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

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

ClienteVerifactu is the main entry point for the verifactuPHP library. It handles authentication against the VeriFactuAPI automatically on construction, manages the Bearer token lifecycle, and exposes every available API operation — from building invoice objects through factory methods to submitting and querying records via the REST API. All HTTP communication is performed internally using Guzzle, so you interact only with clean PHP objects and method calls.

​
Constructor

new ClienteVerifactu(string $email, string $password)
Instantiates the client and immediately authenticates with the VeriFactuAPI by calling the internal logIn() method. The resulting Bearer token is stored and used automatically for all subsequent requests.
​
email
string
required
Your VeriFactuAPI account email address.
​
password
string
required
Your VeriFactuAPI account password.
The constructor throws an Exception if authentication fails (e.g. invalid credentials or a network error). Wrap instantiation in a try/catch block in production code.
use verifactuPHP\ClienteVerifactu;

$client = new ClienteVerifactu('user@example.com', 'secret');

​
Configuration Methods

These methods let you read and update the core configuration of the client instance after construction.

​
getApiURL(): string

Returns the base API URL used for all requests. 
echo $client->getApiURL();
// https://app.verifactuapi.es/api

​
getEmail(): string / setEmail(string $newValue): void

Gets or replaces the email address stored on the client. 
$email = $client->getEmail();

$client->setEmail('other@example.com');

​
getPassword(): string / setPassword(string $newValue): void

Gets or replaces the password stored on the client. 
$password = $client->getPassword();

$client->setPassword('newSecret');

​
getToken(): string

Returns the current Bearer token that was issued by the API during the last successful login. Useful for debugging or for passing the token to a separate HTTP client. 
echo $client->getToken();
// eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...

​
getDebug(): bool / setDebug(bool $newValue): void

Gets or sets debug mode. When true, the client echoes internal messages (tokens, request results, created object data) to standard output. Disable in production. 
$client->setDebug(true);   // enable verbose output
$client->setDebug(false);  // disable (default)

$isDebug = $client->getDebug(); // bool
Debug mode is false by default. Enable it temporarily during development to inspect requests and object payloads.

​
Object Factory Methods

These methods construct the PHP model objects that represent the different components of a VeriFactu invoice. Each factory validates the supplied array and returns a typed object ready to be passed to a submission method.

​
nuevoEmisor(array $dataEmisor): Emisor

Creates an Emisor (issuer) object representing the business or individual issuing the invoice.
​
dataEmisor
array
required
Associative array containing the issuer’s data fields (e.g. NIF, name, address). See the Emisor model reference for the full list of accepted keys.
Returns: Emisor 
$emisor = $client->nuevoEmisor([
    'nif'    => 'B12345678',
    'nombre' => 'Mi Empresa S.L.',
    // ...additional fields
]);

​
nuevoDestinatario(array $dataDestinatario): Destinatario

Creates a Destinatario (recipient) object representing the invoice recipient.
​
dataDestinatario
array
required
Associative array containing the recipient’s identification and address data.
Returns: Destinatario 
$destinatario = $client->nuevoDestinatario([
    'nombreRazon' => 'Cliente S.A.',
    'nif'         => 'A87654321',
    // ...additional fields
]);

​
nuevoTercero(array $dataTercero): Tercero

Creates a Tercero (third party) object, used when a third party is involved in the invoicing process.
​
dataTercero
array
required
Associative array containing the third party’s identification data.
Returns: Tercero 
$tercero = $client->nuevoTercero([
    'tercNombreRazon' => 'Tercero S.L.',
    'tercNIF'         => 'C11111111',
    // ...additional fields
]);

​
nuevoDesglose(array $dataDesglose): Desglose

Creates a Desglose (tax breakdown) object that captures the VAT and tax details for a line or invoice total.
​
dataDesglose
array
required
Associative array with tax breakdown fields such as tax type, rate, taxable base, and quota.
Returns: Desglose 
$desglose = $client->nuevoDesglose([
    'tipoImpositivo'                => 21.0,
    'baseImponibleOImporteNoSujeto' => 1000.00,
    'cuotaRepercutida'              => 210.00,
    // ...additional fields
]);

​
nuevaFacturaRectificada(array $dataFacturaRectificada): FacturaRectificada

Creates a FacturaRectificada object representing an invoice being corrected (referenced in a rectification invoice).
​
dataFacturaRectificada
array
required
Associative array with the identifying details of the original invoice being rectified.
Returns: FacturaRectificada 
$facturaRectificada = $client->nuevaFacturaRectificada([
    'IDEmisorFactura'        => 'B12345678',
    'NumSerieFactura'        => 'FAC-2024-001',
    'FechaExpedicionFactura' => '01-01-2024',
]);

​
nuevaFacturaSustituida(array $dataFacturaSustituida): FacturaSustituida

Creates a FacturaSustituida object representing an invoice being replaced (used in substitution invoices).
​
dataFacturaSustituida
array
required
Associative array with the identifying details of the original invoice being substituted.
Returns: FacturaSustituida 
$facturaSustituida = $client->nuevaFacturaSustituida([
    'IDEmisorFactura'        => 'B12345678',
    'NumSerieFactura'        => 'FAC-2024-002',
    'FechaExpedicionFactura' => '15-01-2024',
]);

​
nuevoRegistroAlta(array $objetos, array $dataRegistroAlta, int $webhookID = 0): RegistroAlta

Creates a RegistroAlta (invoice registration record) object — the main payload submitted to the AEAT. Pass all previously constructed model objects in the $objetos array.
​
objetos
array
required
Array of model objects to embed in the registration record. May include Emisor, Destinatario, Tercero, Desglose, FacturaRectificada, and/or FacturaSustituida instances.
​
dataRegistroAlta
array
required
Associative array with the top-level invoice fields (e.g. series number, issue date, invoice type, total amounts).
​
webhookID
int
Optional ID of a webhook to associate with this record. Defaults to 0 (no webhook).
Returns: RegistroAlta 
$registro = $client->nuevoRegistroAlta(
    [$emisor, $destinatario, $desglose],
    [
        'NumSerieFactura'        => 'FAC-2024-010',
        'FechaExpedicionFactura' => '30-06-2024',
        // ...additional fields
    ],
    $webhookID
);

​
nuevoRegistroAnulacion(array $dataRegistroAnulacion): RegistroAnulacion

Creates a RegistroAnulacion (cancellation record) object used to void a previously submitted invoice registration.
​
dataRegistroAnulacion
array
required
Associative array identifying the registration record to be cancelled (issuer NIF, series number, issue date, etc.).
Returns: RegistroAnulacion 
$anulacion = $client->nuevoRegistroAnulacion([
    'IDEmisorFactura'        => 'B12345678',
    'NumSerieFactura'        => 'FAC-2024-010',
    'FechaExpedicionFactura' => '30-06-2024',
]);

​
Submission Methods

These methods POST the constructed objects to the VeriFactuAPI. They all return void on success and throw an Exception on failure.
All submission methods throw an Exception if the API returns an error response or if a network problem occurs. Always wrap calls in a try/catch block.

​
altaEmisor(Emisor $emisor): void

Registers a new issuer in the system.
  • Endpoint: POST /api/emisor
​
emisor
Emisor
required
A fully constructed Emisor object returned by nuevoEmisor().
$client->altaEmisor($emisor);

​
altaRegistroAlta(RegistroAlta $registroAlta): void

Submits an invoice registration record to the AEAT via VeriFactuAPI.
  • Endpoint: POST /api/alta-registro-facturacion
​
registroAlta
RegistroAlta
required
A fully constructed RegistroAlta object returned by nuevoRegistroAlta().
$client->altaRegistroAlta($registro);

​
altaRegistroAnulacion(RegistroAnulacion $registroAnulacion): void

Submits a cancellation record to void a previously submitted invoice.
  • Endpoint: POST /api/anulacion-registro-facturacion
​
registroAnulacion
RegistroAnulacion
required
A fully constructed RegistroAnulacion object returned by nuevoRegistroAnulacion().
$client->altaRegistroAnulacion($anulacion);

​
bajaRegistro(int $id): void

Cancels a specific registration record by its numeric ID.
  • Endpoint: POST /api/anulacion-registro-facturacion/{id}
​
id
int
required
The integer ID of the registration record to cancel.
$client->bajaRegistro(42);

​
Listing Methods

These methods perform GET requests to retrieve records from the API. All return an array decoded from the API’s JSON response. Pass an integer $id to fetch a single record, or omit it (pass null) to retrieve all records of that type.

​
listarEmisores(?int $id = null): array

Lists all registered issuers, or retrieves a single issuer by ID.
  • Endpoint: GET /api/emisor or GET /api/emisor/{id}
$todos   = $client->listarEmisores();      // all issuers
$uno     = $client->listarEmisores(5);     // issuer with ID 5

​
listarEnviosAEAT(?int $id = null): array

Lists all AEAT submission records, or retrieves one by ID.
  • Endpoint: GET /api/envios-aeat or GET /api/envios-aeat/{id}
$envios = $client->listarEnviosAEAT();     // all submissions
$envio  = $client->listarEnviosAEAT(10);  // submission with ID 10

​
listarRegistrosAlta(?int $id = null): array

Lists all invoice registration records, or retrieves one by ID.
  • Endpoint: GET /api/alta-registro-facturacion or GET /api/alta-registro-facturacion/{id}
$registros = $client->listarRegistrosAlta();     // all records
$registro  = $client->listarRegistrosAlta(7);    // record with ID 7

​
listarListas(string $nombre = '', string $valor = ''): array

Queries the API reference lists (lookup tables). Filter by list name and optionally by a specific value within that list.
  • Endpoint: GET /api/listas / GET /api/listas/{nombre} / GET /api/listas/{nombre}/{valor}
​
nombre
string
The name of the list to retrieve. Leave empty to get all lists.
​
valor
string
A specific value to look up within the named list. Only used when nombre is also provided.
$todasLasListas = $client->listarListas();
$unaLista       = $client->listarListas('TipoFactura');
$unValor        = $client->listarListas('TipoFactura', 'F1');

​
listarWebhooks(?int $id = null): array

Lists all registered webhooks, or retrieves one by ID.
  • Endpoint: GET /api/webhook or GET /api/webhook/{id}
$webhooks = $client->listarWebhooks();     // all webhooks
$webhook  = $client->listarWebhooks(3);   // webhook with ID 3

​
Utility Methods

​
createWebhook(string $webhookUrl): int

Registers a new webhook endpoint with the API. The webhook will receive POST notifications when invoice records are processed.
​
webhookUrl
string
required
The publicly accessible HTTPS URL that the VeriFactuAPI should call when events occur.
Returns: int — The numeric ID of the newly created webhook. 
$webhookID = $client->createWebhook('https://myapp.example.com/webhook');
echo $webhookID; // e.g. 12
Store the returned webhook ID if you intend to pass it to nuevoRegistroAlta() so the API can notify your endpoint when the submission is processed.

​
idValorLista(string $nombreLista, string $valorLista): int

Resolves a human-readable list value (e.g. 'F1') to its internal numeric ID in the API’s lookup tables. Useful when building data arrays for model objects that require integer IDs rather than string codes.
​
nombreLista
string
required
The name of the reference list to query (e.g. 'TipoFactura').
​
valorLista
string
required
The string value within that list whose ID you want to look up (e.g. 'F1').
Returns: int — The numeric ID corresponding to the given list value. 
$id = $client->idValorLista('TipoFactura', 'F1');
echo $id; // e.g. 3

​
Error Handling

Every public method in ClienteVerifactu throws a standard PHP Exception when an error occurs — including authentication failures in the constructor, API error responses, and unexpected network issues. The exception message contains a descriptive explanation of the failure returned by the API or by Guzzle. 
try {
    $client->altaRegistroAlta($registro);
} catch (Exception $e) {
    echo 'Error: ' . $e->getMessage();
}
Enable debug mode with $client->setDebug(true) during development to see detailed output for every request and response before investing in full exception handling.

Build docs developers (and LLMs) love

Get started for freeTalk to us