Cambios de la API pública

Política (ADR 0027): en v1 solo se añade (endpoints, parámetros opcionales, campos, valores de enum, cabeceras). Los clientes deben tolerar campos y valores desconocidos. Un cambio incompatible (quitar o renombrar, cambiar tipo o semántica, cambiar el orden por defecto o el sobre) sale en /v2, y v1 sigue viva al menos 12 meses con las cabeceras Deprecation y Sunset.

v1.5.1 — 2026-10-06

vehiculo_tipo gana el valor 2R2: camión sencillo o turbo con remolque (2 + 2 ejes). Aparece en /despachos y /citas, y en la dimensión y el filtro vehiculo de /metricas. Si tu integración valida la configuración contra una lista cerrada, añádelo (la política de v1 pide tolerar valores desconocidos).
El 2R2 no está tarifado por el SICETAC ni lo regula el Decreto 1017: TruckDock no le calcula piso de flete ni tarifa por hora (sicetac_valor_piso llega en null, salvo el piso que el despacho ya tuviera con otra configuración o que se haya registrado a mano) y no le genera liquidaciones, ni de origen ni de destino, así que no tiene penalidad de 8 h ni stand-by de 12 h.
Como las configuraciones con «S», un 2R2 se confirma con la placa del remolque (placa_remolque).
Los campos y tipos no cambian.

v1.5.0 — 2026-09-27

Liquidación en destino: además del comprobante de origen (el tiempo en el muelle del generador, uno por despacho), el generador emite un comprobante de destino por cada entrega de una salida con transporte contratado (y del nodo puerto_cliente): el tiempo desde el mayor entre la llegada al destino y la cita de destino vigente hasta «Finalizar operación». Una integración que suponía un comprobante por despacho verá varios: filtra por contexto o agrupa por despacho_id.
LiquidacionV1 gana contexto (origen | destino), entrega_id y entrega_numero (solo en destino), minutos_previos y requiere_nueva_cita. cierre gana el valor finalizacion.
En un comprobante de destino salida_at e inicio_operacion_at van en null, fin_operacion_at (y fin_conteo_at) es «Finalizar operación», cita_at es la cita de destino y espera_min va en null; total_min son los minutos propios del tramo. cita_id sigue siendo la cita del muelle del despacho (null en puerto_cliente, que no usa muelle).
La penalidad del Decreto 1017 y el stand-by se miden sobre el tiempo acumulado del viaje (origen y destinos anteriores, sin contar el tránsito): minutos_previos trae lo acumulado antes del tramo y penalidad_valor es la marginal del tramo. El comprobante de origen no cambia.
Un comprobante de destino con requiere_nueva_cita = true (llegó más de 15 min tarde o la entrega no tenía cita) trae total_min = 0 y sigue en borrador hasta que el generador reprograme la cita de destino.
/liquidaciones acepta el filtro contexto. El PDF de un comprobante de destino dice «Liquidación en destino · Entrega E1 · Despacho D-…».
El KPI costo_transporte_cop de /metricas suma también las liquidaciones de destino emitidas o pagadas; por cliente, cada una se atribuye al cliente de su entrega.

v1.4.0 — 2026-09-27

Corrección de registros de origen y destino: el generador puede corregir la fecha y hora o la ubicación de un evento del muelle, con motivo obligatorio; el registro original se conserva y la API entrega el valor vigente (la última corrección aplicada).
EventoV1 gana corregido (true si se corrigió) y corregido_at (la última corrección, null si nunca). En un evento corregido, ocurrido_at, diferencia_min, llegada_clasificacion, latitud y longitud traen el valor corregido; registrado_at y el orden del cursor no cambian.
/eventos acepta updated_since: eventos registrados o corregidos desde ese instante (registrado_at >= o corregido_at >=). created_since sigue igual (solo eventos nuevos).
Los tiempos de /citas, /citas/{id} y de la cita de /despachos/{id} (llegada_at, inicio_efectivo_at, espera_min, operacion_min, tiempo_logistico_min…) se calculan con los valores vigentes. Aplicar una corrección mueve updated_at de la cita y del despacho: updated_since los re-entrega.
LiquidacionV1 gana corregida_despues_pago_at: una corrección aplicada después de pagar el comprobante no lo cambia; lo marca para conciliar (guarda la última) y mueve su updated_at. Una corrección sobre un comprobante emitido lo anula (estado = anulada) y genera uno nuevo en borrador.
Las correcciones de los registros en destino no se publican en esta versión (los registros en destino tampoco).

v1.3.0 — 2026-09-27

