Documentación Técnica

Bienvenido al Developer Hub de Kargonode. Aquí detallamos cómo nuestra infraestructura extrae, estructura y empuja datos operativos hacia tu ERP o herramientas de automatización (n8n, Zapier) en tiempo real.

Arquitectura del Sistema

Kargonode no es un OCR tradicional. Utilizamos un Motor de Inferencia Multimodal (procesamiento visual y semántico simultáneo) orquestado mediante flujos asíncronos. Esto nos permite leer un PDF estructurado o una foto borrosa de WhatsApp con la misma efectividad.

Capa	Tecnología Principal	Función
Ingesta	Kargonode OS / Email Sync	Recepción segura de archivos (AES-256).
Orquestación	n8n Workflow Engine + Python	Gestión de colas y enrutamiento inteligente.
Cognición (IA)	Gemini 3.0 pro (Vision)	Extracción semántica y "Auto-Suma" financiera.
Persistencia	Supabase (PostgreSQL)	Almacenamiento temporal y relacional.

Configurar Webhooks

La forma más rápida de conectar Kargonode con tu ERP (SAP, Odoo, QuickBooks) es utilizando Webhooks. Cada vez que el sistema procesa un documento con éxito, envía una petición POST a la URL que hayas configurado en tu panel.

Tip de Integración: Te recomendamos usar n8n o Zapier como "Atrapadores" (Catch Hooks). Solo debes pegar la URL generada por estas herramientas en la configuración de tu cuenta Kargonode.

Estructura del Payload (JSON)

El objeto JSON que Kargonode empuja vía Webhook está normalizado para cualquier tipo de documento de comercio exterior. Siempre incluye un objeto documento (Cabecera) y un array items (Relacional).

response_payload.json

{
  "user_id": "usr_98a7sd6f5g4",
  "documento": {
    "fecha": "2024-03-15",
    "tipo_documento": "Factura Internacional",
    "no_documento": "INV-2024-889",
    "emisor": "Global Tech Shenzhen",
    "receptor": "Importadora Latam SAS",
    "moneda": "USD",
    "total_factura": 14500.50,
    "costo_flete": 1200.00,
    "incoterm": "FOB",
    "datos_extra": {
      "peso_bruto_kg": 450.5,
      "total_piezas": 120
    }
  },
  "items": [
    {
      "item_no": 1,
      "sku": "GT-MEM-16GB",
      "descripcion": "Modulo RAM DDR4 16GB",
      "cantidad": 100,
      "precio_unitario": 45.00,
      "sub_total": 4500.00,
      "nota_item": "Marks: Box 1-4 | NW: 15kg"
    }
  ]
}

Requisitos de Documentos

Aunque la IA multimodal es altamente tolerante a errores de formato, seguir estas prácticas garantiza una tasa de extracción de datos perfecta (100%):

Formatos Nativos: PDFs generados desde sistemas contables son procesados en ~5 segundos.
Imágenes y Escaneos: JPG, PNG o PDF escaneado. Se requiere una resolución mínima para garantizar la lectura correcta de decimales.
Archivos Masivos: Si subes un PDF de 50 páginas con 10 facturas diferentes, el sistema (Splitter Automático) tardará aproximadamente 1 minuto en separar y procesar cada registro.

Seguridad y Retención (Zero-Trust)

Sabemos que los documentos de comercio exterior contienen información sensible (precios, proveedores, aduanas). Nuestra política de infraestructura está diseñada para proteger tu operación:

Política Anti-Entrenamiento: Ningún documento, dato extraído o metadato procesado por Kargonode es utilizado para entrenar modelos de Inteligencia Artificial públicos o privados. Tu data te pertenece.

Los archivos originales subidos a la plataforma se almacenan en un bucket privado para su visualización en el Panel de Control. Si tu empresa requiere políticas de "Retención Cero" (Zero-Retention), podemos configurar tu cuenta para que el PDF se purgue de nuestros servidores inmediatamente después de realizar la extracción.