Cupo — API pública de guías¶

Estado: diseño aprobado por Iker el 2026-10-22 para el piloto (solo API, solo Interrapidísimo). No hay código desplegado. Las decisiones de negocio que dependen de gerencia están en Pendiente con gerencia.

1. Resumen¶

Hoy nada limita cuántas guías crea una tienda. La wallet (ResumenSaldoActualLogigho) solo se mueve cuando ApiLambdaLiquidacionesLogighoAOT liquida una guía entregada o devuelta, 2 a 5 días después de crearla. Una tienda con 100 000 de saldo puede crear 300 000 en guías y terminar en negativo; si no paga, pierde LogiGho.

El cupo limita lo que una tienda puede crear por la API: antes de crear cada guía se reserva su costo de peor caso (calculado con las mismas fórmulas que la liquidación) y la reserva se libera cuando la guía se liquida, se anula o falla. Si no hay Disponible, la guía no se crea.

Disponible = SaldoConfiable + LimiteCredito − ExposicionExterna − Reservado

Principios:

• No cambia las liquidaciones ni la wallet. El cupo solo lee; nunca escribe en ResumenSaldoActualLogigho ni en LiquidacionesLogigho.
• Un solo cálculo. La reserva sale de la misma fórmula con la que luego se liquida la guía, no de una tarifa paralela.
• Seguro ante fallos. Si algo no se puede calcular, la guía se rechaza; nunca se reserva 0.
• Piloto controlado. Pocas tiendas en lista blanca, primero en modo OBSERVAR, luego APLICAR.
• Operable. Finanzas ve el cupo en solo lectura; el integrador consulta su cupo y sus movimientos.

2. Glosario¶

3. Alcance del piloto¶

Encaja con las fases de la API de guías: F0 documentación, F1 Inter con cupo, F3 resto de transportadoras, F4 dashboard.

4. Hallazgos verificados que condicionan el diseño¶

Revisión de código del 2026-10-22. Rutas relativas a Lambdas_NET_LogiGho/LambdasLogiGho.Aplicacion/.

4.1 La wallet y el saldo¶

4.2 La liquidación¶

4.3 Inter al crear la guía¶

4.4 Plataforma¶

5. Modos y estados¶

5.1 Modo (contrato; lo decide gerencia)¶

5.2 Suspensión (automática; operativa)¶

La suspensión es por tienda. ApiClientes.Estado = SUSPENDIDO_CUPO solo se usa cuando todas las tiendas permitidas del cliente están suspendidas (informativo; pendiente de alinear con Colecciones).

5.3 Aplicación (por tienda)¶

Una tienda fuera de la lista blanca del piloto no puede crear por la API.

stateDiagram-v2
    [*] --> PREPAGO: alta de tienda
    PREPAGO --> CREDITO: gerencia aprueba límite
    CREDITO --> PREPAGO: gerencia retira el límite
    PREPAGO --> BLOQUEADO: decisión manual
    CREDITO --> BLOQUEADO: decisión manual
    BLOQUEADO --> PREPAGO: decisión manual

    state "Suspensión (ortogonal al modo)" as S {
        [*] --> Activa: Disponible ≤ 0
        Activa --> [*]: Operaciones desbloquea con Disponible > 0
    }

6. Modelo de datos¶

Colecciones nuevas con prefijo Api. Las demás están en Colecciones.

6.1 ApiCupoTiendas¶

Un documento por tienda. _id es el IdTienda entero normalizado.

{
  "_id": 1234,
  "Tienda": "Tienda Ejemplo",
  "Modo": "PREPAGO",
  "LimiteCredito": 0,
  "Aplicacion": "OBSERVAR",
  "Suspension": { "Activa": false, "Motivo": null, "Desde": null, "Por": null },
  "Parametros": {
    "DescontarRecaudoNoPagado": false,
    "MargenEstimacionPct": 25,
    "GuiasPorDiaTienda": 200,
    "TopeLote": 50,
    "VentanaExposicionDias": 90
  },
  "Saldo": {
    "Confiable": 100000,
    "Liquidaciones": 130000,
    "Retiros": 40000,
    "Novedades": 10000,
    "RecaudoNoPagado": 0,
    "Corte": "6718f2a1c3e4b5d6e7f80912",
    "CalculadoEn": "2026-10-22T17:40:00Z"
  },
  "ExposicionExterna": 0,
  "Reservado": 0,
  "Base": 100000,
  "Disponible": 100000,
  "Alertas": { "Nivel80": false, "Nivel100": false },
  "Version": 1,
  "CreadoEn": "2026-10-22T17:00:00Z",
  "ActualizadoEn": "2026-10-22T17:40:00Z"
}

