primer cambio
This commit is contained in:
beseira13
264
DOCUMENTACION_API.md
Normal file
264
DOCUMENTACION_API.md
Normal file
@@ -0,0 +1,264 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user