Documentación de la API REST

Documentación REST de la API de VIES

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:

GET /api-test/get/vies/euvat/PL7171642051 HTTP/1.1
Host: viesapi.eu:443
Authorization: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
User-Agent: VIESAPIClient/client_version platform_name/platform_version
Accept: mime_type

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),
  • mime_type – Nombre del tipo MIME en el que se debe devolver la respuesta; se admiten dos tipos: text/xml y application/json, si la solicitud no contiene el encabezado Aceptar, se devuelve XML de forma predeterminada.

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 (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

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 + ':' + key

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, cadena test_key).

Para el entorno de prueba, la cadena de entrada para la función Base64 será:

str = "test_id:test_key"

Después de aplicar la función Base64, obtenemos:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

Este valor debe enviarse como valor Básico en el encabezado con datos para la autorización. Por último:

Authorization: Basic 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 VIES
  • date – fecha de ejecución de la consulta
  • source – 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:

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),

Códigos de error

La siguiente tabla enumera todos los posibles errores devueltos por las API REST y las bibliotecas de programación:

Código de error Mensaje de error
8 Formato de solicitud no válido
10 Ruta de API no válida
11 Error de servicio interno
22 El número de IVA de la UE no es válido
23 No se pudieron obtener datos del sistema VIES
26 Esta función no está disponible en el plan seleccionado actualmente
27 Esta función no admite este modo de búsqueda.
33 No es posible consultar los datos proporcionados en el modo de prueba
35 No se requiere autorización de consulta de acceso
36 El servicio no está disponible temporalmente debido a trabajos técnicos programados.
43 No se pudo recuperar el número de consultas de usuario para el mes actual
54 Fecha u hora incorrecta en la computadora o sistema del usuario
55 Valor de cadena MAC no válido en el encabezado con credenciales de consulta
57 Valor de clave no válido en el encabezado con credenciales de consulta
58 Se ha alcanzado el número máximo de consultas simultáneas para este Estado miembro
59 La solicitud en el Estado miembro no responde o no está disponible
101 El número de IP de conexión no coincide con el número de IP asignado a la clave API
102 La clave API está bloqueada
103 Clave API no válida
104 Se ha alcanzado el número máximo de consultas disponibles para el plan seleccionado
105 Cuenta bloqueada o eliminada
106 Tipo de cuenta no válido
107 La cuenta prepago no ha sido pagada
108 ID de clave API no válida
201 No se pudo conectar al servicio API de VIES
202 La respuesta del servicio API de VIES tiene un formato no válido
203 Tipo de número no válido
204 El NIP no es válido
205 El número de IVA de la UE no es válido
206 La función generó una excepción
207 La fecha tiene un formato no válido
208 Parámetro de entrada no válido