tzzr/system-docs

Fork 0

Files

admin e24de4102c Add HST Contract (CCT) standard documentation

2026-01-01 18:55:29 +00:00

18 KiB

Raw Blame History

Estandar HST Contract (CCT)

Version: 1.0
Estado: Especificacion
Fecha: 2026-01-01

Vision General

El estandar HST Contract (CCT) es un modelo de datos semantico para la gestion integral de contratos. Sigue la arquitectura de 6 capas (L1-L6) compatible con el estandar INV, proporcionando un marco completo para la gestion del ciclo de vida contractual.

Caracteristicas Principales

~280 campos totales distribuidos en 6 capas
18 tipos de contrato para cubrir escenarios empresariales
22 roles de partes para identificar participantes
14 estados de ciclo de vida para trazabilidad completa
37 tipos de clausulas estandarizadas
Compatibilidad eIDAS para firmas electronicas europeas
Soporte Smart Contracts para blockchain
Auditoria completa con hash inmutables

Arquitectura de 6 Capas (L1-L6)

L1 - Identificacion Base

Campo	Tipo	Descripcion
h_contract	VARCHAR(64)	Hash SHA-256 unico del contrato
contract_id	UUID	Identificador interno
external_ref	VARCHAR(100)	Referencia externa del cliente
contract_number	VARCHAR(50)	Numero de contrato
version	INTEGER	Version del contrato
parent_contract	UUID	Contrato padre (para enmiendas)
created_at	TIMESTAMPTZ	Fecha de creacion
created_by	UUID	Usuario creador

L2 - Clasificacion

Campo	Tipo	Descripcion
contract_type	ENUM	Tipo de contrato (ver catalogo)
contract_subtype	VARCHAR(50)	Subtipo especifico
category	VARCHAR(50)	Categoria de negocio
department	VARCHAR(100)	Departamento responsable
cost_center	VARCHAR(50)	Centro de coste
business_unit	VARCHAR(100)	Unidad de negocio
project_code	VARCHAR(50)	Codigo de proyecto asociado
h_maestro_tags	JSONB	Tags HST asociados

L3 - Partes y Roles

Campo	Tipo	Descripcion
parties	JSONB	Array de partes involucradas
party_id	UUID	Identificador de la parte
party_role	ENUM	Rol de la parte (ver catalogo)
party_type	ENUM	Tipo: person, company, government
legal_name	VARCHAR(255)	Nombre legal completo
tax_id	VARCHAR(50)	NIF/CIF/VAT
address	JSONB	Direccion estructurada
contact_person	VARCHAR(255)	Persona de contacto
contact_email	VARCHAR(255)	Email de contacto
signatory	BOOLEAN	Es firmante autorizado
signatory_power	TEXT	Poder de representacion

L4 - Terminos Contractuales

Campo	Tipo	Descripcion
effective_date	DATE	Fecha de inicio de vigencia
expiration_date	DATE	Fecha de finalizacion
duration_months	INTEGER	Duracion en meses
auto_renewal	BOOLEAN	Renovacion automatica
renewal_period	INTERVAL	Periodo de renovacion
notice_period_days	INTEGER	Dias de preaviso
termination_terms	TEXT	Condiciones de terminacion
governing_law	VARCHAR(100)	Ley aplicable
jurisdiction	VARCHAR(100)	Jurisdiccion
dispute_resolution	ENUM	Metodo de resolucion
arbitration_rules	VARCHAR(100)	Reglas de arbitraje
language	VARCHAR(10)	Idioma del contrato
currency	VARCHAR(3)	Moneda principal

L5 - Condiciones Economicas

