# Integración de órdenes PrestaShop

Ticket N.º 5307.

El archivo `obtenerOrdenes.php` consulta las órdenes de las cuentas PrestaShop configuradas en la base de preenvíos y las inserta en las tablas `pre_envios` y `pre_envios_items`.

PrestaShop se identifica en el sistema con:

- `tipoCuenta = 5`
- `flex = 5`

## Funcionamiento

Por cada cuenta activa, el proceso:

1. Lee la URL y la API key desde `cuentas.data`.
2. Consulta las órdenes de PrestaShop por rango de fechas y de forma paginada.
3. Obtiene la dirección de entrega, el cliente, el transportista, el estado y la provincia.
4. Convierte la información al formato utilizado por `pre_envios`.
5. Inserta la orden y sus productos dentro de una transacción.
6. Evita duplicados mediante la combinación de empresa, cliente, cuenta, `flex` e `id_reference`.
7. Actualiza el estado cuando la orden ya existe.
8. Intenta completar nuevamente registros anteriores que tengan `sync = -1` o `sync = -2`.
9. Registra la ejecución y sus errores en la tabla `logs`.

El proceso utiliza un bloqueo de base de datos para impedir que dos ejecuciones se superpongan.

## Requisitos

- PHP 7 o superior.
- Extensión cURL.
- Extensión MySQLi.
- Extensiones SimpleXML y libxml.
- Acceso a la base de datos `preenvio_preenvios`.
- Webservice de PrestaShop habilitado.
- API key con permisos de lectura para:

  - `orders`
  - `addresses`
  - `customers`
  - `carriers`
  - `order_states`
  - `states`

## Configuración de las cuentas

El proceso consulta la tabla `cuentas` y toma solamente registros que cumplan estas condiciones:

```sql
tipoCuenta = 5
superado = 0
elim = 0
pais = <pais solicitado>
```

El campo `data` debe contener un JSON con la URL de la tienda y la API key. La configuración recomendada es:

```json
{
  "url": "https://tienda.example.com",
  "token": "API_KEY_DE_PRESTASHOP",
  "fulfillment": 0,
  "ingreso_automatico": 0,
  "id_shop": 0
}
```

También se reconocen los siguientes nombres históricos:

| Dato | Claves aceptadas |
| --- | --- |
| URL | `url`, `pre_url`, `urlApi`, `urlTienda`, `base_url` |
| API key | `key`, `token`, `pre_api`, `apiKey`, `api_key` |
| Ingreso automático | `ingreso_automatico`, `inat` |

La URL puede apuntar a la tienda o directamente a `/api`. La API key puede estar guardada en formato original o codificada en Base64 para autenticación Basic.

## Ejecución

El proceso se ejecuta mediante una petición HTTP `GET`.

### Ejecución normal

```text
obtenerOrdenes.php?pais=1
```

### Probar sin modificar preenvíos

```text
obtenerOrdenes.php?pais=1&dry_run=1
```

`dry_run` consulta la base y la API, y escribe el registro de ejecución en `logs`, pero no inserta ni actualiza `pre_envios` o `pre_envios_items`.

### Filtrar una empresa

```text
obtenerOrdenes.php?pais=1&empresa=211
```

### Filtrar una cuenta específica

```text
obtenerOrdenes.php?pais=1&empresa=211&cliente=250&cuenta=15
```

### Indicar un rango de fechas

```text
obtenerOrdenes.php?pais=1&desde=2026-07-20&hasta=2026-07-21
```

También se aceptan estos nombres:

- Desde: `desde`, `fechaDesde` o `date_from`.
- Hasta: `hasta`, `fechaHasta` o `date_to`.

Cuando se indica solamente una fecha, el día inicial comienza a las `00:00:00` y el día final se incluye completo. Internamente, el extremo superior enviado a PrestaShop es el inicio del día siguiente porque su filtro lo interpreta como exclusivo.

## Parámetros disponibles