Flujo en destino por entrega: EntregaV1 gana estado_destino (pendiente → llegada → post_operacion → completado) y DespachoV1 gana estado_destino (pendiente si ninguna entrega tiene llegada, en_curso, completado cuando todas se completaron). Tienen flujo en destino las salidas sin nodo con transporte contratado o flota propia y el nodo puerto_cliente; en los demás (planta_puerto, puerto_planta, recepciones de proveedor, cliente retira) llega null, igual que en los despachos que ya estaban cerrados (completado o cancelado) al actualizar.
Cada fase registrada en destino mueve el updated_at de la entrega y, cuando cambia el estado agregado, el del despacho: updated_since los re-entrega.
Re-entrega única al actualizar: para llenar los datos nuevos se escribieron las entregas y los despachos vivos de los carriles con flujo en destino (estado_destino = pendiente) y las entregas cuyo NIT de cliente coincide con un cliente del catálogo (la entrega quedó ligada a ese cliente; el vínculo no se publica). Su updated_at cambió, así que llegan una vez por updated_since en /entregas y /despachos, aunque lo único visible que cambió es estado_destino (o nada, si solo se ligó la entrega al cliente).
Los registros detallados en destino (fotos, ubicación, quién registró) no se publican en esta versión.

v1.2.0 — 2026-09-27

Anulación de despachos: DespachoV1 gana anulado (true si el generador lo anuló) y anulado_at (instante de la anulación, null si no se anuló). Un despacho anulado queda con estado = cancelado; un cancelado corriente trae anulado = false. La anulación mueve updated_at, así que updated_since lo re-entrega.
LiquidacionV1 gana cierre (salida | anulacion) y fin_conteo_at. Con cierre = salida (todas las liquidaciones anteriores), fin_conteo_at es la salida_at. Con cierre = anulacion, el despacho se anuló con el camión ya en planta: se liquida solo el tiempo logístico hasta la anulación (fin_conteo_at), salida_at llega en null y el generador valida el borrador antes de emitirlo.
/metricas/cumplimiento_pct: la solicitud pendiente de un despacho que se cancela o se anula se cierra como cancelada (antes el vencimiento la marcaba como vencida) y no cuenta en el porcentaje, igual que las pendientes. Las filas ganan la columna canceladas y vencidas ya no incluye esas solicitudes. Las vencidas históricas no se reescriben; las que seguían pendientes en despachos ya cancelados pasaron a canceladas.
Desde esta versión solo se generan liquidaciones de salidas con transporte contratado (y del nodo puerto_planta contratado); una salida de flota propia o de cliente retira no genera liquidación.

Nota de datos — número de entrega y número de despacho (sin cambio de contrato)

Las entregas sin número reciben uno automático E1, E2… (en el orden del despacho); un número escrito a mano se respeta. Las entregas existentes quedaron numeradas al actualizar y se re-entregan una vez por updated_since en /entregas (su updated_at cambió). Dentro de un mismo despacho el numero de la entrega no se repite.
El numero del despacho es único en la cuenta. Los pocos repetidos que existían conservaron el más antiguo y los demás recibieron el sufijo -2, -3… (también se re-entregan una vez).
En los despachos puerto_planta, cita_destino_at de su entrega es la cita en el muelle de la planta (la misma cita_at del despacho); cuando esa cita cambia, la entrega se re-entrega por updated_since.
Los campos y tipos no cambian; la versión sigue en 1.1.0.

v1.1.0 — 2026-09-24

Costos de las operaciones portuarias y aéreas, con el alcance liquidaciones:read: /operaciones-logisticas, /operaciones-logisticas/{id} (con lineas[]: los despachos terrestres y los servicios de la operación), /servicios-portuarios y /servicios-portuarios/{id}. Filtros desde/hasta, tipo (maritimo | aereo) y updated_since; en servicios también agente_id, operacion_id y asociado. costo_total = fletes pactados (un despacho cancelado aporta 0) + servicios; el tiempo liquidado es informativo (valor_tiempo_liquidado) y no entra al total.
DespachoV1 gana nodo (planta_puerto | puerto_cliente | puerto_planta), puerto_id, puerto_nombre, puerto_tipo (puerto | aeropuerto), operacion_id y operacion_numero. Un despacho puerto_cliente no tiene cita ni muelle; uno puerto_planta es una entrada (tipo_operacion = entrada) que sí lleva flete.
/despachos acepta el filtro operacion_id.
El alcance liquidaciones:read cubre ahora también estos costos: las llaves que ya lo tienen los ven sin cambios.

v1.0.0 — 2026-09-22

Primera versión: llaves por tenant con alcances (despachos:read, citas:read, liquidaciones:read, metricas:read, metricas_dinero:read).
Recursos: /me, /despachos, /despachos/{id}, /entregas, /entregas/{id}, /citas, /citas/{id}, /citas/{id}/eventos, /eventos, /muelles, /transportadoras, /liquidaciones, /liquidaciones/{id}, /liquidaciones/{id}/pdf, /metricas, /metricas/{key}.
Las métricas conductores_bloqueados_proximas_citas y pendientes_accion no se exponen (datos personales de conductores y mecánica interna de asignación); el aplanado descarta cualquier columna con esos fragmentos.
Guía de integración y este historial publicados en /v1/guia y /v1/cambios.
Paginación por cursor (next_cursor/next), sincronización incremental (updated_since, created_since), errores application/problem+json, límites de tasa con cabeceras X-RateLimit-*.