Home - dgt30-esp/General GitHub Wiki

La documentación de esta API ofrece una descripción detallada de los métodos disponibles con ejemplos de las respuestas obtenidas, así como información acerca del uso.

Algunas consideraciones previas a tener en cuenta son:

• La API utiliza JSON Web Tokens para la autentificación.

• Las peticiones de la API deben ser realizadas con peticiones GET o POST según el caso.

• Se pueden considerar todas las respuestas que no sean devueltas con un código HTTP 200 como un error.

• Todas las respuestas son en formato JSON.

El versionado de la API se determina en la propia URL. Por ejemplo, para la versión 1 obtendremos la siguiente URL:

{baseUrl}/v1/xxx....

• Para identificar a los clientes, la plataforma utiliza un sistema basado en Certificados Digitales X509. Este se debe solicitar a través del correo [email protected] Desde la plataforma se le enviará un formulario donde cumplimentar la identificación del propietario del certificado así como las direcciones IP desde las que se conectará el cliente a la plataforma. Por seguridad, solo se permitirá el acceso desde las mismas utilizando el certificado otorgado en cada conexión.

• Como paso previo a la obtención del token, se debe poseer el certificado de seguridad y que la IP esté en la lista de permitidas.

• El cn que está contenido en el certificado que se utiliza es el que la aplicación utiliza para comprobar si existe en el registro de usuarios.

{baseUrl}/v1/token

• Si la autentificación es válida, se obtiene una respuesta con la fecha y hora en formato UTC en la que se ha generado, en la que expira y el propio token.

  {
      "issuedAt": "2021-04-01T09:09:16.284Z",
      "expiration": "2021-04-02T09:09:16.284Z",
      "token": "Bearer eyJhbGciOiJIUzUxMiJ9.e......."
  }

• Además, si se realiza una petición con un token expirado se recibe un error HTTP 400 – Bad Request con la respuesta como en el siguiente ejemplo. Se debe solicitar un nuevo token para continuar realizando peticiones a la API.

  {
      "status": 400,
      "code": 6,
      "message": "Expired token received"
  }

• Para realizar peticiones a los endpoints de la API se debe adjuntar en las cabeceras de la petición un atributo en la cabecera (Authorization) y su valor será Bearer (el tipo de token obtenido) más el valor del token que has obtenido separado por un espacio. Por ejemplo:

  Bearer eyJhbGciOiJIUzUxMiJ9.eyJqdGkiOiJDTW9iaWxpdHkzLjAiLCJzdWIiOiJwcnVlYmEiLCJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwiaWF0IoxNjE2NDIxMDYyLCJleHAiOjE2MTY0MjQ2NjJ9.N8KimN9_IgtjXX2Wv-rXLKK929mavlkaakxY_NzHVFgN9DWT8bqRVeTaBgL5GbzDfZSPZXDutoVwjdbTEx3FbA
  

  

Los certificados generados se envían automáticamente por la plataforma DGT3.0 al correo electrónico indicado en el formulario, mediante dos emails: uno contiene un archivo .zip con los certificados y otro que contiene la passphrase (password) para descomprimir el paquete y para ser usado con el certificado .pfx (en caso de utilizar este tipo de certificado).

En caso de no recibir estos emails se debe:

• Comprobar la carpeta Spam de su correo electrónico
• Revisar, por parte de su equipo de IT, si su servidor de correo electrónico ha bloqueado la recepción de los mismos. Esto puede ocurrir debido a que se trata de un email generado y enviado automáticamente por la plataforma, que lleva como adjuntos los certificados digitales, lo cual en ocasiones se considera como una recepción peligrosa. En tal caso, se deberían incluir las excepciones oportunas para recibir todos los emails provenientes de [email protected]

Automatización de renovación de certificados

Los certificados emitidos por la plataforma DGT3.0 tienen una validez de un año.

• Dos meses antes de su caducidad recibirá un correo electrónico automático avisando de la misma
• Un mes antes de dicha fecha, recibirá un correo electrónico automático con los nuevos certificados renovados

Es importante que revise la recepción de estos correos, y aplique en caso necesario los cambios oportunos para recibirlos, ya que están diseñados para ayudar a mantener siempre los certificados en vigor y evitar que caduquen por olvido de esta fecha.

La información relacionada con la conexión MQTT se encuentra disponible aquí.