# HITO 1: Descarga de Pedidos EDI — Integración EDICOM iPaaS
**Proyecto**: AGRIGEST — Integración EDI con EDICOM iPaaS  
**Documento**: EDICOM-HITO-01-PEDIDOS.md  
**Mensaje EDI**: `ORDERS` (UN/EDIFACT D96A)  
**Dirección de flujo**: EDICOM → AGRIGEST (Inbound)  
**Versión**: 1.0 — 2026-07-23

---

## 1. Descripción del Hito

La descarga de pedidos consiste en la **recepción automatizada de órdenes de compra** enviadas por los clientes/cadenas a través de la plataforma EDICOM iPaaS.  
El cliente (cadena comercial, supermercado, distribuidor) envía un mensaje EDI `ORDERS` que EDICOM transforma y pone a disposición de AGRIGEST mediante su API REST.

**Flujo**: `Cliente EDI → Plataforma EDICOM → API iPaaS → AGRIGEST → BD MariaDB`

---

## 2. Requerimientos EDICOM para la Descarga de Pedidos

### 2.1 Autenticación

Todas las peticiones deben incluir:

```http
Authorization: Bearer <token_acceso>
X-Eipaas-Ds: <codigo_datasource_cliente>
```

| Parámetro | Valor a solicitar a EDICOM |
|---|---|
| `<token_acceso>` | Token JWT obtenido por EDICOM Accounts o API Key |
| `<codigo_datasource_cliente>` | Datasource del entorno (ej. `RAUEDI01`) |
| URL Base | `https://ipaasgw.edicomgroup.com` |

### 2.2 Endpoint de Consulta de Pedidos Pendientes

```http
GET /api/v1/messages/pending
Authorization: Bearer <token>
X-Eipaas-Ds: <datasource>
```

**Respuesta de ejemplo**:
```json
{
  "messages": [
    {
      "messageId": "MSG-20260723-00001",
      "documentType": "ORDERS",
      "sender": "GLN-CLIENTE-12345678",
      "receiver": "GLN-PROVEEDOR-87654321",
      "createdAt": "2026-07-23T10:00:00Z",
      "payload": { ... }
    }
  ],
  "totalCount": 5
}
```

### 2.3 Descarga del Payload de un Pedido

```http
GET /api/v1/messages/{messageId}
Authorization: Bearer <token>
X-Eipaas-Ds: <datasource>
```

### 2.4 Confirmación de Recepción (OBLIGATORIO)

Tras procesar cada pedido, DEBE confirmarse su recepción para que EDICOM lo marque como procesado:

```http
POST /api/v1/messages/{messageId}/confirm
Authorization: Bearer <token>
X-Eipaas-Ds: <datasource>
Content-Type: application/json

{ "status": "ACCEPTED" }
```

### 2.5 Estructura Canónica del Payload ORDERS

Campos principales que EDICOM transforma desde el EDI `ORDERS`:

| Campo EDICOM | Descripción | Mapeo AGRIGEST |
|---|---|---|
| `orderNumber` | Número de pedido del cliente | `ge_pedidos.referencia_cliente` |
| `orderDate` | Fecha del pedido | `ge_pedidos.fecha` |
| `deliveryDate` | Fecha de entrega solicitada | `ge_pedidos.fecha_entrega` |
| `buyerGLN` | GLN del comprador (cliente) | `ge_clientes.ean` |
| `deliveryPointGLN` | GLN del punto de entrega | `ge_clientes_destinos.ean` |
| `sellerGLN` | GLN del vendedor (nuestra empresa) | `ge_empresas` |
| `lines[].lineNumber` | Número de línea | `ge_pedidos_lineas.posicion` |
| `lines[].ean` | EAN del producto | `ge_articulos.ean` / `ge_articulos_ean.ean` |
| `lines[].orderedQuantity` | Cantidad pedida | `ge_pedidos_lineas.cantidad` |
| `lines[].unitPrice` | Precio unitario acordado | `ge_pedidos_lineas.precio` |
| `lines[].description` | Descripción del artículo | `ge_pedidos_lineas.descripcion` |

---

## 3. Análisis de la Base de Datos Actual — Carencias Detectadas

### 3.1 Tabla `ge_pedidos` — Estado Actual