• Base = Saldo.Confiable + LimiteCredito − ExposicionExterna.
• Disponible = Base − Reservado. Se materializa para poder usar una guarda simple (Disponible ≥ monto) sin $expr.
• Todos los montos son pesos enteros (long). La reserva se redondea hacia arriba al peso; el saldo se redondea como la wallet (AwayFromZero).
• Índices: _id (único por definición); { Aplicacion: 1, "Suspension.Activa": 1 }.

6.2 ApiMovimientosCupo (ledger)¶

Solo inserciones. Nunca update ni delete.

{
  "_id": "sol_01HZX...:Reserva:1",
  "IdTienda": 1234,
  "ClienteId": "cli_abc",
  "SolicitudId": "sol_01HZX...",
  "NumeroGuia": null,
  "Tipo": "Reserva",
  "Monto": 14250,
  "Origen": "ESTIMADO",
  "Desglose": { "Flete": 11250, "Seguro": 1500, "ServicioContraPago": 0, "Otros": 1500 },
  "ReservadoDespues": 14250,
  "DisponibleDespues": 85750,
  "HabriaRechazado": false,
  "Actor": { "Tipo": "SISTEMA", "Id": "ApiLambdaGuias" },
  "Motivo": null,
  "TraceId": "1-67...",
  "Fecha": "2026-10-22T17:41:03Z"
}

• _id determinista {SolicitudId}:{Tipo}:{Secuencia}: la idempotencia sale gratis (clave duplicada = ya aplicado). Los movimientos manuales usan un GUID.
• Índices: { IdTienda: 1, Fecha: -1 }; { NumeroGuia: 1 }; { ClienteId: 1, Fecha: -1 }.
• Σ(Reserva + AjusteReserva + Correccion) − Σ(Liberacion + Consumo) de una tienda debe ser igual a ApiCupoTiendas.Reservado.

Diferencia con Colecciones: ahí el índice único del ledger es {SolicitudId, Tipo}. No alcanza: una solicitud puede tener varios ajustes. Aquí la unicidad la da el _id determinista con Secuencia. Actualizar colecciones.md al aprobar este documento.

6.3 ApiContadoresUso¶

Conteos de guías por día. Se usa una sola colección con dos tipos de documento:

TTL de 90 días. El conteo se incrementa con findOneAndUpdate({_id, Guias: {$lt: limite}}, {$inc: {Guias: 1}}, upsert). Si el documento ya existe y alcanzó el límite, el upsert falla por clave duplicada: eso es "límite alcanzado". Si la creación falla definitivamente, el contador se decrementa.

Diferencia con Colecciones: ahí el índice es {ClienteId, Fecha}. Se propone el _id compuesto para cubrir también tienda.

6.4 Relación con ApiSolicitudesGuia¶

ApiSolicitudesGuia (ya diseñada) lleva la máquina de estados RECIBIDA → RESERVADA → CREANDO → CREADA | FALLIDA | INCIERTA → ANULADA y los montos estimados y reales. Para el cupo agrega: Reserva (monto vigente), Provisional (resultado de la calculadora con su origen ESTIMADO/REAL y versión de fórmulas) y ReservaViva (booleano que el reconciliador baja al liberar o consumir).

7. Liquidación provisional (calculadora)¶

7.1 Idea¶

La reserva es la liquidación de la guía calculada antes de tiempo: el mismo resultado que luego escribirá ApiLambdaLiquidacionesLogighoAOT en LiquidacionesLogigho.Liquidacion. Se calculan los dos escenarios y se reserva el más costoso:

