Contratos y fases

El contrato es el objeto central de Relvo. Relaciona un cliente con los cargos que se le facturarán, bajo qué condiciones y durante qué vigencia. Todo lo que se cobra tiene un contrato detrás.

Qué contiene un contrato

Elemento	Qué define
Cliente	A quién se le factura
Vigencia	Desde y hasta cuándo aplica el acuerdo
Moneda	En qué moneda se expresan los importes
Ancla de facturación	Desde qué fecha corren los períodos
Fases	Los términos vigentes en cada tramo de la vigencia
Cargos	Fijos, de uso, por asiento y únicos
Ajustes	Descuentos, mínimos y topes
Condición de pago	El plazo desde la emisión hasta el vencimiento
Referencias comerciales	OC, HES u otra evidencia requerida antes de emitir
Ruta de facturación	Cómo se agrupan los cargos en documentos y líneas
Política de FX	Cómo se determina el tipo de cambio

Estados

Ciclo de vida

1. DRAFT
2. UPCOMING
3. ACTIVE
4. PAUSED
5. COMPLETED

Estado	Significado
DRAFT	En preparación. No genera cobros
UPCOMING	Activado pero aún no vigente. Sólo aplica a contratos con fecha futura
ACTIVE	Vigente. Genera cobros en cada período
PAUSED	Vigente pero suspendido temporalmente
COMPLETED	Vigencia terminada
AMENDED	Reemplazado por una versión posterior. Se conserva como historia
CANCELLED	Terminado antes de su vigencia

Un contrato AMENDED no se borra ni se edita: queda como el registro de lo que estuvo acordado durante ese período. Es lo que permite explicar, meses después, por qué una factura vieja cobró lo que cobró.

Fases

Una fase es el tramo de vigencia durante el cual los términos no cambian. Un contrato de un solo precio tiene una fase; un ramp deal tiene varias.

Ejemplo

Ramp deal a tres fases

Fase	Vigencia	Plataforma	Precio por conversación
1	Ene–Abr 2026	USD 500	USD 0,12
2	May–Ago 2026	USD 1.000	USD 0,10
3	Sep–Dic 2026	USD 1.500	USD 0,08

Las tres fases están definidas desde el día uno. Relvo aplica la que corresponde a cada período sin que nadie tenga que acordarse de cambiar el precio en mayo.

Las fases de un contrato son contiguas por construcción: no hay huecos ni superposiciones en la línea de tiempo. Cada día de la vigencia pertenece exactamente a una fase.

Pausar y reanudar

Al pausar un contrato se decide qué pasa con el consumo del período pausado:

Comportamiento	Efecto
bill_through_pause	El período se factura igual, como si no hubiese pausa
hold_unbilled	El consumo queda retenido sin facturar

Y al reanudar, qué pasa con el ciclo:

Anclaje al reanudar	Efecto
unchanged	El ciclo mantiene su ancla original
resume_date	El ciclo se re-ancla a la fecha de reanudación

Son decisiones comerciales distintas y se declaran por separado: pausar el servicio no implica automáticamente correr las fechas de facturación.

Amendments

Un amendment —una enmienda al contrato— cambia las condiciones hacia adelante. Preserva el contrato anterior como historia y crea la versión vigente desde la fecha de efecto.

!

Un amendment no reescribe un período ya facturado

Si necesitas cambiar el monto de un período que ya se facturó, el amendment no es la herramienta: los períodos finalizados son inmutables. La diferencia se resuelve con una nota de crédito o débito, que deja un rastro fiscal explícito de la corrección.

Un amendment con fecha de efecto a mitad de período divide ese período: la porción anterior se cobra con las condiciones antiguas y la posterior con las nuevas. Ambas porciones terminan en la misma factura.

Ruta de facturación

Por defecto, todos los cargos de un contrato producen una factura. La ruta de facturación te permite declarar explícitamente otra cosa:

• Varias facturas desde un mismo contrato —por ejemplo, una por centro de costo del cliente— cada una identificada por su propia clave.
• Agrupar varios cargos en una sola línea de la factura, con el nombre que el cliente espera ver, en vez de exponer la estructura interna del contrato.

Los límites son 50 facturas por ruta, 200 líneas por factura y 50 cargos por línea. La regla que Relvo verifica es de cobertura: cada cargo de la fase se enruta exactamente una vez. No hay cargos huérfanos que se dejen de facturar en silencio, ni cargos duplicados en dos documentos.

Moneda y FX

El contrato declara su moneda. Cuando la moneda del contrato no es la moneda de emisión del documento, la política de FX determina el tipo de cambio:

Política	Efecto
not_required	No se necesita conversión
official_issue_date	Se usa el tipo de cambio oficial de la fecha de emisión

Cada tipo de cambio aplicado queda registrado con su fecha, de modo que reimprimir una factura antigua reproduce sus montos originales y no los de hoy.

API

Operación	Endpoint
Crear / listar	POST · GET /api/v1/public/contracts
Ver / actualizar	GET · PUT /api/v1/public/contracts/{contract_id}
Activar	POST /api/v1/public/contracts/{contract_id}/activate
Pausar	POST /api/v1/public/contracts/{contract_id}/pause
Cancelar	POST /api/v1/public/contracts/{contract_id}/cancel

Las transiciones de estado son endpoints con nombre propio, no un PATCH genérico de campo status. Cada transición valida sus propias reglas.

SiguienteDescuentos, mínimos y topesLos ajustes que un contrato puede aplicar sobre sus cargos.RelacionadoPeríodos y cadencia de cobroCómo se determinan los períodos de un contrato.RelacionadoOC, HES y aprobacionesLa evidencia comercial que un contrato puede exigir antes de emitir.RelacionadoDe contrato a pagoEl recorrido completo de un contrato real.