FacturaScripts

Vies
in package

Cliente para el servicio VIES (VAT Information Exchange System) de la Comisión Europea, que permite verificar la validez de un número de IVA intracomunitario.

Uso típico:

$result = Vies::check('B12345678', 'ES');
if ($result === Vies::RESULT_VALID) { ... }

La consulta se hace por SOAP contra ec.europa.eu y por tanto requiere la extensión soap de PHP y conectividad de red. Para pruebas unitarias se puede cortocircuitar la llamada con Vies::simulateViesResponse().

Tags

Daniel Fernández Giménez [email protected]

Table of Contents

Constants

EU_COUNTRIES  : mixed = ['AT', 'BE', 'BG', 'CY', 'CZ', 'DE', 'DK', 'EE'...
Códigos ISO aceptados por VIES (UE + XI para Irlanda del Norte tras el Brexit).
RESULT_ERROR  : mixed = -1
No se ha podido comprobar (extensión SOAP ausente, país no UE, red caída, etc.).
RESULT_INVALID  : mixed = 0
El número de IVA tiene formato correcto pero VIES lo da por inválido o inexistente.
RESULT_VALID  : mixed = 1
El número de IVA existe y está activo en el país indicado.
VIES_TIMEOUT  : mixed = 10
Timeout (en segundos) aplicado tanto a la conexión SOAP como al socket HTTP.
VIES_URL  : mixed = "https://ec.europa.eu/taxation_customs/vies/che...

Properties

$lastError  : mixed
Último mensaje de error devuelto por VIES, accesible mediante {@see getLastError()}.
$simulatedFetchResponse  : mixed
Respuesta simulada para {@see fetch()}; cuando es distinta de null se devuelve sin tocar la red.
$simulatedResponse  : mixed
Respuesta simulada para tests; cuando es distinta de null, {@see check()} la devuelve sin tocar la red.

Methods

check()  : int
Comprueba contra VIES si un número de IVA es válido en el país indicado.
fetch()  : array<string|int, mixed>|null
Consulta VIES y devuelve los datos del titular del NIF intracomunitario.
getLastError()  : string
Devuelve el mensaje de la última excepción capturada al hablar con VIES, o cadena vacía si la última llamada no produjo error de transporte/SOAP.
normalize()  : string
Normaliza un cifnif para enviarlo a VIES: lo pasa a mayúsculas, descarta separadores habituales (espacios, guiones, puntos, barras...) y, si el resultado empieza por el código ISO indicado, también lo elimina.
simulateFetchResponse()  : void
Fija una respuesta fija que {@see fetch()} devolverá sin tocar la red.
simulateViesResponse()  : void
Fija una respuesta fija que {@see check()} devolverá sin tocar la red.
fetchViesInfo()  : array<string|int, mixed>|null
Llama a VIES y devuelve un array con `valid`, `name` y `address`.
getViesInfo()  : int
prepare()  : string|null
Aplica las validaciones previas comunes a {@see check()} y {@see fetch()}: extensión SOAP disponible, código ISO con formato correcto y perteneciente a la UE, y longitud mínima del cifnif tras normalizar.
setMessage()  : void

Constants

EU_COUNTRIES

Códigos ISO aceptados por VIES (UE + XI para Irlanda del Norte tras el Brexit).

public mixed EU_COUNTRIES = ['AT', 'BE', 'BG', 'CY', 'CZ', 'DE', 'DK', 'EE', 'EL', 'ES', 'FI', 'FR', 'HR', 'HU', 'IE', 'IT', 'LT', 'LU', 'LV', 'MT', 'NL', 'PL', 'PT', 'RO', 'SE', 'SI', 'SK', 'XI']

RESULT_ERROR

No se ha podido comprobar (extensión SOAP ausente, país no UE, red caída, etc.).

public mixed RESULT_ERROR = -1

RESULT_INVALID

El número de IVA tiene formato correcto pero VIES lo da por inválido o inexistente.

public mixed RESULT_INVALID = 0

RESULT_VALID

El número de IVA existe y está activo en el país indicado.

public mixed RESULT_VALID = 1

VIES_TIMEOUT

Timeout (en segundos) aplicado tanto a la conexión SOAP como al socket HTTP.

public mixed VIES_TIMEOUT = 10

VIES_URL

public mixed VIES_URL = "https://ec.europa.eu/taxation_customs/vies/checkVatService.wsdl"

Properties

$lastError

Último mensaje de error devuelto por VIES, accesible mediante {@see getLastError()}.

private static mixed $lastError = ''

$simulatedFetchResponse

Respuesta simulada para {@see fetch()}; cuando es distinta de null se devuelve sin tocar la red.

private static mixed $simulatedFetchResponse = null

$simulatedResponse

Respuesta simulada para tests; cuando es distinta de null, {@see check()} la devuelve sin tocar la red.

private static mixed $simulatedResponse = null

Methods

check()

Comprueba contra VIES si un número de IVA es válido en el país indicado.

public static check(string $cifnif, string $codiso[, bool $msg = true ]) : int

El cifnif se normaliza antes de enviarlo (ver normalize()), por lo que admite indistintamente "B12345678", "ES-B12345678" o "es b12345678".

Parameters
$cifnif : string

número de IVA (con o sin prefijo ISO)

$codiso : string

código ISO de país en mayúsculas y dos caracteres

$msg : bool = true

si true, registra warnings en el log ante errores de validación

Return values
int —

uno de Vies::RESULT_VALID, Vies::RESULT_INVALID o Vies::RESULT_ERROR

fetch()

Consulta VIES y devuelve los datos del titular del NIF intracomunitario.

public static fetch(string $cifnif, string $codiso[, bool $msg = true ]) : array<string|int, mixed>|null

Junto al flag valid se incluye razón social y dirección si el país las publica (varios estados miembros las devuelven vacías por privacidad).

Parameters
$cifnif : string

número de IVA (con o sin prefijo ISO)

$codiso : string

código ISO de país en mayúsculas y dos caracteres

$msg : bool = true

si true, registra warnings en el log ante errores de validación

Return values
array<string|int, mixed>|null —

array con claves valid (bool), name (string), address (string), o null si no se pudo completar la consulta

getLastError()

Devuelve el mensaje de la última excepción capturada al hablar con VIES, o cadena vacía si la última llamada no produjo error de transporte/SOAP.

public static getLastError() : string
Return values
string

normalize()

Normaliza un cifnif para enviarlo a VIES: lo pasa a mayúsculas, descarta separadores habituales (espacios, guiones, puntos, barras...) y, si el resultado empieza por el código ISO indicado, también lo elimina.

public static normalize(string $cifnif, string $codiso) : string

El codiso debe llegar ya en mayúsculas; si no, no se reconocerá como prefijo y se enviará tal cual a VIES.

Parameters
$cifnif : string

valor original tal como lo introduce el usuario

$codiso : string

código ISO de país en mayúsculas

Return values
string —

cifnif normalizado, sin prefijo ISO

simulateFetchResponse()

Fija una respuesta fija que {@see fetch()} devolverá sin tocar la red.

public static simulateFetchResponse(array<string|int, mixed>|null $response) : void

Pensado exclusivamente para tests; pasar null para restaurar el comportamiento real.

Parameters
$response : array<string|int, mixed>|null

array con claves valid/name/address (o null en errores), o null para desactivar

simulateViesResponse()

Fija una respuesta fija que {@see check()} devolverá sin tocar la red.

public static simulateViesResponse(int|null $response) : void

Pensado exclusivamente para tests; pasar null para restaurar el comportamiento real.

Parameters
$response : int|null

uno de los Vies::RESULT_* o null para desactivar la simulación

fetchViesInfo()

Llama a VIES y devuelve un array con `valid`, `name` y `address`.

private static fetchViesInfo(string $vatNumber, string $codiso, bool $msg) : array<string|int, mixed>|null

Devuelve null sólo si la llamada SOAP falla; un NIF con formato correcto pero inexistente devuelve ['valid' => false, ...], no null.

Parameters
$vatNumber : string
$codiso : string
$msg : bool
Return values
array<string|int, mixed>|null

getViesInfo()

private static getViesInfo(string $vatNumber, string $codiso, bool $msg) : int
Parameters
$vatNumber : string
$codiso : string
$msg : bool
Return values
int

prepare()

Aplica las validaciones previas comunes a {@see check()} y {@see fetch()}: extensión SOAP disponible, código ISO con formato correcto y perteneciente a la UE, y longitud mínima del cifnif tras normalizar.

private static prepare(string $cifnif, string $codiso, bool $msg) : string|null
Parameters
$cifnif : string
$codiso : string
$msg : bool
Return values
string|null —

cifnif normalizado listo para enviar a VIES, o null si alguna validación falla

setMessage()

private static setMessage(bool $msg, string $txt[, array<string|int, mixed> $context = [] ]) : void
Parameters
$msg : bool
$txt : string
$context : array<string|int, mixed> = []
On this page

Search results