Reserva = max( −Liquidacion(entrega), −Liquidacion(devolucion) )

7.2 Fórmulas del legacy (Interrapidísimo, prepago)¶

DepurarLiquidacionUseCase.cs (rutas bajo Logigho/ApiLambdaLiquidacionesLogighoAOT/Aplicacion/CasosUso/Liquidacion/). Para una guía sin contrapago (TotalRecaudo = 0):

Los porcentajes y montos salen de CostosTransporteTienda (por nombre de tienda, transportadora y EstadoGuia, con reintentos y fila "Generico Interrapidisimo …"; :102-157) y de AdministracionCostos (:204-239).

Nota de nombres. En el legacy, TotalSobreflete es el seguro y TotalServicio es el servicio de recaudo. Para el integrador se exponen como seguro y servicioContraPago.

7.3 Qué se sabe al crear y qué no¶

Por eso la reserva tiene dos tiempos:

1. Estimación (antes de crear en Inter): TotalFlete desconocido. Se usa max(cotización de Inter si existe, flete máximo configurado de la tienda) × (1 + MargenEstimacionPct/100) como sustituto de TotalFlete, Trayecto desconocido ⇒ el mayor de las columnas de flete configuradas, y el piso carrier + 200 no se evalúa.
2. Ajuste (con la respuesta de Inter): se recalcula con los valores reales y se reemplaza la reserva (AjusteReserva por la diferencia). El margen deja de aplicar.

Regla de recaudo: si TotalRecaudo = 0, servicioContraPago = 0 en lo que se le cobra a la tienda y se le muestra al integrador. Si Inter devuelve un valorServicioContraPago > 0 con recaudo 0, se ignora para la tienda, se guarda en el costo del carrier y se emite una alarma (LogiGho estaría pagando un cobro que no recupera).

7.4 Ejemplo calculado (valores ilustrativos, no son tarifas reales)¶

Tienda: FleteUrbano 6 000, FleteRegional 7 500, FleteNacionalMetropolitano 9 000, %Seguro 1,5 con valor declarado 100 000 y Seguro = SI (seguro de tienda 1 500), %FleteEntregado 0, %FleteDevolucion 0, OtroDevolucion 1 500 fijo, el resto de costos en 0. Prepago.

Estimación (margen 25 %, sin valores reales):

TotalFlete_est = 9 000 × 1,25                       = 11 250
TotalFleteTienda = 11 250 + 0 + 1 500               = 12 750
Entrega     = −12 750
Devolución  = −12 750 − 1 500                       = −14 250
Reserva     = 14 250

Respuesta de Inter: valorFlete 5 530, valorSobreFlete 2 577, valorServicioContraPago 0.

Flete = max(5 530, 9 000)                            = 9 000
TotalFleteTienda = 9 000 + 0 + 1 500                 = 10 500
TotalTransportadora = −(5 530 + 0 + 2 577)           = −8 107
Entrega: FleteFinal = −10 500; ¿−8 107 < −10 500? no ⇒ sin piso      ⇒ −10 500
Devolución: −10 500 − 1 500                                           ⇒ −12 000
Reserva exacta = 12 000   (ajuste −2 250 respecto de la estimación)

Caso excepcional: Inter cobra valorFlete 14 000.

Flete = max(14 000, 9 000) = 14 000;  TotalFleteTienda = 15 500
TotalTransportadora = −(14 000 + 0 + 2 577) = −16 577
Entrega: FleteFinal = −15 500; −16 577 < −15 500 ⇒ piso: −16 577 − 200 = −16 777
Devolución: −15 500 − 1 500 = −17 000
Reserva exacta = 17 000   (ajuste +2 750 respecto de la estimación)

7.5 Dónde vive la calculadora¶

Decisión (ajustada el 2026-10-24): una sola implementación de las fórmulas, como clase pura en el proyecto Logigho.Guias.Liquidacion (carpeta Guias/; sin Mongo, AWS ni reloj). La usa la función Lambda ApiLambdaGuiasCalculadora, que ApiLambdaGuias, el worker y el reconciliador invocan con Lambda.Invoke (sin API Gateway público; permiso IAM lambda:InvokeFunction acotado a esa función, en Terraform).

