Developer Hub
Bienvenido a la documentación técnica de Kargonode v2.0. Descubre cómo nuestra infraestructura Multi-Tenant B2B extrae, consolida y empuja datos financieros y logísticos hacia tu ERP en tiempo real.
Arquitectura del Sistema V2
Kargonode opera bajo un modelo Embarque-céntrico. No somos un OCR tradicional, somos un motor de procesamiento orquestado mediante flujos asíncronos y Edge Functions que garantizan el aislamiento de datos (Row-Level Security).
| Capa | Tecnología / Protocolo | Función |
|---|---|---|
| Client SPA | React + TypeScript + Tailwind | Interfaz Zero-Trust y Tablero Kanban en tiempo real. |
| API Proxy | Edge Functions (JWT Auth) | Enrutamiento seguro y validación de credenciales (Serverless). |
| Orquestación | n8n + Modelos Multimodales | Extracción semántica OCR y normalización MDM (Memoria de Alias). |
| Persistencia | PostgreSQL (Multi-Tenant RLS) | Motor relacional, Landed Cost y cadena de auditoría inmutable. |
Conexión y Webhooks
La ingesta y exportación de datos en Kargonode se maneja de forma asíncrona mediante Edge Functions. Una vez que el documento es extraído y vinculado automáticamente mediante nuestra Normalización MDM, disparamos un POST a tu endpoint.
x-kargonode-auth. Las URLs de los archivos adjuntos son Firmadas (Signed URLs) con un TTL estricto.
Estructura del Payload (JSON)
El objeto JSON unifica la cabecera del documento y los ítems de inventario, incorporando el motor de costeo V2 (Prorrateo y Matriz de Beneficios Aduaneros).
{
"embarque_id": "DO-2026-001",
"documento": {
"tipo_documento": "Factura Internacional",
"no_documento": "INV-2026-884",
"emisor": "Shenzhen Solartech Co.",
"moneda": "USD",
"trm_aduana": 4000.00, // Override TRM DIAN
"totales": {
"total_factura": 14500.50,
"costo_flete": 1400.00,
"incoterm": "FOB"
}
},
"base_inventario": [
{
"sku": "PANEL-500W",
"hs_code": "8541430000",
"beneficio_aduanero": "LEY_1715", // Matriz aduanera (0% IVA)
"cantidad": 100,
"precio_unitario": 145.00,
"costo_nacionalizado_unitario_cop": 615000.00 // Landed Cost congelado
}
]
}Compliance: Dossier DIAN y Firmas
Kargonode es una plataforma de grado regulatorio. Nuestro sistema de exportación empaqueta todos los soportes legales del embarque en un único archivo ZIP, renombrando los archivos según la nomenclatura normativa (ej: 01_Declaracion_Importacion).
Firma Criptográfica (Sello HMAC)
Para evitar manipulaciones, la Edge Function sign-dossier genera un manifest.json con el hash de cada archivo. Todo el paquete es sellado con una firma HMAC-SHA256 que crea una cadena de custodia legalmente irrefutable ante la DIAN.
Seguridad Enterprise y Retención
La plataforma ha sido diseñada bajo un enfoque estricto de Defensa en Profundidad (Defense-in-Depth), garantizando el aislamiento total entre inquilinos (Tenants).
- AUDIT TRAIL Inmutabilidad: Los cambios manuales se registran en una cadena hash SHA-256 (blockchain-like) protegida por triggers en BD.
- STORAGE Acceso Privado: Los documentos residen en buckets cerrados y solo son accesibles mediante URLs firmadas con TTL.
- AES-256-GCM Disaster Recovery (DRP): Backups lógicos cifrados automatizados hacia AWS S3 con rotación de llaves.