1. API Obtención de llave pública v1

 
Con esta API puedes obtener la llave pública de transporte necesaria para implementar el mecanismo de encriptación híbrida para cifrar la FIEL que se requiere para realizar una solicitud de descargas hacia el SAT; esto asegura el transporte de información de manera segura entre tu desarrollo y las APIs de CONTPAQi® Nube.
 
API síncrona
 
La llave pública tiene las siguientes características:
 
La llave pública es de tipo RSA con 2048 bytes de longitud.
Puedes almacenar en un archivo .pem el contenido de la propiedad Base64Key.
El objeto de respuesta retorna la expiración de la llave. Si la llave llega a caducar consumiendo este endpoint, podrás obtener una nueva versión de la misma.
 
Métodos o Endpoints de la API
GET: Obtiene la llave pública necesaria en el proceso de cifrado de la FIEL u otra información sensible.
 
Encabezado de la solicitud:
 
Campo
Tipo
Descripción
 
 
License-Code
 
 
String
Código de licencia de la cuenta CONTPAQi® Nube que tiene disponible CONTPAQi® Descargas.
Puedes acceder a él desde tu perfil.
Obligatorio.
 
 
Subscription-Key
 
 
String
Clave de suscripción que proporciona acceso a esta API. Se genera una vez que te suscribiste al producto CONTPAQi® Descargas. Se encuentra en tu perfil.
Obligatorio.
 
 
Respuesta exitosa: 200 OK
 
Retorna la siguiente información de la llave pública:
 
Contenido en base 64 de la llave pública, listo para guardarse en un archivo con extensión .pem.
Operaciones criptográficas que se pueden realizar con la llave.
Fecha de expiración de la llave.
Versión de la llave pública.
Tipo de llave pública.
Tamaño de la llave.
 
 
 
Respuesta fallida:
 
Retorna la siguiente información de la llave pública:
 
Estatus o código de error HTTPS
Tipo de error
Título del error
Detalle del error
Identificador de la traza
Errores
 
 
 
Proceso de encripción de la FIEL
 
La FIEL o e.firma es el conjunto de datos y caracteres que te identifica al realizar trámites y servicios por internet en el SAT, así como en otras Dependencias, Entidades Federativas, Municipios y la iniciativa privada.
Es única y tiene la validez de una firma autógrafa, por esta razón es importante usar mecanismos de encriptación para que la transferencia de la FIEL sea segura en el proceso de descargas.
 
Pasos para encriptar:
1.     Obtén la llave pública con la API de Obtención de llave pública.
2.     Guarda la llave pública en un archivo .pem.
3.     Obtén el contenido de la FIEL en bytes: archivo .cer, archivo .key y la contraseña.
4.     Genera una llave de sesión.
5.     Encripta cada parte de la FIEL con la llave de sesión con el algoritmo AES.
6.     Genera una llave de transporte encriptando la llave de sesión con la llave pública RSA.
7.     Prepara los datos encriptados para mandarlos a la API de Descarga.
 
 
Nota:
 
  • Los pasos 1 y 2 sólo se deben de realizar una vez, no por cada petición.
  • Si la llave cambiara, la API de Descargas te responderá con el mensaje correspondiente, en este caso obtén la llave pública y genera nuevamente el archivo .pem.
  • La llave de sesión debe ser un arreglo de 32 bytes aleatorios.
  • La llave utilizada para la encriptación AES es la llave de sesión.
Por cada dato de la FIEL a encriptar con AES se debe de generar un IV (Initialization Vector).
El IV se debe concatenar al inicio del contenido encriptado.
  • La encriptación RSA debe de ser con el algoritmo RSA-OAEP con Hashing SHA256.
  • Encontrarás ejemplos de código en lenguaje C#, Python, Node.js del proceso de encriptación de la FIEL, solo necesitas copiarlo, pegarlo en tu ID de compilación y compilarlo.
  • Recuerda que sólo debes recuperar la llave pública una única vez o cuando llegue a cambiar, no por petición.
  • Un mal uso de la API puede generar penalizaciones.
 
 
Posibles respuestas:
 
Escenario éxito:
 
{ "base64Key": "xxxxxxxxxx", "version": "xxxxxxxxx", "usage": "encrypt|decrypt|sign|verify|wrapKey|unwrapKey", "keyType": "RSA", "expirationDate": null, "size": 2048 }
 
 
Escenario falla:
 
Clave de suscripción incorrecta:
 
Clave de suscripción no corresponde, inválida, nulo o vacío.
 
{ "status": 401, "type": "https://tools.ietf.org/html/rfc7231#section-6.5", "title": "Subscription Key inválido.", "detail": "Acceso denegado. Encabezado Subscription-Key no especificado o inválido.", "errors": null, "traceId": "" }
 
Clave de suscripción original regenerada
{ "statusCode": 401, "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription." }
 
Código de licencia incorrecto:
 
Código de licencia existente pero no corresponde con el subscriptionkey
{ "status": 403, "title": "Error al validar la suscripción.", "detail": "El código de licencia especificado no corresponde al Subscription Key.", "errors": null, "traceId": "68326832-a578-4bbd-b4b7-61223e28ce0c" }
 
Código de licencia inexistente o inválidos (incompleto, con caracteres adicionales, etc.)
 
{ "status": 404, "title": "El servidor no pudo encontrar el recurso o los recursos solicitados.", "detail": "La licencia especificada no existe o no cuenta con el servicio.", "errors": null, "traceId": "052f770d-f296-4f0a-b21a-d122ba9a887d" }
 
Código de licencia nulo o vacío
 
{ "status": 400, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Error en la solicitud.", "detail": "Encabezado Ocp-Apim-License-Code requerido", "errors": null, "traceId": "ff59d54b-98d9-4bb8-b793-7229243c7f0f" }
 
Servicio no disponible:
 
{ "status": 500, "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1", "title": "Error no controlado", "detail": "Error no controlado, inténtelo de nuevo más tarde.", "traceId": null, "errors": null }
 
Nombre de parámetro incorrecto header:
 
{ "status": 400, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Error en la solicitud.", "detail": "Encabezado Ocp-Apim-License-Code requerido", "errors": null, "traceId": "3d30b0f4-58be-46c4-8ba4-64eb5df20544" }
 
El código de licencia no se tiene el servicio CONTPAQi® Descarga asignado.
 
{ "status": 404, "title": "El servidor no pudo encontrar el recurso o los recursos solicitados.", "detail": "La licencia especificada no existe o no cuenta con el servicio.", "errors": null, "traceId": "2ee0265b-5fa0-42a6-8d0c-c27e6bbe92ad" }
 
El código de licencia tiene el servicio CONTPAQi® Descarga asignado, pero no está vigente, tiene cero en días de vigencia, ha caducado.
 
{ "status": 402, "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Servicio de licencia inválido.", "detail": "El servicio CONTPAQi® Descarga no tiene vigencia.", "errors": null, "traceId": "79b9c4bc-8d38-416f-b548-0b04be7e0db5" }
 
El código de licencia tiene el servicio CONTPAQi®  Descarga asignado, pero está bloqueado
 
¿Qué significa que el servicio está bloqueado, en qué casos pasa?
 
{ "status": 402, "title": "Servicio de licencia inválido.", "detail": "El servicio o módulo de la licencia se encuentra deshabilitado.", "errors": null, "traceId": "74a25b30-b832-43c8-8600-a127e3e97f8a" }