ApiLambdaGuias no copia fórmulas. La función de cálculo es dueña de las tarifas: lee de solo lectura CostosTransporteTienda (solo Interrapidísimo), AdministracionCostos, Marketing y TarifasInter, y las guarda 60 s en memoria (el job actual carga 9 colecciones completas; no sirve por guía).

Divergencia deliberada con el diseño inicial: el diseño decía que LiquidarAsync también llamaría a esta clase. No se tocó ApiLambdaLiquidacionesLogighoAOT (regla: no se cambia la liquidación para sacar la API). La clase replica DepurarLiquidacionUseCase, y lo que impide que se desincronicen son las pruebas doradas de §7.6. Si algún día se quiere una sola fuente de verdad, el job pasaría a usar este proyecto; es un cambio aparte que decide Iker.

Costo y mitigación: es una dependencia en línea. Si la función no responde, la API rechaza con 503 CUPO_NO_DISPONIBLE y no reserva 0 (RC-014). Como el código de Guias/ vive en el mismo repo de Lambdas, si la latencia del Invoke molesta se puede pasar a referencia de proyecto sin cambiar las fórmulas.

Contrato:

// Request (nombres tal como los usa el código: camelCase)
{
  "tienda": "Tienda Ejemplo",
  "transportadora": "INTERRAPIDISIMO",
  "peso": 1.0,
  "valorDeclarado": 100000,
  "seguro": true,
  "aplicaContraPago": false,
  "totalRecaudo": 0,
  "margenEstimacionPct": 25,
  "valoresCarrier": null,
  "valorDropshipper": null
}

// Response
{
  "motor": "LEGACY",
  "origen": "ESTIMADO",
  "entrega":    { "liquidacion": -12750, "desglose": { "flete": 11250, "seguro": 1500, "servicioContraPago": 0, "otros": 0 } },
  "devolucion": { "liquidacion": -14250, "desglose": { "flete": 11250, "seguro": 1500, "servicioContraPago": 0, "otros": 1500 } },
  "reserva": 14250,
  "version": "legacy-2026.10",
  "advertencias": []
}

valoresCarrier = { "totalFlete": 5530, "totalServicio": 0, "totalSobreflete": 2577 } cambia origen a REAL. El trayecto ya no viaja en la petición: la función lo busca en TarifasInter por el flete cobrado (si no hay coincidencia, advertencias trae TRAYECTO_NO_RESUELTO y se usa la columna de flete más cara). valorDropshipper solo se envía si el pedido llevará Tiendaproveedor. Los errores vuelven como datos en error (TARIFA_NO_RESUELTA, SOLICITUD_INVALIDA), no como caída de la función; una caída de la función es 503 CUPO_NO_DISPONIBLE.

Notas de lo implementado (2026-10-24):

• Los ejemplos de §7.4 son de un paquete de hasta 1 kg. Con más de 1 kg la liquidación calcula Flete = TotalFlete × (1 + %KiloAdicional/100) y no usa las columnas por trayecto; el ejemplo de la petición ya no lleva 1,5 kg por eso.
• En la estimación, «el mayor de las columnas» son urbano, regional, nacional/metropolitano y municipal. FleteReexpedido no cuenta: es un trayecto que aparece después de crear la guía (al reenviar el paquete); incluirlo multiplicaría la reserva de toda guía (en una tienda real: 32 500 contra 13 820 de las demás columnas). Decisión pendiente de Iker.
• La reserva se redondea hacia arriba al peso (RC-019) y nunca es cero; si la liquidación de peor caso no es un costo, o la tienda no tiene ningún flete configurado, es TARIFA_NO_RESUELTA.
• Sin fila propia de la tienda en CostosTransporteTienda se usa la fila Generico Interrapidisimo …; como en la liquidación, entonces el seguro depende solo del recaudo (0 en una guía prepagada). Si falta también la genérica, TARIFA_NO_RESUELTA.
• Se incluyen AdministracionCostos (PicyPac, otros, confirmación, adelanto, descuentos de flete), Marketing y, si se envía, el valor del proveedor (ValorDropshipper, que la liquidación descuenta en la entrega). La API hoy no escribe Tiendaproveedor en PedidosInter, así que no lo envía; si se agrega, la reserva de una guía de dropshipping crece en el valor de los productos del proveedor.