Campo	Tipo	Descripcion
total_value	NUMERIC(18,4)	Valor total del contrato
annual_value	NUMERIC(18,4)	Valor anualizado
payment_terms	JSONB	Terminos de pago
payment_schedule	JSONB	Calendario de pagos
penalty_clauses	JSONB	Clausulas de penalizacion
price_adjustment	JSONB	Mecanismos de ajuste de precio
tax_treatment	JSONB	Tratamiento fiscal
billing_address	JSONB	Direccion de facturacion
bank_details	JSONB	Datos bancarios (encriptados)
insurance_requirements	JSONB	Requisitos de seguro
performance_bond	JSONB	Garantias de cumplimiento

L6 - Metadatos y Auditoria

Campo	Tipo	Descripcion
status	ENUM	Estado del ciclo de vida
workflow_stage	VARCHAR(50)	Etapa del workflow
approval_chain	JSONB	Cadena de aprobacion
signatures	JSONB	Firmas (eIDAS compatible)
documents	JSONB	Documentos adjuntos
amendments	JSONB	Historial de enmiendas
notes	JSONB	Notas internas
tags	JSONB	Etiquetas adicionales
metadata	JSONB	Metadatos extensibles
blockchain_ref	VARCHAR(100)	Referencia blockchain
smart_contract_address	VARCHAR(100)	Direccion smart contract
audit_log	JSONB	Log de auditoria
h_entrada	VARCHAR(64)	Hash de entrada
h_instancia	VARCHAR(64)	Hash de instancia
last_modified_at	TIMESTAMPTZ	Ultima modificacion
last_modified_by	UUID	Usuario que modifico

Catalogo de Tipos de Contrato (18)

Codigo	Nombre	Descripcion
COM	Commercial	Contrato de compraventa comercial
SVC	Service	Prestacion de servicios
EMP	Employment	Contrato laboral
LIC	License	Licencia de software/IP
NDA	Non-Disclosure	Acuerdo de confidencialidad
JVA	Joint Venture	Empresa conjunta
LEA	Lease	Arrendamiento/alquiler
LOA	Loan	Prestamo
INS	Insurance	Seguro
CON	Consulting	Consultoria
AGY	Agency	Agencia/representacion
FRA	Franchise	Franquicia
SLA	Service Level	Acuerdo de nivel de servicio
MNT	Maintenance	Mantenimiento
SUB	Subscription	Suscripcion
PAR	Partnership	Sociedad/colaboracion
SET	Settlement	Acuerdo transaccional
AMD	Amendment	Enmienda/modificacion

Catalogo de Roles de Partes (22)

Codigo	Rol	Descripcion
BUYER	Comprador	Parte que adquiere
SELLER	Vendedor	Parte que provee
LICENSOR	Licenciante	Otorga la licencia
LICENSEE	Licenciatario	Recibe la licencia
LESSOR	Arrendador	Propietario del bien
LESSEE	Arrendatario	Usuario del bien
EMPLOYER	Empleador	Contratante laboral
EMPLOYEE	Empleado	Trabajador
LENDER	Prestamista	Otorga el prestamo
BORROWER	Prestatario	Recibe el prestamo
INSURER	Asegurador	Compania de seguros
INSURED	Asegurado	Beneficiario del seguro
FRANCHISOR	Franquiciador	Dueno de la marca
FRANCHISEE	Franquiciado	Operador local
PRINCIPAL	Principal	Representado
AGENT	Agente	Representante
GUARANTOR	Garante	Proporciona garantia
BENEFICIARY	Beneficiario	Recibe el beneficio
CONSULTANT	Consultor	Proveedor de asesoria
CLIENT	Cliente	Receptor de asesoria
PARTNER	Socio	Miembro de sociedad
WITNESS	Testigo	Testigo de la firma

Estados del Ciclo de Vida (14)