| Parámetro | Obligatorio | Descripción |
| --- | --- | --- |
| `pais` | Sí | Identificador del país utilizado para seleccionar las cuentas. |
| `empresa` | No | Limita el proceso a una empresa. |
| `cliente` | No | Limita el proceso a un cliente. |
| `cuenta` | No | Limita el proceso a una cuenta. |
| `desde` | No | Inicio del rango. Acepta fecha o fecha y hora. |
| `hasta` | No | Fin del rango. Acepta fecha o fecha y hora. |
| `limit` | No | Cantidad de órdenes por página, entre 1 y 250. El valor predeterminado es 100. |
| `dry_run` | No | Acepta `1`, `true` o `si` para evitar cambios en las tablas de preenvíos. |

Si no se informa un rango, se consultan desde las `00:00:00` de tres días atrás hasta el final del día actual.

## Mapeo principal

| PrestaShop | `pre_envios` |
| --- | --- |
| `order.id` | `id_reference`, `id_interno` |
| `order.reference` | `number` |
| `order.date_add` | `fecha_venta` |
| `order.current_state` / nombre del estado | `status` |
| `order.id_carrier` | `id_carrier` |
| Nombre del transportista | `metodoenvio` |
| `order.shipping_number` | `id_envio` |
| Nombre de la dirección | `destinatario_nombre` |
| `address.address1` | `direccion_calle` y, cuando es posible, `direccion_numero` |
| `address.address2` | `direccion_floor` |
| `address.city` | `direccion_localidad` |
| `address.postcode` | `direccion_cp` |
| Nombre del estado o provincia | `direccion_provincia` |
| `customer.email` | `email` |
| Teléfono de la dirección | `telefono` |
| `order.total_paid_tax_incl` | `valor_declarado` |
| Productos de `order_rows` | `items` y `pre_envios_items` |

## Valores de `sync`

- `sync = 0`: la orden tiene los datos mínimos necesarios.
- `sync = -2`: la orden fue insertada, pero le faltan datos obligatorios o no se pudo obtener algún recurso necesario.
- `sync = -1`: valor generado por integraciones anteriores; el proceso intenta recuperar y completar estos registros.

Los campos mínimos controlados son:

- Estado.
- Identificador de la orden.
- Nombre del destinatario.
- Calle.
- Localidad.
- Código postal.
- Productos.

## Paginación y límites

- Tamaño predeterminado de página: 100 órdenes.
- Tamaño máximo configurable: 250 órdenes.
- Tiempo máximo aproximado por ejecución: 115 segundos.

Si se alcanza el límite de tiempo, la ejecución finaliza de forma controlada. La siguiente ejecución vuelve a consultar el rango y omite las órdenes que ya existen.

## Salida y errores

La respuesta muestra el avance en HTML y termina con un resumen similar a:

```text
RESUMEN {"cuentas":1,"ordenes":10,"insertado":8,"sin_cambios":2,"errores":0}
```

Los principales mensajes son:

- `ERROR_CONFIG`: JSON inválido o credenciales faltantes.
- `ERROR_API`: error de conexión, autenticación, permisos o respuesta de PrestaShop.
- `ERROR_ORDEN`: error al mapear o guardar una orden concreta.
- `ADVERTENCIAS`: no se pudo obtener un recurso relacionado; la orden puede quedar con `sync = -2`.
- `Ya hay otra ejecucion de PrestaShop en curso`: el bloqueo impidió una ejecución superpuesta.

Los mismos detalles quedan registrados en `logs.observacion`.

## Verificación de sintaxis

Antes de publicar cambios se puede ejecutar:

```bash
php -l obtenerOrdenes.php
```

## Seguridad

- No enviar la API key como parámetro de la URL.
- Mantener las credenciales solamente en la configuración de la cuenta.
- Usar HTTPS en las tiendas.
- Limitar la API key a permisos de lectura sobre los recursos necesarios.
- Restringir el acceso web al proceso mediante cron, VPN, autenticación o lista de IP permitidas.