# Documentación del Servicio Webhook Polimin

## Descripción General

Este es un servicio web desarrollado en Node.js que proporciona endpoints para recibir webhooks y gestionar autentificación mediante JWT. El servicio está diseñado para procesar datos de webhooks y almacenarlos en una base de datos MySQL.

## Información del Proyecto

- **Nombre**: ws-polimin-node
- **Versión**: 1.0.0
- **Autor**: Alberto Beseira
- **Descripción**: Migración de APIs Posvirtual Node

## Tecnologías Utilizadas

- **Node.js** con ES6 Modules
- **Express.js** - Framework web
- **MySQL** - Base de datos
- **Sequelize** - ORM para base de datos
- **JWT** - Autentificación
- **CORS** - Manejo de políticas de origen cruzado

## Configuración del Entorno

### Variables de Entorno (.env)

El servicio requiere las siguientes variables de entorno:

```env
PORT=3000
SECRET=tu_clave_secreta_jwt
# Variables de base de datos
DB_HOST=localhost
DB_USER=usuario
DB_PASSWORD=contraseña
DB_NAME=nombre_base_datos
```

### Instalación

```bash
# Instalar dependencias
npm install

# Ejecutar en modo desarrollo
npm run dev

# Ejecutar en producción
npm start
```

## Endpoints Disponibles

### 1. Endpoint Raíz

**GET** `/`

- **Descripción**: Endpoint de verificación del servicio
- **Respuesta**: `400 - "Sitio Restringido"`
- **Uso**: Verificar que el servicio está funcionando

### 2. Autentificación

**POST** `/v1/autentificacion`

- **Descripción**: Endpoint para obtener token de acceso JWT
- **Autentificación**: Basic Auth (usuario:contraseña en Base64)
- **Headers requeridos**:
  ```
  Authorization: Basic <credenciales_base64>
  Content-Type: application/json
  ```

#### Ejemplo de Solicitud

```bash
curl -X POST http://localhost:3000/v1/autentificacion \
  -H "Authorization: Basic dXN1YXJpbzpjb250cmFzZW5h" \
  -H "Content-Type: application/json"
```

#### Respuesta Exitosa (200)

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 180,
  "scope": ""
}
```

#### Respuestas de Error

- **401**: Credenciales inválidas
- **400**: Formato de credenciales inválido
- **500**: Error interno del servidor

### 3. Webhook

**POST** `/v1/webhoock/`

- **Descripción**: Endpoint para recibir y procesar webhooks
- **Autentificación**: Bearer Token (JWT)
- **Restricción de IP**: Solo IPs autorizadas pueden acceder
- **Headers requeridos**:
  ```
  Authorization: Bearer <jwt_token>
  Content-Type: application/json
  ```


#### Estructura del JSON de Entrada

```json
{
  "TipoMnt": 1,
  "IdMnt": 120250729154505,
  "Item": [
    {
      "CodigoNetSuit": "AC01"
    },
    {
      "CodigoNetSuit": "AC03"
    }
  ]
}
```

#### Ejemplo de Solicitud

```bash
curl -X POST http://localhost:3000/v1/webhoock/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "TipoMnt": 1,
    "IdMnt": 120250729154505,
    "Item": [
      {
        "CodigoNetSuit": "AC01"
      }
    ]
  }'
```

#### Respuesta Exitosa (201)

```json
{
  "success": true,
  "message": "Webhook almacenado correctamente",
  "id": 123
}
```

#### Respuestas de Error

- **400**: Cuerpo del webhook inválido o vacío
- **401**: Token JWT inválido o no proporcionado
- **403**: IP no autorizada
- **500**: Error interno del servidor

## Estructura de la Base de Datos

### Tabla: log_hook_procesos

La tabla almacena los datos de los webhooks recibidos:

| Campo | Tipo | Descripción |
|-------|------|-------------|
| id | INT AUTO_INCREMENT | Identificador único (PK) |
| OrderId | VARCHAR(50) | ID del pedido (mapeado desde IdMnt) |
| NroPaquete | INT | Número de paquete |
| estatus | VARCHAR(50) | Estado del proceso |
| estado | CHAR(20) | Estado general (default: '0') |
| fecha | TIMESTAMP | Fecha de creación (default: CURRENT_TIMESTAMP) |
| json | LONGTEXT | JSON completo del webhook |
| error | VARCHAR(100) | Mensaje de error si aplica |
| tipo | VARCHAR(20) | Tipo de proceso (mapeado desde TipoMnt) |

#### Índices

- `id`: Índice en campo id
- `key1`: Índice compuesto (estado, tipo)
- `llave1_lhp`: Índice en OrderId
- `llave2`: Índice compuesto (OrderId, NroPaquete)
- `llave3`: Índice compuesto (OrderId, NroPaquete, estado)

## Mapeo de Campos

Cuando se recibe un webhook, los campos se mapean de la siguiente manera:

| Campo JSON | Campo BD | Transformación |
|------------|----------|----------------|
| IdMnt | OrderId | Convertido a string |
| TipoMnt | tipo | Convertido a string |
| NroPaquete | NroPaquete | Directo (si existe) |
| estatus | estatus | Directo (si existe) |
| (todo el JSON) | json | JSON.stringify() |

## Seguridad

### Autentificación JWT

- **Algoritmo**: HS256
- **Expiración**: 3 horas
- **Header**: `Authorization: Bearer <token>`

### Restricciones de IP

El endpoint de webhook solo acepta conexiones desde IPs autorizadas.

### CORS

Configurado para aceptar:
- **Orígenes**: Todos (`*`)
- **Métodos**: GET, POST, PUT, DELETE, PATCH
- **Headers**: Content-Type, Authorization, x-access-token

## Códigos de Estado HTTP

| Código | Descripción |
|--------|-------------|
| 200 | Autentificación exitosa |
| 201 | Webhook procesado correctamente |
| 400 | Solicitud inválida |
| 401 | No autorizado (credenciales/token inválido) |
| 403 | Prohibido (IP no autorizada) |
| 500 | Error interno del servidor |

## Logs y Monitoreo

El servicio registra:
- Errores de procesamiento de webhooks
- Errores de autentificación
- Información de debug en modo desarrollo

## Flujo de Trabajo Típico

1. **Obtener Token**:
   - Realizar POST a `/v1/autentificacion` con Basic Auth
   - Recibir JWT token

2. **Enviar Webhook**:
   - Realizar POST a `/v1/webhoock/` con Bearer token
   - Incluir JSON con datos del webhook
   - Recibir confirmación de almacenamiento

3. **Verificación**:
   - Los datos se almacenan en la tabla `log_hook_procesos`
   - Se puede consultar por OrderId, tipo, etc.

## Consideraciones de Desarrollo

- El servicio usa ES6 modules (`"type": "module"` en package.json)
- Sequelize como ORM para interacciones con la base de datos
- Nodemon para desarrollo con recarga automática
- Manejo de errores centralizado
- Validaciones de entrada en todos los endpoints

## Contacto

Para soporte técnico o consultas sobre la API, contactar al desarrollador: Alberto Beseira.