7.6 Pruebas y calibración¶

1. Pruebas doradas (hechas el 2026-10-24): la función pura corre sobre liquidaciones reales ya guardadas en LiquidacionesLogigho de PreProd y reproduce todos los campos (flete, seguro, comisión de recaudo, total de la tienda, flete final, otros servicios y liquidación) con diferencia 0 en 92 de 92 guías (Interrapidísimo 22, Envía 48, Servientrega 22; las 33 filas restantes del volcado son las liquidaciones del proveedor, que no son de la guía). El fixture (test/.../Datos/golden-liquidaciones-preprod.json) está anonimizado: tiendas y guías con alias. Limitación: esas liquidaciones no guardan el peso ni el trayecto ni el valor declarado, así que la herramienta que arma el fixture busca los datos de entrada legítimos con los que se reproducen todos los campos; ninguna fórmula se ajustó para que cuadre. AdministracionCostos y Marketing están vacías en PreProd: sus valores salen de lo que cada liquidación guardó. Falta repetir la corrida con las liquidaciones de producción (solo lectura) cuando Iker lo autorice.
2. Contraverificación con LogighoPricingService.CalcularTarifaInterEnMemoriaAsync, que usa el mismo modelo de tarifas.
3. Margen: durante OBSERVAR se mide LiquidacionReal − Provisional por transportadora; el margen se calibra con el percentil 95.
4. Regresión del motor dinámico al extraer el método puro (TCC): mismas salidas que hoy.

La carpeta de pruebas de ApiLambdaLiquidacionesLogighoAOT.Tests en este checkout solo contiene bin/ y obj/; no se pudo comprobar la cobertura actual.

7.7 Qué pasa con otras transportadoras¶

No se migra Inter al motor dinámico para el piloto: cambiaría las liquidaciones actuales (17 diferencias entre motores: mínimos de servicio y recaudo, máximo contra el carrier, tabla de peso, trayecto sin resolver, base del seguro en prepago, doble fecha, entre otras).

8. Flujos¶

8.1 Crear una guía (con reserva)¶

sequenceDiagram
    autonumber
    participant I as Integrador
    participant A as ApiLambdaGuias
    participant C as Calculadora (Lambda)
    participant D as DocumentDB
    participant Q as SQS
    participant W as Worker
    participant T as Inter

    I->>A: POST /v1/guias (Idempotency-Key)
    A->>D: ¿cliente activo? ¿tienda en lista blanca? conteos
    A->>C: liquidación provisional (ESTIMADO)
    C-->>A: reserva estimada
    A->>D: findOneAndUpdate cupo (Disponible ≥ monto) $inc
    alt sin cupo en APLICAR
        A-->>I: 422 CUPO_INSUFICIENTE
    else con cupo
        A->>D: línea Reserva en el ledger; solicitud RESERVADA
        A->>Q: mensaje por guía
        Q->>W: procesa
        W->>T: crea la guía
        T-->>W: valorFlete, valorSobreFlete, valorServicioContraPago
        W->>C: liquidación provisional (REAL)
        C-->>W: reserva exacta
        W->>D: $inc por la diferencia; AjusteReserva; solicitud CREADA
        W-->>I: costos con incrementos de LogiGho
    end

Detalle del paso de reserva:

findOneAndUpdate(
  { _id: idTienda, Modo: { $ne: "BLOQUEADO" }, "Suspension.Activa": false, Disponible: { $gte: monto } },
  { $inc: { Disponible: -monto, Reservado: +monto } },
  { returnDocument: "after" })