Codigo	Estado	Descripcion	Transiciones Validas
DRAFT	Borrador	En redaccion	REVIEW, CANCELLED
REVIEW	En Revision	Pendiente de revision	DRAFT, NEGOTIATION, CANCELLED
NEGOTIATION	Negociacion	En proceso de negociacion	REVIEW, PENDING_APPROVAL, CANCELLED
PENDING_APPROVAL	Pendiente Aprobacion	Esperando aprobacion	NEGOTIATION, APPROVED, REJECTED
APPROVED	Aprobado	Aprobado internamente	PENDING_SIGNATURE
REJECTED	Rechazado	Rechazado (final)	DRAFT
PENDING_SIGNATURE	Pendiente Firma	Esperando firmas	APPROVED, SIGNED, CANCELLED
SIGNED	Firmado	Todas las firmas completadas	ACTIVE
ACTIVE	Activo	En vigor	SUSPENDED, TERMINATED, EXPIRED, RENEWED
SUSPENDED	Suspendido	Temporalmente inactivo	ACTIVE, TERMINATED
TERMINATED	Terminado	Terminacion anticipada	-
EXPIRED	Expirado	Vencido naturalmente	RENEWED
RENEWED	Renovado	Renovado (nuevo periodo)	ACTIVE
CANCELLED	Cancelado	Cancelado antes de firma	-

Catalogo de Clausulas (37)

Clausulas Generales

Codigo	Clausula	Descripcion
DEF	Definiciones	Terminos y definiciones
OBJ	Objeto	Proposito del contrato
SCO	Alcance	Ambito de aplicacion
DUR	Duracion	Vigencia temporal
PRI	Precio	Condiciones economicas
PAY	Pago	Terminos de pago
DEL	Entrega	Condiciones de entrega
WAR	Garantia	Garantias ofrecidas

Clausulas de Responsabilidad

Codigo	Clausula	Descripcion
LIM	Limitacion Responsabilidad	Limites de responsabilidad
IND	Indemnizacion	Obligaciones de indemnizar
INS	Seguro	Requisitos de seguro
FOR	Fuerza Mayor	Eventos extraordinarios

Clausulas de Propiedad Intelectual

Codigo	Clausula	Descripcion
IPR	Propiedad Intelectual	Derechos de PI
LIC	Licencia	Terminos de licencia
CON	Confidencialidad	Obligaciones de secreto
NDA	No Divulgacion	Restricciones de divulgacion
NCA	No Competencia	Restricciones de competencia

Clausulas de Terminacion

Codigo	Clausula	Descripcion
TER	Terminacion	Causas de terminacion
NOT	Notificacion	Requisitos de preaviso
PEN	Penalizacion	Penalizaciones por incumplimiento
TRA	Transicion	Obligaciones de transicion

Clausulas de Cumplimiento

Codigo	Clausula	Descripcion
COM	Cumplimiento	Obligaciones de compliance
AUD	Auditoria	Derechos de auditoria
REP	Reportes	Obligaciones de informar
REC	Registros	Mantenimiento de registros

Clausulas de Datos

Codigo	Clausula	Descripcion
DPA	Procesamiento Datos	Acuerdo de procesamiento
GDP	RGPD	Cumplimiento RGPD
SEC	Seguridad	Medidas de seguridad
BRE	Brecha	Notificacion de brechas
RET	Retencion	Periodo de retencion
DEL	Eliminacion	Destruccion de datos

Clausulas de Resolucion

Codigo	Clausula	Descripcion
GOV	Ley Aplicable	Jurisdiccion legal
JUR	Jurisdiccion	Tribunales competentes
ARB	Arbitraje	Clausula arbitral
MED	Mediacion	Procedimiento de mediacion

Clausulas Especiales

Codigo	Clausula	Descripcion
ASS	Cesion	Transferencia de derechos
SUB	Subcontratacion	Autorizacion de subcontratistas
ENT	Integracion	Acuerdo completo
MOD	Modificacion	Procedimiento de enmienda
WAI	Renuncia	No renuncia de derechos

Compatibilidad eIDAS

El estandar CCT es compatible con el Reglamento eIDAS (910/2014) para firmas electronicas.

Niveles de Firma Soportados