**Campos existentes**:
- `id`, `empresa_id`, `cliente_id`, `clientedestino_id`
- `serie`, `numero`, `referencia`, `fecha`
- `base_imponible`, `total`, `iva`
- `observaciones`
- Campos de auditoría estándar

**❌ Carencias para la integración EDI**:

| Campo Faltante | Tipo | Descripción | Necesario Para |
|---|---|---|---|
| `edi_message_id` | `varchar(100)` | ID del mensaje EDICOM | Control de duplicados |
| `edi_numero_pedido_cliente` | `varchar(50)` | Nº pedido original del cliente | Referencia cruzada |
| `edi_fecha_pedido_cliente` | `datetime` | Fecha en que el cliente hizo el pedido | Trazabilidad |
| `edi_fecha_entrega_solicitada` | `date` | Fecha de entrega pedida por el cliente | Gestión logística |
| `edi_estado` | `enum('PENDIENTE','PROCESADO','RECHAZADO','ERROR')` | Estado del procesamiento EDI | Control de flujo |
| `edi_descargado_at` | `timestamp` | Fecha/hora de descarga desde EDICOM | Auditoría |
| `edi_confirmado_at` | `timestamp` | Fecha/hora de confirmación a EDICOM | Auditoría |
| `edi_origen` | `varchar(50)` | GLN del emisor (cliente) | Identificación origen |

### 3.2 Tabla `ge_clientes` — Estado Actual

**Campos existentes**:
- `ean` → `varchar(45)` — **✅ Campo GLN existe** (código EAN/GLN-13)

**⚠️ Carencia**: El campo `ean` existe pero debe contener el **GLN (Global Location Number)** del cliente para la identificación EDI. Verificar que todos los clientes EDI tengan su GLN informado.

### 3.3 Tabla `ge_clientes_destinos` — Estado Actual

**Campos existentes**:
- `ean` → `varchar(20)` — **✅ Campo GLN punto entrega existe**
- `ean_cliente`, `ean_receptor` — **✅ Campos adicionales EDI existen**

### 3.4 Tabla `ge_articulos` — Estado Actual

**Campos existentes**:
- `ean` → `varchar(20)` — **✅ Campo EAN artículo existe**
- Tabla `ge_articulos_ean` → **✅ EANs múltiples por artículo**

### 3.5 Tabla `ge_pedidos_lineas` — Estado Actual

**Campos existentes**: `articulo_codigo`, `articulo_id`, `descripcion`, `cantidad`, `precio`, `posicion`

**❌ Carencias para la integración EDI**:

| Campo Faltante | Tipo | Descripción |
|---|---|---|
| `edi_ean_producto` | `varchar(20)` | EAN del producto según el pedido EDI |
| `edi_cantidad_pedida_original` | `decimal(12,4)` | Cantidad original del EDI (antes de ajustes) |
| `edi_numero_linea_cliente` | `int(11)` | Número de línea en el pedido del cliente |

---

## 4. SQL Propuesto — Campos a Añadir

> ⚠️ **IMPORTANTE**: Este script debe ser revisado y ejecutado **manualmente** por el usuario según la regla de seguridad de la empresa.

```sql
-- ========================================
-- HITO 1: Campos EDI para ge_pedidos
-- ========================================

ALTER TABLE `ge_pedidos` 
  ADD COLUMN `edi_message_id`              varchar(100)  DEFAULT NULL COMMENT 'ID del mensaje EDICOM (control de duplicados)'        AFTER `referencia`,
   ADD COLUMN `edi_estado`                  enum('PENDIENTE','PROCESADO','RECHAZADO','ERROR') DEFAULT 'PENDIENTE'
                                                                      COMMENT 'Estado del procesamiento EDI'                          AFTER `edi_fecha_entrega_solicitada`,
  ADD COLUMN `edi_descargado_at`           timestamp     NULL DEFAULT NULL COMMENT 'Fecha/hora de descarga desde EDICOM'             AFTER `edi_estado`,
  ADD COLUMN `edi_confirmado_at`           timestamp     NULL DEFAULT NULL COMMENT 'Fecha/hora de confirmación a EDICOM'             AFTER `edi_descargado_at`,
  ADD COLUMN `edi_origen_gln`              varchar(30)   DEFAULT NULL COMMENT 'GLN del emisor (cliente EDI)'                         AFTER `edi_confirmado_at`,
  ADD INDEX `idx_ge_pedidos_edi_message_id` (`edi_message_id`),
  ADD INDEX `idx_ge_pedidos_edi_estado` (`edi_estado`);

-- ========================================
-- HITO 1: Campos EDI para ge_pedidos_lineas
-- ========================================

ALTER TABLE `ge_pedidos_lineas`
  ADD COLUMN `ean_producto`            varchar(20)   DEFAULT NULL COMMENT 'EAN del producto según pedido EDI'                    AFTER `total`,
  ADD COLUMN `cantidad_pedida_original` decimal(12,4) DEFAULT NULL COMMENT 'Cantidad original del pedido EDI (antes de ajustes)' AFTER `ean_producto`,
  ADD COLUMN `numero_linea_cliente`    int(11)       DEFAULT NULL COMMENT 'Número de línea en el pedido del cliente EDI'         AFTER `cantidad_pedida_original`;
```