• Orden: 1) $inc con guarda; 2) insertar la línea Reserva; 3) pasar la solicitud a RESERVADA. Si falla entre 1 y 2, Reservado queda mayor que Σ ledger (lado conservador) y la auditoría lo corrige.
• En OBSERVAR la guarda de Disponible y la de suspensión no se aplican; solo se registra HabriaRechazado.
• Lotes: una sola reserva por la suma de las estimaciones del lote (todo o nada), más una línea de ledger por guía. Si no alcanza, se rechaza el lote completo (422 CUPO_INSUFICIENTE).
• Después de un ajuste que deje Disponible < 0 (la guía ya existe en el carrier): la tienda queda suspendida y el negativo queda acotado al error de la estimación.

8.2 Falla o incertidumbre al crear en el carrier¶

8.3 Anulación¶

POST /v1/guias/{numero}/anulacion solo procede si la guía está en estados iniciales (Creado, "generada en…", "en alistamiento del cliente"). Una guía despachada no se puede anular: su reserva sigue hasta que se liquide. Al anular: Liberacion por el monto vigente. La anulación es gratis (decisión de Iker; no hay modelo de negocio sobre anulaciones).

8.4 Liberación al liquidar (reconciliador)¶

El reconciliador vive en ApiLambdaGuiasWorker y corre cada 5 minutos para las tiendas con reservas vivas o en lista blanca. El orden es parte de la regla:

