SQL-INYECTOR/DOCUMENTACION_API.md

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:

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

# 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

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

Respuesta Exitosa (200)

{
  "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

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

Ejemplo de Solicitud

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)

{
  "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.