---

## 5. Proceso de Implementación en AGRIGEST (Delphi)

### 5.1 Módulo Delphi Propuesto

**Nuevo módulo**: `uEdicomPedidosClient.pas`

**Responsabilidades**:
1. `AutenticarEdicom()` — Obtener/renovar el Bearer Token
2. `ConsultarPedidosPendientes(): TJSONArray` — GET a endpoint de mensajes pendientes
3. `DescargarPedido(MessageId: string): TJSONObject` — GET mensaje específico
4. `ProcesarPedidoJSON(Payload: TJSONObject): Integer` — Mapear JSON → `ge_pedidos` + `ge_pedidos_lineas`
5. `ConfirmarRecepcion(MessageId: string)` — POST confirmación a EDICOM
6. `BuscarClientePorGLN(GLN: string): Integer` — Localizar cliente en `ge_clientes.ean`
7. `BuscarArticuloPorEAN(EAN: string): Integer` — Localizar artículo en `ge_articulos.ean` / `ge_articulos_ean`

### 5.2 Flujo de Proceso

```
INICIO (manual o programado)
  │
  ├── 1. AutenticarEdicom() → Bearer Token
  │
  ├── 2. ConsultarPedidosPendientes() → Lista de messageIds
  │
  └── 3. Para cada mensaje:
        ├── DescargarPedido(messageId) → JSON payload
        ├── BuscarClientePorGLN(buyerGLN) → clienteId
        ├── BuscarArticuloPorEAN(lineEAN) → articuloId (por línea)
        ├── ProcesarPedidoJSON() → INSERT en ge_pedidos + ge_pedidos_lineas
        │   ├── Verificar duplicado por edi_message_id
        │   ├── edi_estado = 'PENDIENTE'
        │   └── edi_descargado_at = NOW()
        ├── ConfirmarRecepcion(messageId) → POST confirm
        └── UPDATE ge_pedidos SET edi_estado='PROCESADO', edi_confirmado_at=NOW()
```

### 5.3 Integración en la UI

- Nuevo botón en la pantalla de Pedidos: **"Descargar Pedidos EDI"**
- Indicador visual del estado EDI: `edi_estado` con colores (Pendiente/Procesado/Error)
- Log de operaciones EDI en `ge_proceso_log`

---

## 6. Datos Necesarios de EDICOM (Solicitar al Gestor)

- [ ] URL base del entorno de producción y preproducción
- [ ] Código de datasource (`X-Eipaas-Ds`)
- [ ] Credenciales para obtención del token (usuario API Key o EDICOM Accounts)
- [ ] Endpoint exacto para consulta de pedidos pendientes
- [ ] Esquema JSON canónico del payload `ORDERS` (Canonical Format Document)
- [ ] GLN de nuestra empresa (vendedor)
- [ ] Lista de GLNs de los clientes/cadenas configurados

---

## 7. Dependencias y Consideraciones

- **`ge_clientes.ean`**: Debe contener el **GLN EAN-13** de cada cliente EDI. Verificar y completar datos.
- **`ge_clientes_destinos.ean`**: GLN del punto de entrega (tienda/almacén).
- **`ge_articulos.ean` y `ge_articulos_ean`**: EAN-13 o EAN-14 del producto. Debe estar correctamente registrado.
- **Manejo de Duplicados**: Verificar `edi_message_id` antes de insertar para evitar pedidos duplicados.
- **Scheduler**: Puede implementarse como tarea programada (proceso Windows o botón manual en AGRIGEST).