Operaciones con el API

Este documento describe los endpoints y la configuración de encabezados necesarios para utilizar los servicios de cifrado y descifrado de AES-256-GCM.

En este documento, encontrará un manual completo que cubre Endpoints, Headers, Request Body y Responses de KeyFortress API Gateway AES-256-GCM.

Endpoints Disponibles

La API expone dos operaciones principales a través de métodos POST.

Operación	Endpoint	Método	Descripción
Encriptar	https://gateway-aes256gcm.keyfortress.com/test/files/encrypt	POST	Cifra los datos o archivos proporcionados.
Desencriptar	https://gateway-aes256gcm.keyfortress.com/test/files/decrypt	POST	Descifra los datos o archicos cifrados.

Configuración de HEADERS

Debe incluir los siguientes encabezados en todas las solicitudes para la autenticación y especificación de la operación.

Header	Ejemplo de Valor	Descripción
company_id	10458341988	Identificador único de tu empresa.
username	usuario.id	Nombre de usuario para la auditoría de la operación.
operation_mode	(Ver opciones)	Define el modo de operación deseado para el proceso de encriptación.

Modos de Operación (operation_mode)

El header operation_mode debe contener uno de los siguientes valores:

• E: Encrypt only (Solo Encriptar). El servicio solo devolverá los datos cifrados.

• S: Encrypt and Storage (Encriptar y Almacenamiento). El servicio cifrará los datos y los almacenará internamente.

• N: Notificación. Modo para fines de notificación o testing específico (requiere documentación adicional de la API para su uso completo).

Ejemplos de Respuesta (Response)

1. Respuesta de la Operación Encriptar (/files/encrypt)

Campo	Tipo	Descripción	Ejemplo de Valor
status	string	Indica el resultado de la operación.	"200"
file_encrypted	string	Datos cifrados resultantes (en Base64).	"Y3lwaGVydGV4dERhdGFoYmNjZGVmZ2hpbms="
operation_mode	string	El modo de operación que se ejecutó (replicado del Header).	"E" (Encrypt only)
timestamp	number	Hora en que se completó la operación (epoch time).	1702584000

Ejemplo JSON de Éxito (Encrypt):

"statusCode": 200,
"body": {
"uuid": "jhj23424-n3h4-fsfdr4wr4f34f3ff43-989090009",
"client_id": "1234567890",
"file_name": "file_name_test_12.pdf.encrypted",
"file_encrypted": "L89IQ3qowPF8ESdiGtPeUCu7OBAS2Vh4NpB/+8NKCW1QManAfSXxVNG69E1OBR2Dy6JslXOEV4G4WE/DYYIe7J+vHiWnnDvlzxjqg+ZlYHwpD+0Xco/+nVysUEnD7izaheEcRcN8w5017XZh4d9tJRWMykExC1CugK73wuYowMLkvoZHu8zs+j/KEzd3SLFC97lDDWIXb09TW/nwLtBe3Tk3sKTHIhjsVO5miNwvEOzWrXkvr4Qn7S6Gx5M/X4Z1xgXUCq4vS8O22K7sjMDYsjBHmml" ...

2. Respuesta de la Operación Desencriptar (/files/decrypt)

Una respuesta exitosa de descifrado solo debe devolver los datos en su formato original (descifrado).

Campo	Tipo	Descripción	Ejemplo de Valor
status	string	Indica el resultado de la operación.	"200"
file_decrypted	string	Los datos descifrados (en Base64).	"VGhpcyBpcyBhIHRlc3QgZGF0YQo=" (El contenido original)
timestamp	number	Hora en que se completó la operación.	1702584005

Ejemplo JSON de Éxito (Decrypt):

"statusCode": 200,
"body": {
"uuid": "jhj23424-n3h4-fsfdr4wr4f34f3ff43-989090009",
"file_name": "file_name_test_12.pdf",
"file_decrypted": "JVBERi0xLjcNJeLjz9MNCjMxIDAgb2JqDTw8L0xpbmVhcml6ZWQgMS9MIDEwMDAwNjUvTyAzMy9FIDU3MDkzNi9OIDIvVCA5OTk3MTYvSCBbIDUxMyAyMTBdPj4NZW5kb2JqDSAgICAgICAgICAgICAgDQo1NCAwIG9iag08PC9EZWNvZGVQYXJtczw8L0NvbHVtbnMgNS9QcmVkaWN0b3IgMTI.. "

3. Respuesta de Error Común

Para cualquier error (ej. clave no encontrada, header faltante, datos mal formados), la API devuelve un código de estado HTTP 4xx o 5xx, y un cuerpo JSON que describirá el problema.

Campo	Tipo	Descripción	Ejemplo de Valor
status	string	Indica el estado de error.	"400"
message	string	Descripción detallada y amigable del error.	"El campo client_id es obligatorio, El tmtamaño del archivo excede lo permitido."

Ejemplo JSON de Error:

{
  "status": "400",
  "message": "El campo client_id es obligatorio.","El tamaño del archivo excede el permitido.",
  "timestamp": 1702584010
}