Welko · Contratos JSON (v1.1)
Versión del documento: v1.1
Fecha: 2025-11-21

DESCRIPCIÓN GENERAL

Este documento define los contratos JSON entre los distintos componentes del sistema Welko (paneles web, microservicios, APIs PHP, etc.).

CONVENCIONES GENERALES

Formato JSON: siempre "application/json; charset=utf-8".

Codificación: UTF-8.

Montos en CLP: enteros, sin puntos ni símbolos.
Ejemplo: 60000 (no "60.000", no "$ 60.000.-").

RUT chileno:
· En el request se puede enviar sin puntos y con guion, o solo dígitos + K. El backend puede normalizar.
· En las respuestas se puede devolver formateado ("12.345.678-9").

Fechas/hora: cuando se usen, preferir siempre formateos claros:
· ISO 8601: 2025-11-19T18:30:00-03:00
· o "YYYY-MM-DD" para fechas simples.

TIPOS DE DATOS (CONVENCIÓN EN ESTE DOCUMENTO)

string : texto.

number : número (entero o decimal, aquí normalmente entero).

boolean : true / false.

null : ausencia de valor.

enum : texto acotado a un conjunto (ej: "ENTREGADO" | "PENDIENTE").

CONTRATO: EVENTOESTADOREPARTO (PANEL → MICROSERVICIO_ESTADO) · v1

1.1 Descripción

El panel de Reparto Web envía un evento de estado al microservicio "microservicio_estado" (vía un proxy PHP "verificar_estado_proxy.php"), indicando que un pedido ha sido:

Entregado por primera vez ("ENTREGADO"), o

Corregido/actualizado ("ACTUALIZADO") en cuanto a método de pago o datos del receptor.

Este evento debe ser idempotente en el microservicio: si llega dos veces el mismo estado para el mismo "pedido_id", el backend debe manejarlo sin duplicar efectos.

1.2 Endpoint

Cliente:

Panel Reparto Web (reparto_panel.php).

Servidor:

PHP: /api/verificar_estado_proxy.php

que a su vez llama al microservicio "microservicio_estado".

Método HTTP:

POST

URL (lado PHP):

POST {API_BASE}/verificar_estado_proxy.php

Cabeceras mínimas:

Content-Type: application/json
Authorization: Bearer {TOKEN_SESION}

1.3 Request (JSON)

1.3.1 Campos

Campo: pedido_id
Tipo: string
Obligatorio: Sí
Descripción: ID lógico del pedido Welko. Puede venir de id_pedido, pedido_id, etc., pero aquí ya va normalizado.
Ejemplo: "20001"

Campo: pago
Tipo: string
Obligatorio: Sí
Descripción: Código del método de pago normalizado. Ver tabla de códigos más abajo.
Ejemplo: "E"

Campo: estado
Tipo: string
Obligatorio: Sí
Descripción: Estado del evento enviado al microservicio: "ENTREGADO" o "ACTUALIZADO".
Ejemplo: "ENTREGADO"

Campo: monto
Tipo: number
Obligatorio: Sí
Descripción: Monto entero en pesos chilenos del pedido (sin puntos ni símbolos).
Ejemplo: 60000

Campo: origen_pago
Tipo: string
Obligatorio: Sí
Descripción: Origen del evento de pago. Desde el panel de reparto siempre "REPARTIDOR".
Ejemplo: "REPARTIDOR"

Campo: rut_receptor
Tipo: string
Obligatorio: No
Descripción: RUT del receptor final (persona que recibe el pedido). Puede ir vacío.
Ejemplo: "12.345.678-9"

Campo: nombre_receptor
Tipo: string
Obligatorio: Sí
Descripción: Nombre del receptor final, normalmente en mayúsculas.
Ejemplo: "JUAN PÉREZ"

Campo: rut_cliente
Tipo: string
Obligatorio: No
Descripción: RUT del cliente dueño del pedido (empresa o particular).
Ejemplo: "76.543.210-8"

Campo: fuente_evento
Tipo: string
Obligatorio: Sí
Descripción: Identificador de la fuente del evento. Desde el panel siempre "PANEL".
Ejemplo: "PANEL"

Códigos válidos para "pago"

"E" → EFECTIVO

"TA" → TARJETA

"TR" → TRANSFERENCIA

"C" → CRÉDITO

"TR-MP" → Transferencia vía Mercado Pago (webhook MP)

Valores válidos para "estado"

"ENTREGADO" → primer registro de entrega

"ACTUALIZADO" → corrección posterior sobre un pedido ya entregado

1.3.2 Ejemplos de Request válidos

Ejemplo de Request (ENTREGADO):

{
"pedido_id": "20001",
"pago": "E",
"estado": "ENTREGADO",
"monto": 60000,
"origen_pago": "REPARTIDOR",
"rut_receptor": "12.345.678-9",
"nombre_receptor": "JUAN PÉREZ",
"rut_cliente": "76.543.210-8",
"fuente_evento": "PANEL"
}

Ejemplo de actualización (ya estaba entregado, se ajusta método de pago):

