# Operaciones con el API

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.                  | <p><code>"400"</code> </p><p> </p>                                                  |
| `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
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://keyfortress.gitbook.io/es-apigateway-aes256-gcm/operaciones-con-el-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.