Contrato de Datos – Reparto
Versión: v1.0
Fecha: (completar)
Ámbito: Pedidos enviados al sistema de reparto (API / panel / microservicio_estado)
________________________________________
1. Objetivo
Definir, de forma estable, todos los campos que puede manejar la base de datos de reparto, indicando:
•	Nombre exacto del campo.
•	Tipo lógico de dato.
•	Quién lo escribe/modifica (Excel, API, panel, microservicio, servidor).
•	Uso principal.
Este contrato es la referencia oficial para:
•	El JSON que se enviará desde Welko (Excel / Python).
•	La tabla de base de datos de reparto.
•	La API /api/orders y el panel web de reparto.
________________________________________
2. Tabla principal de reparto
Nombre sugerido: pedidos_reparto
Clave primaria interna: id (autonumérico, solo servidor)
Nota: todos los nombres de campo son canónicos. No se usan alias, ni “posibles nombres”, ni variantes.
________________________________________
3. Campos de identidad y auditoría
Campo	Tipo lógico	Lo escribe/modifica	Descripción / Uso principal
id	Entero	Servidor (autoincrement)	Identificador interno de la tabla. No se envía desde Excel.
id_pedido	Texto corto	Excel / API Welko (ALTA)	ID funcional del pedido (ej: P000123). Es el ID que se comparte entre Excel, microservicio y panel.
fecha_venta	Fecha	Excel / API Welko	Fecha en que se registró la venta en Welko.
hora_venta	Hora	Excel / API Welko	Hora en que se registró la venta en Welko.
fecha_reparto	Fecha	Servidor / API Welko	Fecha en que el pedido fue insertado en la tabla de reparto (puede coincidir con fecha_venta).
hora_reparto	Hora	Servidor / API Welko	Hora de inserción en reparto. Marca inicio del ciclo de reparto.
fecha_entrega	Fecha (nullable)	Panel / microservicio_estado	Fecha en que se marcó ENTREGADO. Nula mientras está pendiente.
hora_entrega	Hora (nullable)	Panel / microservicio_estado	Hora en que se marcó ENTREGADO. Nula mientras está pendiente.
repartidor_usuario	Texto	Panel (servidor)	Usuario/rol que marcó la entrega (login del panel). Se envía en blanco desde Excel.
________________________________________
4. Campos de cliente (dueño del pedido)
Campo	Tipo lógico	Lo escribe/modifica	Descripción / Uso principal
nombre_cliente	Texto	Excel / API Welko	Nombre completo del cliente en una sola cadena (puede estar armado a partir de nombre + apellidos).
rut_cliente	Texto	Excel / API Welko	RUT del cliente (formato chileno, con dígito verificador).
tipo_cliente_codigo	Texto corto (1 char)	Excel / API Welko	Tipo de cliente: E = Empresa, P = Particular. El panel interpreta y muestra “EMPRESA” / “PARTICULAR”.
permite_credito	Booleano (0/1)	Excel / API Welko	Indica si el cliente tiene crédito habilitado. No significa que la compra esté pagada con crédito.
Política: en la base se almacena solo el código (tipo_cliente_codigo), no el texto. El panel hace la traducción visual.
________________________________________
5. Campos de receptor (quien recibe el pedido)
Campo	Tipo lógico	Lo escribe/modifica	Descripción / Uso principal
nombre_receptor	Texto	Panel / microservicio_estado	Nombre de la persona que recibe el pedido en el momento de la entrega. Puede coincidir o no con nombre_cliente.
rut_receptor	Texto	Panel / microservicio_estado	RUT de la persona que recibe. Puede ser obligatorio o no según casuística futura. Distinto de rut_cliente.
Regla conceptual: cliente ≠ receptor. Son campos separados por diseño.
________________________________________
6. Campos de ubicación
Campo	Tipo lógico	Lo escribe/modifica	Descripción / Uso principal
direccion	Texto	Excel / API Welko	Dirección o texto base de ubicación. En urbano: calle + número + comuna. En rural puede ser texto descriptivo.
coordenadas	Texto	Excel / API Welko	Cadena única con coordenadas o punto de referencia (ej: "−36.825, -73.050" o texto). No se separa en latitud/longitud.
sector_codigo	Texto corto (1 char)	Excel / API Welko	Código de sector: U = Urbano, R = Rural. El panel puede mostrar “URBANO” / “RURAL”.
referencia	Texto	Excel / API Welko	Referencia adicional para encontrar la dirección (puntos de referencia, indicaciones, etc.).
________________________________________
7. Campos de contacto
Campo	Tipo lógico	Lo escribe/modifica	Descripción / Uso principal
telefono1	Texto	Excel / API Welko	Teléfono principal del cliente (formato libre; idealmente 9 dígitos Chile sin +56).
telefono2	Texto	Excel / API Welko	Teléfono secundario (opcional).
________________________________________
8. Campos de pedido y lista de reparto
Campo	Tipo lógico	Lo escribe/modifica	Descripción / Uso principal
detalle_pedido	Texto largo	Excel / API Welko	Resumen legible del pedido (líneas de productos). El panel lo muestra como lista.
valor_total	Entero	Excel / API Welko	Monto total del pedido en pesos chilenos (sin puntos ni formato, solo número).
estado_pedido	Texto corto	Servidor / panel / microservicio	Estado de reparto del pedido. Valores estándar: PENDIENTE / ENTREGADO.
orden_lista	Entero	Panel (drag & drop)	Posición del pedido en la ruta de reparto. Se ajusta desde el panel al reordenar.
Casuística más fina (por ejemplo: “no puede haber método de pago con estado pendiente”) se definirá en una etapa posterior, pero no cambia los nombres ni la existencia de estos campos.
________________________________________
9. Campos de pago (método y origen)
9.1. Método de pago (código interno)
Campo	Tipo lógico	Lo escribe/modifica	Descripción / Uso principal
metodo_pago_codigo	Texto corto	Panel / microservicio_estado / MP	Código interno del método de pago. Valores previstos: E (Efectivo), TA (Tarjeta), TR (Transferencia), C (Crédito), TR-MP (Mercado Pago). Puede ser nulo mientras el pedido está pendiente y sin información de pago.
•	Visualmente el panel muestra:
o	E → “EFECTIVO”
o	TA → “TARJETA”
o	TR → “TRANSFERENCIA”
o	C → “CRÉDITO”
o	TR-MP → “MERCADO PAGO”
Definimos que el código oficial para Mercado Pago será siempre TR-MP en base de datos. El texto visible puede ser “Mercado Pago”.
9.2. Origen del pago
Campo	Tipo lógico	Lo escribe/modifica	Descripción / Uso principal
pago_origen	Texto corto	Panel / microservicio_estado / MP	Indica quién “cerró” el pago: LOCAL (pago gestionado en caja / sistema principal), REPARTIDOR (cerrado en panel de reparto), MP (cerrado directamente por Mercado Pago).
Regla general: este campo sirve para diferenciar quién hizo la acción final, sin duplicar la lógica de “pagado / no pagado”. Esa casuística se fija después.
________________________________________
10. Flags y campos técnicos de pago (opcional / futuro)
En esta versión v1.0 no se exige un campo adicional tipo pagado_flag, porque muchos estados se pueden deducir de estado_pedido + metodo_pago_codigo + pago_origen.
Si en el futuro se decide agregar un flag explícito, se hará como campo nuevo (por ejemplo estado_pago_codigo) en una versión v1.x del contrato.
________________________________________
11. Resumen de fuentes por campo
Para tenerlo claro, a alto nivel:
•	Excel / API Welko (alta):
o	id_pedido, fecha_venta, hora_venta
o	nombre_cliente, rut_cliente, tipo_cliente_codigo, permite_credito
o	direccion, coordenadas, sector_codigo, referencia
o	telefono1, telefono2
o	detalle_pedido, valor_total
•	Servidor / API de reparto:
o	Genera id interno.
o	Inicializa fecha_reparto, hora_reparto.
o	Inicializa estado_pedido en PENDIENTE (si no viene otro estado válido).
•	Panel / microservicio_estado / integraciones de pago:
o	Actualizan metodo_pago_codigo, pago_origen.
o	Escriben/actualizan estado_pedido (por ejemplo, a ENTREGADO).
o	Rellenan nombre_receptor, rut_receptor.
o	Rellenan fecha_entrega, hora_entrega.
o	Rellenan repartidor_usuario.
________________________________________
12. Política de cambios
1.	Este documento se considera CONTRATO DE DATOS – REPARTO v1.0.
2.	Si se agregan campos nuevos en el futuro:
o	Se agregan como columnas nuevas (permitiendo valor nulo al inicio).
o	Se documentan en una versión v1.1, v1.2, etc.
3.	No se renombra ni recicla un campo existente sin actualizar este contrato y sin migración explícita.