1. Leer el documento de cupo y su Version.
2. Primero calcular el conjunto L de guías con reserva viva que ya tienen liquidación ("Numero Guia" en LiquidacionesLogigho, Estado ≠ "Referido") o estado Anulada.
3. Después calcular SaldoConfiable (liquidaciones, retiros y novedades, buscando el IdTienda como entero y como string), de forma incremental (§8.8).
4. Calcular ExposicionExterna (§8.6), con la consulta acotada de §8.8.
5. Base' = SaldoConfiable + LimiteCredito − ExposicionExterna y liberado = Σ reserva(L).
6. Una sola escritura con guarda de versión: $inc { Disponible: (Base' − Base) + liberado, Reservado: −liberado, Version: 1 }, $set { Base, Saldo, ExposicionExterna, ... }.
7. Insertar líneas Consumo (con la liquidación real) y Recalculo.

Por qué ese orden: si el saldo se leyera antes que L, una guía liquidada entre ambas lecturas se liberaría sin que su costo esté todavía en el saldo y el Disponible quedaría inflado (lado peligroso). Con L primero, lo peor que pasa es que una guía quede contada dos veces hasta el próximo ciclo (lado conservador).

Como las reservas y los ajustes solo usan $inc, que es conmutativo, el reconciliador no necesita bloquear: aplica el delta aunque entren reservas mientras calcula. Solo la guarda de Version evita dos reconciliadores simultáneos sobre la misma tienda.

8.5 Retiros y novedades¶

• Retiro: el monto debe ser ≤ Disponible (RC-029). Es lo que impide crear guías y luego retirar todo el saldo. Un retiro Pendiente o Aprobado ya resta de SaldoConfiable. La validación vive en el flujo de desembolso; es un cambio de Angular y su backend, fuera del piloto API-only (ver Pendiente con gerencia). Mientras tanto Finanzas revisa los retiros de las tiendas del piloto.
• Novedad negativa (por ejemplo, re-pesaje: la transportadora cobra más de lo reservado): se registra en la wallet como hoy (NovedadesLogigho). SaldoConfiable la recoge en el siguiente recálculo. No se ajusta el ledger.

8.6 Exposición de otros canales¶

Las guías que crean Angular y las lambdas no reservan, pero sí gastan saldo cuando se liquidan. El reconciliador las cuenta:

• Guías de la tienda en PedidosInter sin documento en LiquidacionesLogigho, no Anulada, creadas dentro de VentanaExposicionDias (90 por defecto) y que no estén en ApiSolicitudesGuia.
• Cada una se valora con la calculadora en modo REAL (ya tienen Total Flete, Total Servicio, Total Sobreflete).
• Solo para tiendas de la lista blanca, con una consulta por índice y acotada. Nunca se escanea PedidosInter completo: el presupuesto de carga está en §8.8.

En v1 esta exposición reduce el Disponible de la API pero no bloquea Angular ni las lambdas.

8.7 Auditoría diaria¶

Para cada tienda: recalcular Reservado desde el ledger y compararlo con el documento. Si difiere: línea Correccion, ajuste del documento y alarma. También se recalcula Disponible = Base − Reservado. Corre de noche, fuera del horario de operación.

Precisión de la implementación (F1a-f). La suma del libro que se compara con Reservado es Σ(Reserva + AjusteReserva) − Σ(Liberacion + Consumo). Las líneas Correccion no suman: documentan el ajuste hecho para volver a ese valor. Si sumaran, una corrección nunca podría cuadrar con su propio libro (RC-031 se lee con esta salvedad).

8.8 Presupuesto de carga sobre DocumentDB¶

Producción es una sola instancia t4g.medium ya cargada y no crece por ahora. El recálculo periódico debe ser liviano: toda consulta va por índice, con proyección mínima, maxTimeMS y sin $lookup. Si una consulta excede su tiempo, el reconciliador conserva el último valor, marca el dato como atrasado y alarma; nunca reintenta con un escaneo.

Reglas de carga:

• Solo tiendas de la lista blanca o con reservas vivas. Con 1 a 3 tiendas en el piloto el costo es despreciable; el número de tiendas activas es el que escala el costo.
• Recálculo incremental de liquidaciones (suma desde el corte) cada 5 minutos y recálculo completo por tienda una vez al día de noche. El completo detecta liquidaciones editadas o borradas después del corte y deja una línea Recalculo si corrige algo.
• Lotes y pausa: las tiendas se procesan en serie con una pausa corta entre una y otra, con tope de tiempo por ciclo.
• Datos atrasados: si Saldo.CalculadoEn supera 15 minutos o ExposicionExterna supera 60, se alarma. Una tienda en APLICAR cuyo saldo lleva más de 60 minutos sin recalcular pasa a rechazar con CUPO_NO_DISPONIBLE (no se confía en un saldo viejo).
• Índices antes de activar: se verifican con explain en preprod (Atlas) y se crean en prod (DocumentDB) en horario valle, desde el código con la convención ix_*/ux_*, ver Colecciones. Hoy no se confirmó cuáles existen (solo se sabe que no hay uno sobre PedidosInter.Idtienda).
• Alternativa si la carga molesta: reemplazar el cálculo de ExposicionExterna por un contador mantenido en el momento de crear la guía por los otros canales (RC-036). Queda para cuando esos canales se enganchen.

9. Reglas de cupo (RC)¶

"Aplica a" indica el alcance: API v1 rige en el piloto; Sistema son reglas para todos los canales que se aplicarán cuando Angular y las lambdas se enganchen.

10. Endpoints¶

Complementan Endpoints.

10.1 Integrador¶

// GET /v1/cupo
{
  "tiendas": [{
    "idTienda": 1234,
    "nombre": "Tienda Ejemplo",
    "modo": "PREPAGO",
    "estado": "ACTIVA",
    "disponible": 4000,
    "reservado": 96000,
    "saldoBase": 100000,
    "limiteCredito": 0,
    "otrasGuiasAbiertas": 0,
    "utilizacionPct": 96,
    "conteo": { "guiasHoy": 8, "limiteDia": 200 },
    "actualizadoEn": "2026-10-22T17:45:00Z"
  }]
}

// POST /v1/guias → respuesta (fragmento)
"costos": {
  "flete": 9000,
  "seguro": 1500,
  "servicioContraPago": 0,
  "otros": 0,
  "totalEntrega": 10500,
  "totalDevolucion": 12000,
  "cupoReservado": 12000,
  "moneda": "COP"
}

movimientos muestra solo Reserva, AjusteReserva, Liberacion, Consumo, Suspension y Desbloqueo, con monto, desglose, numeroGuia, disponibleDespues y fecha. No expone Actor, el margen ni el detalle de ExposicionExterna (solo el agregado otrasGuiasAbiertas).

10.2 Administración y Finanzas¶

Autenticación con el pool interno de administradores; todo cambio queda en ApiAuditoria.

/admin/v1/clientes-api/{id}/cupos de Endpoints queda para los límites de conteo del cliente; los de dinero viven en /admin/v1/cupos.

10.3 Errores¶

11. Ejemplos numéricos¶

Tienda de ejemplo en PREPAGO, saldo 100 000, guía de las de §7.4: reserva estimada 14 250, exacta 12 000, liquidación de entrega 10 500, de devolución 12 000.

El margen tiene un costo: con Disponible 12 500 una guía que realmente cuesta 12 000 se rechaza porque la estimación pide 14 250. Para reducirlo, la estimación debería usar la cotización exacta de Inter antes de crear la guía; se calibra con los datos de OBSERVAR.

12. Casos de borde¶

13. Observabilidad y alarmas¶

Se integra con Observabilidad; los logs no incluyen datos personales.

14. Plan de despliegue del piloto¶

15. Trabajo derivado¶

Dentro del alcance del cupo¶

• Normalizar IdTienda (entero/string) en el cálculo de SaldoConfiable.
• Índices de §8.8 (ix_PedidosInter_Idtienda_Estado, LiquidacionesLogigho por Idtienda y por "Numero Guia", retiros y novedades por IdTienda) antes de activar el reconciliador. Si ya existen, se confirma con explain.
• Reemplazar WalletLogigho.ValidaSaldoTienda (por nombre, sin uso) por una validación por id contra Disponible en retiros.
• Pruebas doradas de la calculadora.

Se registran aparte (no son del cupo)¶

Documentos que hay que alinear al aprobar este¶

• Colecciones: índice del ledger y de ApiContadoresUso.
• Endpoints: agregar GET /v1/cupo/movimientos, GET /v1/guias/{numero}/costos, rutas /admin/v1/cupos y los errores de §10.3.
• API pública de guías: este documento ya figura como "en construcción".

16. Decisiones tomadas¶

Pendiente con gerencia¶

1. Recaudo COD no pagado. Ejemplo: el lunes LogiGho acredita 40 000 de recaudo a la tienda, pero el carrier le paga a LogiGho 15 días después. Si la tienda usa esos 40 000 para crear guías y el carrier nunca paga, la pérdida es de LogiGho. Hoy se asume ese riesgo (RC-004). ¿Se confirma, y hasta qué monto total?
2. Tope de crédito. Máximo por tienda y máximo global entre todas las tiendas con CREDITO (por ejemplo, "la suma de los créditos no puede pasar de $N millones").
3. Negativos al abrir a más clientes. Hoy una tienda con saldo negativo no crea por la API. Si hay una tienda en −30 000, ¿se le da un plazo de gracia o se mantiene el bloqueo hasta que recargue?
4. Extender el cupo a Angular y a las lambdas. Criterio y fecha para que esos canales también reserven (RC-036).
5. Retiros. Confirmar el cambio en desembolso para que un retiro no supere el Disponible (RC-029) y cuándo hacerlo.

Pendiente técnico antes de empezar¶

• Confirmar en ConfiguracionLiquidacionTransportadora qué carriers están en cada motor.
• Confirmar si ApiLambdaProcesoAutomaticoInter completa siempre Trayecto; si no, la liquidación real puede usar la columna de flete Nacional/Metropolitano.
• Confirmar el tipo real de IdTienda/Idtienda en LiquidacionesLogigho, TransaccionesWalletLogigho y NovedadesLogigho consultando Mongo.
• Valores iniciales de GuiasPorDiaTienda, TopeLote y MargenEstimacionPct (aquí 200, 50 y 25 %; propuestos, a calibrar en OBSERVAR).
• Confirmar la regla de recaudo 0: "no se debería cobrar el servicio de contrapago a las transportadoras" se interpreta como servicioContraPago = 0 para la tienda.

Documentos relacionados¶

• API pública de creación de guías · Endpoints · Colecciones · Observabilidad
• ADR-003 Idempotencia (máquina de estados con RESERVADA)
• ApiLambdaLiquidacionesLogighoAOT · Motor legacy · Motor dinámico