Esquema JSON de Pedidos (OrderPayload) y Validación Zod

Para garantizar que ningún pedido malformado o incompleto llegue a corromper la base de datos de Factusol, Bentian valida cada objeto entrante contra un esquema TypeScript estricto validado en runtime mediante la biblioteca Zod.

1. Especificación del Esquema JSON

Estructura completa de un pedido válido procesable por el conector:

{
  "id": "ORD-2026-9041",
  "series": "1",
  "createdAt": "2026-10-05T08:30:00Z",
  "customer": {
    "name": "Suministros Industriales Levante S.L.",
    "cif": "B98765432",
    "email": "[email protected]",
    "phone": "+34 961 234 567",
    "billingAddress": {
      "address": "Calle Mayor 12, Nave 3",
      "city": "Valencia",
      "postalCode": "46001",
      "province": "Valencia",
      "country": "ES"
    }
  },
  "lines": [
    {
      "sku": "TAL-BOSCH-750",
      "description": "Taladro Percutor Bosch GSB 750W",
      "quantity": 2,
      "unitPrice": 89.00,
      "discountPercent": 0.0,
      "vatRate": 21.0,
      "equivalenceSurchargeRate": 5.2
    }
  ],
  "shipping": {
    "cost": 6.50,
    "vatRate": 21.0
  },
  "paymentMethod": "stripe",
  "total": 222.18
}

2. Campos de Cabecera y Cliente

• id (string): Identificador único del pedido en la tienda web (utilizado para evitar duplicidades).
• series (string, 1 char): Serie de facturación de Factusol (por defecto "1").
• customer.cif (string): NIF, CIF o NIE del cliente para matching en F_CLI.

3. Campos de Detalle de Líneas de Producto

• sku (string): Código de artículo en Factusol (F_ART.CODART).
• quantity (number): Número de unidades (soporta decimales para venta a peso/metros).
• unitPrice (number): Precio unitario base sin impuestos.
• vatRate (number): Tipo impositivo de IVA (21, 10, 4 o 0).
• equivalenceSurchargeRate (number, opcional): Recargo de equivalencia aplicable (5.2, 1.4, 0.5 o 0).

4. Validación en TypeScript con Zod

El pipeline de ingesta de Bentian ejecuta OrderSchema.parse(payload). Si falta algún campo obligatorio o los importes no cuadran matemáticamente, el pedido no se inserta en Factusol y queda registrado en la cola de inspección con una notificación humanizada.