264 lines
6.2 KiB
Markdown
264 lines
6.2 KiB
Markdown
# 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. |