Documentación de la API REST

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 un API key, valor test_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

Especificación del método de autorización utilizado: Autenticación HTTP: autenticación de acceso MAC. Cada consulta a nuestro sitio web debe autenticarse utilizando este método. 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 (siempre viesapi.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