Nivel	Tipo	Valor Legal
SES	Simple Electronic Signature	Basico
AES	Advanced Electronic Signature	Presuncion de validez
QES	Qualified Electronic Signature	Equivalente a firma manuscrita

Estructura de Firma eIDAS

{
  "signature_id": "uuid",
  "signer_id": "uuid",
  "signature_level": "QES",
  "timestamp": "2026-01-01T12:00:00Z",
  "certificate": {
    "issuer": "Qualified Trust Service Provider",
    "serial": "...",
    "validity": {...}
  },
  "signature_value": "base64...",
  "document_hash": "sha256:...",
  "seal": {
    "timestamp_authority": "...",
    "timestamp_token": "..."
  }
}

Proveedores QES Soportados

Espana: FNMT, Camerfirma, AC Firmaprofesional
Alemania: D-Trust, Bundesdruckerei
Francia: Certinomis, ChamberSign
Italia: Aruba PEC, InfoCert

Integracion Blockchain / Smart Contracts

Casos de Uso

Caso	Descripcion	Beneficio
Notarizacion	Hash del contrato en blockchain	Prueba de existencia
Pagos automaticos	Smart contract para milestones	Automatizacion
Escrow	Fondos en custodia automatica	Seguridad
Vesting	Liberacion programada de activos	Transparencia
Multi-firma	Aprobacion descentralizada	Gobernanza

Estructura Smart Contract

{
  "blockchain_network": "ethereum|polygon|arbitrum",
  "contract_address": "0x...",
  "deployment_tx": "0x...",
  "abi_hash": "sha256:...",
  "state_hash": "sha256:...",
  "last_update_block": 12345678,
  "oracle_sources": [],
  "events": []
}

Redes Soportadas

Red	Tipo	Uso Recomendado
Ethereum	Mainnet	Contratos de alto valor
Polygon	L2	Operaciones frecuentes
Arbitrum	L2	DeFi integrado
Hyperledger	Permissioned	Enterprise privado

Hashes e Inmutabilidad

Cadena de Hashes

h_contract = SHA-256(contract_core_data)
    |
    +-- h_entrada = SHA-256(modification_data)
    |       |
    |       +-- h_instancia = SHA-256(snapshot_data)
    |
    +-- h_bloque = SHA-256(consolidated_block)

Formula de Hash

h_contract = sha256(
    contract_type + "|" +
    parties_hash + "|" +
    effective_date + "|" +
    total_value + "|" +
    created_at
)

Verificacion de Integridad

SELECT 
  contract_id,
  h_contract,
  sha256(
    contract_type || \x27|\x27 ||
    parties_hash || \x27|\x27 ||
    effective_date || \x27|\x27 ||
    total_value || \x27|\x27 ||
    created_at
  ) as computed_hash,
  CASE 
    WHEN h_contract = computed_hash THEN \x27VALID\x27
    ELSE \x27TAMPERED\x27
  END as integrity_status
FROM contracts;

Relaciones con Otras Entidades

Diagrama de Relaciones

CONTRACT (CCT)
    |
    +---> HST (h_maestro tags)
    |       - Etiquetas semanticas del contrato
    |       - Clasificacion automatica
    |
    +---> PLY (Players/Partes)
    |       - Identificacion de partes
    |       - Roles y capacidades
    |
    +---> LOC (Locations)
    |       - Lugar de ejecucion
    |       - Direcciones de las partes
    |
    +---> FLG (Flags/Normativas)
    |       - Ley aplicable
    |       - Jurisdiccion
    |       - Compliance requerido
    |
    +---> DOC (Documentos)
    |       - Anexos
    |       - Versiones
    |
    +---> WFL (Workflows)
            - Proceso de aprobacion
            - Notificaciones

Integracion con Feldman

Los contratos CCT se consolidan en Feldman como parte del registro consolidado:

