Introducción
La API proporcionada por nosotros utiliza el protocolo HTTP estándar. Todas las funciones de la API utilizan el método HTTP GET. Cada llamada de función requiere autorización de consulta. Los datos para la autorización de consultas se envían en el encabezado HTTP.
Servicio de producción
Es necesario el registro de una entidad que quiera utilizar la funcionalidad del sistema viesapi.eu. Para ello, acceda a la Registro página y complete el formulario correspondiente. El requisito previo para utilizar el sistema viesapi.eu es la aceptación de la Términos de servicio. Rellenando correctamente el formulario y haciendo clic en el Registro botón creará una cuenta en el sistema viesapi.eu y su activación automática.
Al iniciar sesión por primera vez, se genera automáticamente un identificador junto con la clave correspondiente. El identificador es público y no requiere protección, mientras que la clave es privada y no debe ponerse a disposición de terceros.
Dirección del servicio de producción: https://viesapi.eu/api
servicio de prueba
La funcionalidad completa de todas las bibliotecas compartidas se puede comprobar mediante el uso compartido Pruebe la API de VIES. Mediante el uso de la API de prueba, es posible comprobar todas las funciones que se ofrecen en los planes de pago sin necesidad de crear una cuenta.
Dirección del servicio de prueba: https://viesapi.eu/api-test
Definición de la interfaz API
Una definición detallada de la API está disponible en un formato compatible con OpenAPI y se puede descargar como un archivo YAML aquí.
La API también está disponible como interfaz de cliente Interfaz de usuario de Swagger.
Ejecución de la consulta
Un ejemplo de hacer una consulta al sitio de prueba:
OBTENER /api-test/get/vies/euvat/PL7171642051 HTTP/1.1
Anfitrión: viesapi.eu:443
Autorización: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
Agente de usuario: VIESAPIClient/cliente_versión nombre_plataforma/plataforma_versión
Dónde:
api_key_id
– Identificador de clave API (en el entorno de producción, el valor del identificador generado durante el registro, en el entorno de prueba, el valor de test_id),unix_timestamp
– la hora actual en forma de un número de segundos de los llamados época unix,random_str
– cadena aleatoria, diferente para cada consulta (mín. 8 caracteres, máx. 16 caracteres),b64_calculated_mac_value
– HMAC calculado (utilizando unAPI key
, valortest_key
en el entorno de prueba),client_version
– versión del cliente (en nuestras bibliotecas es la versión de nuestra biblioteca API, por ejemplo, 1.2.3),platform_name
– el nombre de la plataforma del cliente API (en nuestras bibliotecas es el nombre del lenguaje de la biblioteca, por ejemplo, JAVA, PHP, .NET, Python),platform_version
– Versión de la plataforma del cliente API (en nuestras bibliotecas es la versión del entorno de la biblioteca, por ejemplo, 17 para JAVA o 7.4 para PHP).
Todas las respuestas devueltas por el sitio web están en formato XML.
Solicitud de autenticación
Los datos de autorización deben prepararse de acuerdo con Autenticación HTTP: autenticación de acceso MAC y este es el método de autenticación recomendado. También es posible utilizar el Autenticación HTTP: autenticación básica Sin embargo, por motivos de seguridad, utilícelo solo cuando no sea posible utilizar el primer método por algún motivo.
Cada consulta a nuestro sitio web debe autenticarse utilizando uno de los dos métodos disponibles.
Método 1: HMAC (recomendado)
Especificación del método de autorización utilizado: Autenticación HTTP: autenticación de acceso MAC. La autorización consiste en calcular el HMAC SHA256 a partir de una cadena debidamente preparada y enviar el resultado en la cabecera HTTP.
Ejemplo
La cadena de entrada a la función HMAC es:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'
Dónde:
ts
– la hora actual en forma de un número de segundos de los llamados época unix, siempre debe proporcionar el tiempo de ejecución de consulta actual (tolerancia del servidor +/- 10 min en relación con el tiempo actual),nonce
– cadena aleatoria, diferente para cada consulta (mín. 8 caracteres, máx. 16 caracteres),method
– Nombre del método HTTP (siempre GET),path
– Ruta URL de la consulta a ejecutar,host
– Nombre del servidor API VIES (siempreviesapi.eu
),port
– Número de puerto del servidor VIES API (siempre 443),’\n’
– carácter de nueva línea (código ASCII 10, 0x0A).
Para la consulta del número de IVA PL7171642051 enviada al servicio de prueba el 25/11/2019 a las 00:00:00 UTC, la cadena de entrada a la función HMAC se verá así:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"
El archivo de cadena de entrada para este ejemplo se puede descargar aquí.
De la cadena preparada, calculamos HMAC SHA256, como la contraseña HMAC le damos el API key
, es decir, en el caso de la API de prueba, el valor de test_key
:
HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306
La función HMAC SHA256 devuelve 32 bytes binarios (que se muestra arriba como un hex
cadena para facilitar la lectura). Descargar archivo con valor binario aquí.
El valor binario del HMAC calculado debe codificarse con el algoritmo Base64, obtenemos:
d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=
Este valor debe enviarse como valor MAC en el encabezado con datos para la autorización. Finalmente:
Authorization: MAC id="test_id", ts="1574640000", nonce="dt831hs59s", mac="d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY="
En la máquina Linux, el valor MAC requerido se puede calcular en un solo paso usando este comando:
$ echo -e -n "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n" | openssl dgst -sha256 -hmac "test_key" -binary | openssl enc -base64
Método 2: autenticación básica
Especificación de este método de autorización utilizado: Autenticación HTTP: autenticación básica.
Ejemplo 1
La cadena de entrada a la función Base64 es:
str = key_id + ':' + clave
Dónde:
key_id
– Identificador de clave API (en el caso de un entorno de prueba,test_id
cadena),key
– Clave API (en el caso de un entorno de prueba, cadenatest_key
).
Para el entorno de prueba, la cadena de entrada para la función Base64 será:
str = "test_id:prueba_clave"
Después de aplicar la función Base64, obtenemos:
Base64(cadena) = dGVzdF9pZDp0ZXN0X2tleQ==
Este valor debe enviarse como valor Básico en el encabezado con datos para la autorización. Por último:
Autorización: Básica dGVzdF9pZDp0ZXN0X2tleQ==
Ejemplo 2
El siguiente ejemplo muestra una consulta que se puede invocar en un entorno de prueba desde un navegador web. Simplemente cópielo y péguelo en la barra de direcciones del navegador:
https://test_id:test_key@viesapi.eu/api-test/get/vies/euvat/PL7171642051
Dónde:
test_id
– para autenticar en una producción ambiente, el parámetro debe contener un identificador de clave válido utilizado para la autorización,test_key
– para autenticar en una producción entorno, el parámetro debe contener un valor válido de la clave utilizada para la autorización.
El identificador de clave y la clave son generados por el usuario después de iniciar sesión en su cuenta en el viesapi.eu
portal (API keys
pestaña). See el documentación página para obtener más información sobre ID y generación de claves.
Respuesta
Si la solicitud se maneja correctamente, se genera la siguiente respuesta:
Descripción detallada de los atributos devueltos:
uid
– identificador de consulta único generado por viesapi.eu,countryCode
– código de país en el que está registrada la empresa asociada con el número de IVA de la UE proporcionado en la consulta,vatNumber
– Número de IVA de la UE de la empresa verificada proporcionada en la consulta,valid
– respuesta del servicio VIES, informando sobre el estado actual del IVA de la UE de la entidad verificada:true
– el número de IVA de la UE proporcionado en la consulta es válido,false
– el número de IVA de la UE proporcionado en la consulta no es válido,
traderName
– nombre comercial de la empresa,traderCompanyType
– siempre devolvía una cadena de caracteres '-',traderAddress
– dirección de la empresa donde está registrada la empresa,id
– identificador de consulta único generado por el sistema VIESdate
– fecha de ejecución de la consultasource
– fuente de datos, siempre: http://ec.europa.eu
Respuesta de error
En caso de algún error relacionado con el manejo de la solicitud, se devuelve el siguiente mensaje de error:
Descripción detallada de los atributos devueltos:
code
– código de error único para el tratamiento automático de errores,description
– descripción de error interceptable por humanos,details
– mdescripción detallada del error (opcional),