{
"pedido_id": "20001",
"pago": "TR",
"estado": "ACTUALIZADO",
"monto": 60000,
"origen_pago": "REPARTIDOR",
"rut_receptor": "12.345.678-9",
"nombre_receptor": "JUAN PÉREZ",
"rut_cliente": "76.543.210-8",
"fuente_evento": "PANEL"
}

1.4 Response

1.4.1 Respuesta de éxito

Formato mínimo esperado por el panel:

{
"ok": true
}

Se pueden agregar más campos (por ejemplo, "estado_interno", "folio", etc.), pero no son obligatorios para el panel.

1.4.2 Respuesta de error

Formato mínimo:

{
"ok": false,
"error": "Mensaje de error legible para logs"
}

Comportamiento esperado del panel:

Si "ok" es false o falta, muestra un mensaje al usuario con el texto de "error" (si viene).

Si no hay campo "error", usa un mensaje genérico:
"Error desconocido en verificación de estado."

1.5 Notas de compatibilidad

Versión v1:

"pedido_id", "pago", "estado", "monto", "origen_pago", "nombre_receptor", "fuente_evento" son campos base.

"rut_receptor" y "rut_cliente" pueden venir vacíos ("").

Si en el futuro se agregan campos nuevos, deben ser opcionales y compatibles con este formato.
La versión v1 no debe romperse.

[PLANTILLA] CONTRATO: AGREGAR PRODUCTO (POR DEFINIR) · v1

Esta sección es solo PLANTILLA.
Cuando tengamos el JSON real de “agregar producto” (endpoint exacto y ejemplo), se deben rellenar los campos a continuación y fijar la versión.

2.1 Descripción

(Ejemplo de descripción)
Permite agregar un producto a un pedido existente en el sistema Welko desde el módulo que corresponda (panel de ventas, panel reparto, etc.).

2.2 Endpoint

Cliente:

(ejemplo) Panel Ventas Web / Panel Reparto / App móvil.

Servidor:

(ejemplo) /api/orders/add_item.php

Método HTTP:

POST

URL:

POST {API_BASE}/RUTA/DEL/ENDPOINT

Cabeceras mínimas:

Content-Type: application/json
Authorization: Bearer {TOKEN_SESION}

2.3 Request (JSON) · borrador

Campos (borrador, a ajustar cuando tengamos el contrato real):

Campo: pedido_id
Tipo: string
Obligatorio: Sí
Descripción: ID del pedido al que se agrega producto.
Ejemplo: "20001"

Campo: producto_id
Tipo: number
Obligatorio: Sí
Descripción: ID interno del producto.
Ejemplo: 15

Campo: descripcion
Tipo: string
Obligatorio: Sí
Descripción: Texto descriptivo del ítem.
Ejemplo: "BOTELLÓN 20 LITROS"

Campo: cantidad
Tipo: number
Obligatorio: Sí
Descripción: Cantidad del producto.
Ejemplo: 3

Campo: precio_unitario
Tipo: number
Obligatorio: Sí
Descripción: Precio unitario en CLP.
Ejemplo: 5000

Campo: observacion
Tipo: string
Obligatorio: No
Descripción: Nota opcional.
Ejemplo: "PROMO JULIO"

Ejemplo de Request (borrador):

{
"pedido_id": "20001",
"producto_id": 15,
"descripcion": "BOTELLÓN 20 LITROS",
"cantidad": 3,
"precio_unitario": 5000,
"observacion": "PROMO JULIO"
}

2.4 Response (borrador)

Ejemplo de respuesta de éxito:

{
"ok": true,
"id_item": 123,
"item": {
"id_item": 123,
"pedido_id": "20001",
"producto_id": 15,
"descripcion": "BOTELLÓN 20 LITROS",
"cantidad": 3,
"precio_unitario": 5000,
"subtotal": 15000
}
}

Ejemplo de error:

{
"ok": false,
"error": "Producto no encontrado"
}

2.5 Notas de compatibilidad

Completar cuando el endpoint esté implementado y probado.

Al pasar a v2, documentar claramente qué campos se agregan o cambian, manteniendo la compatibilidad con v1 en lo posible.

CONTROL DE VERSIONES (CHANGELOG)

v1.1 – 2025-11-21

Se documenta formalmente el contrato "EventoEstadoReparto (PANEL → microservicio_estado) · v1":
· Request con "pedido_id", "pago", "estado", "monto", "origen_pago", "nombre_receptor", "rut_receptor" (opcional), "rut_cliente" (opcional), "fuente_evento".
· Respuestas "ok: true" / "ok: false" con manejo estándar de errores en el panel.

Se incluye explícitamente la plantilla de contrato "Agregar producto" · v1 (borrador).

Se añaden secciones iniciales de:
· Convenciones generales.
· Tipos de datos.
· Descripción general del rol de este documento dentro del ecosistema de contratos Welko.

v1.0 – Versión inicial

Versión base de los contratos JSON internos de Welko.

La fecha exacta de emisión inicial no se detalla en este documento.

Servía como referencia preliminar antes de formalizar la versión 1.1 con el contrato de "EventoEstadoReparto".