{
  "entity_type": "CONTRACT",
  "entity_id": "h_contract",
  "consolidated_data": {...},
  "validation_status": "VERIFIED",
  "blockchain_proof": "0x..."
}

Ejemplos de Uso

Ejemplo 1: Contrato de Servicios (SVC)

{
  "h_contract": "sha256:a1b2c3...",
  "contract_type": "SVC",
  "parties": [
    {
      "party_role": "CLIENT",
      "legal_name": "Empresa ABC S.L.",
      "tax_id": "B12345678"
    },
    {
      "party_role": "SELLER",
      "legal_name": "Consultora XYZ S.A.",
      "tax_id": "A87654321"
    }
  ],
  "effective_date": "2026-01-15",
  "expiration_date": "2027-01-14",
  "total_value": 120000.00,
  "currency": "EUR",
  "status": "ACTIVE",
  "clauses": ["DEF", "OBJ", "SCO", "PRI", "PAY", "CON", "TER", "GOV"]
}

Ejemplo 2: NDA (NDA)

{
  "h_contract": "sha256:d4e5f6...",
  "contract_type": "NDA",
  "parties": [
    {
      "party_role": "PRINCIPAL",
      "legal_name": "Tech Corp"
    },
    {
      "party_role": "AGENT",
      "legal_name": "Partner Inc"
    }
  ],
  "effective_date": "2026-01-01",
  "duration_months": 24,
  "clauses": ["DEF", "OBJ", "CON", "NDA", "TER", "PEN", "GOV", "ARB"]
}

Validaciones y Reglas de Negocio

Validaciones Obligatorias

Regla	Descripcion
V001	contract_type debe ser uno de los 18 valores validos
V002	Al menos 2 partes deben estar definidas
V003	effective_date no puede ser futuro si status = ACTIVE
V004	expiration_date > effective_date
V005	total_value >= 0
V006	Todas las firmas requeridas antes de SIGNED
V007	governing_law obligatorio para contratos internacionales

Reglas de Transicion de Estado

DRAFT -> [REVIEW, CANCELLED]
REVIEW -> [DRAFT, NEGOTIATION, CANCELLED]
NEGOTIATION -> [REVIEW, PENDING_APPROVAL, CANCELLED]
PENDING_APPROVAL -> [NEGOTIATION, APPROVED, REJECTED]
APPROVED -> [PENDING_SIGNATURE]
REJECTED -> [DRAFT]
PENDING_SIGNATURE -> [APPROVED, SIGNED, CANCELLED]
SIGNED -> [ACTIVE]
ACTIVE -> [SUSPENDED, TERMINATED, EXPIRED, RENEWED]
SUSPENDED -> [ACTIVE, TERMINATED]
EXPIRED -> [RENEWED]
RENEWED -> [ACTIVE]

APIs Recomendadas

Endpoints REST

Metodo	Endpoint	Descripcion
POST	/contracts	Crear contrato
GET	/contracts/{id}	Obtener contrato
PUT	/contracts/{id}	Actualizar contrato
DELETE	/contracts/{id}	Eliminar borrador
POST	/contracts/{id}/sign	Firmar contrato
POST	/contracts/{id}/approve	Aprobar contrato
GET	/contracts/{id}/history	Historial de cambios
POST	/contracts/{id}/verify	Verificar integridad

Webhooks

Evento	Descripcion
contract.created	Nuevo contrato creado
contract.updated	Contrato modificado
contract.signed	Firma completada
contract.activated	Contrato en vigor
contract.expiring	Proximo a vencer (30 dias)
contract.expired	Contrato vencido
contract.terminated	Contrato terminado

Referencias

Entidades Base - Definicion de HST, ITM, PLY, LOC, FLG
Hashes - Sistema de hashes del sistema
Flujos - Flujos de trabajo estandar
Reglamento eIDAS - Regulacion europea de firmas electronicas

Documento generado como parte del sistema TZZR - HST Contract Standard

18 KiB Raw Blame History