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.
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
Servicio no disponible:
Nombre de parámetro incorrecto header:
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" }
Manual de Referencia: Manejo de API's en CONTPAQi®
