FiscalIdentifier and ForeignFiscalIdentifier classes

Verifactu-PHP provides two identifier classes for invoice parties. FiscalIdentifier represents Spanish entities identified by a domestic NIF, and is used wherever a Spanish fiscal identity is required — the taxpayer, a representative, or a domestic invoice recipient. ForeignFiscalIdentifier handles entities outside Spain and carries the additional country code and identification type required by the AEAT schema for foreign parties.

FiscalIdentifier

Namespace: josemmo\Verifactu\Models\Records\FiscalIdentifier Represents a Spanish fiscal entity by legal name and NIF. Used as the $taxpayer and $representative arguments of AeatClient, and as the domestic recipient in RegistrationRecord.

Constructor

public function __construct(
    ?string $name = null,
    ?string $nif  = null,
)

Both parameters are optional. Any non-null argument is written to the corresponding property immediately.

name

string | null

default:"null"

Legal name or trade name of the entity. Sets $this->name when provided.

nif

string | null

default:"null"

Spanish tax identification number. Sets $this->nif when provided.

Properties

name

string

required

Legal name or trade name (nombre-razón social).

Must not be blank
Maximum 120 characters
Corresponds to XML field NombreRazon

nif

string

required

Spanish NIF of the entity.

Must not be blank
Exactly 9 characters
Corresponds to XML field NIF

Typical uses

Context	Argument name
`AeatClient` constructor	`$taxpayer`
`AeatClient::setRepresentative()`	`$representative`
`RegistrationRecord` domestic recipient	depends on record type

ForeignFiscalIdentifier

Namespace: josemmo\Verifactu\Models\Records\ForeignFiscalIdentifier Represents a non-Spanish entity identified by a country code, an ID type, and the ID value itself. Used in RegistrationRecord when the invoice recipient is a foreign party.

Constructor

public function __construct(
    ?string $name    = null,
    ?string $country = null,
    ?ForeignIdType $type = null,
    ?string $value   = null,
)

All parameters are optional; any non-null argument is written to the corresponding property.

name

string | null

default:"null"

Legal name of the entity. Sets $this->name when provided.

country

string | null

default:"null"

ISO 3166-1 alpha-2 country code (e.g. "FR", "DE"). Sets $this->country when provided.

type

ForeignIdType | null

default:"null"

Identification type enum case. Sets $this->type when provided.

value

string | null

default:"null"

The actual identification number or document value. Sets $this->value when provided.

Properties

name

string

required

Legal name or trade name of the foreign entity.

Must not be blank
Maximum 120 characters
Corresponds to XML field NombreRazon

country

string

required

ISO 3166-1 alpha-2 country code in uppercase.

Must not be blank
Matches regex /^[A-Z]{2}$/
Corresponds to XML field IDOtro/CodigoPais

type

ForeignIdType

required

The type of identification document or number.

Must not be blank
Corresponds to XML field IDOtro/IDType

value

string

required

The identification number or document reference.

Must not be blank
Maximum 20 characters
Corresponds to XML field IDOtro/ID

ForeignIdType enum

josemmo\Verifactu\Models\Records\ForeignIdType is a backed string enum:

Case	Raw value	Description
`VAT`	`02`	NIF-IVA (VAT number)
`Passport`	`03`	Pasaporte
`NationalId`	`04`	Official national ID issued by the country of residence
`Residence`	`05`	Certificado de residencia
`Other`	`06`	Other proof document
`Unregistered`	`07`	Not yet registered with AEAT — must be corrected later

Using ForeignIdType::Unregistered obliges you to submit a correction record once the entity has been registered with AEAT.

Validation rules

The following cross-field rules are enforced by validate() in addition to per-property constraints:

Show VAT number country prefix rule

When type is ForeignIdType::VAT, the first two characters of value must equal country. For example, a French VAT number must begin with FR.

Show Spanish entity rule

When country is ES, type must be either ForeignIdType::Passport or ForeignIdType::Unregistered. Using any other type for a Spanish-country entity raises a validation error.

Show Unregistered type rule

When type is ForeignIdType::Unregistered, country must be ES. This type is reserved exclusively for entities pending registration with AEAT.

Code examples

use josemmo\Verifactu\Models\Records\FiscalIdentifier;
use josemmo\Verifactu\Models\Records\ForeignFiscalIdentifier;
use josemmo\Verifactu\Models\Records\ForeignIdType;

// --- FiscalIdentifier (Spanish entity) ---

// Constructor shorthand
$taxpayer = new FiscalIdentifier('Empresa Ejemplo S.A.', 'A87654321');

// Property assignment (equivalent)
$taxpayer = new FiscalIdentifier();
$taxpayer->name = 'Empresa Ejemplo S.A.';
$taxpayer->nif  = 'A87654321';   // exactly 9 characters
$taxpayer->validate();


// --- ForeignFiscalIdentifier (non-Spanish entity with VAT number) ---
$customer = new ForeignFiscalIdentifier(
    'Société Française SARL',
    'FR',
    ForeignIdType::VAT,
    'FR12345678901',  // must start with 'FR'
);
$customer->validate();


// --- ForeignFiscalIdentifier (entity with passport) ---
$individual = new ForeignFiscalIdentifier(
    'John Smith',
    'GB',
    ForeignIdType::Passport,
    'GB123456789',
);
$individual->validate();


// --- ForeignFiscalIdentifier (unregistered Spanish individual) ---
$unregistered = new ForeignFiscalIdentifier(
    'María García López',
    'ES',                         // must be 'ES' for Unregistered type
    ForeignIdType::Unregistered,
    '00000000T',
);
$unregistered->validate();

Services

Models

Records

Enumerations

Responses & Exceptions

FiscalIdentifier and ForeignFiscalIdentifier classes