Integración Medsys Star ↔ TKS Suite

1. Arquitectura y Principios de Integración

La integración entre Medsys Star y TKS Suite está estructurada bajo un patrón de Ingesta Asíncrona Desacoplada y Staging Contable. Su propósito es actuar como receptor de alta fidelidad de las órdenes operativas emitidas por la agencia, garantizando custodia completa de datos y continuidad del flujo comercial.

Principios de Diseño de la Plataforma

• Preservación Fidedigna del Payload Crudo: Cada transmisión recibida se almacena de forma íntegra e inmutable en el registro de auditoría (raw_payload), salvaguardando la trazabilidad exacta de los datos emitidos por Medsys Star.
• Staging Asíncrono y Auditoría Preventiva: Discrepancias comerciales, RUCs en trámite de actualización, variaciones en el cálculo de subtotales o ausencia del archivo PDF adjunto no impiden el ingreso de la transacción. El sistema acepta la orden en staging (HTTP 201/200) y marca automáticamente la bandera needs_review: true junto con el detalle en review_reason para su revisión por el equipo contable.
• Separación del Momento de Facturación: La verificación formal de datos y la facturación definitiva se ejecutan de manera nativa dentro de TKS Suite al procesar la orden, no en la pasarela de ingesta.
• Contrato Estructural Mínimo: Para asegurar máxima disponibilidad, el contrato requiere únicamente un Bearer Token autorizado, una estructura JSON válida y el identificador order.order_number.
• Soporte Flexible de Estructura de Medios: La API acepta planes de medios multi-línea mediante la lista estándar items (recomendada para desglose detallado de pautas) así como estructuras de servicio único mediante item_detail, normalizando ambas de forma homogénea en la consola de pre-facturación.

1.2 Recepción de Importes e Impuestos (ITBMS)

TKS Suite opera como un receptor de órdenes y no interviene ni recalcula las liquidaciones realizadas por el sistema emisor (Medsys Star). Todos los importes se reciben y almacenan exactamente como vienen definidos en la orden:

• Recepción Directa de Valores: Medsys Star transmite los montos resultantes de su propia liquidación (gross_cost, agency_fee, itbms_pct, itbms_amount y total). La API no impone fórmulas de cálculo al emisor.
• Órdenes con y sin Impuesto: Los campos itbms_pct e itbms_amount son completamente opcionales. Si la orden no maneja impuesto (exenta o no gravada), se pueden enviar en 0 o simplemente omitirse del JSON.
• Ingesta Tolerante sin Rechazos: Si entre los subtotales, ítems o total transmitido existiera alguna diferencia aritmética por redondeo o configuración propia del emisor, la orden nunca es rechazada. Ingresa directamente a staging con applied: true, registrándose la transacción fielmente y señalando cualquier observación para que el equipo contable de la agencia la atienda internamente en TKS Suite.

1.3 Catálogo Exhaustivo de Motivos de Auditoría (review_reason)

Cuando una transacción ingresa a staging con needs_review: true, el sistema documenta la causa en review_reason mediante el siguiente catálogo estándar:

2. Autenticación, Seguridad y Ambientes

El acceso a los servicios de ingesta de TKS Suite se gestiona a través del estándar Bearer Token HTTP. Las credenciales emitidas son custodiadas bajo algoritmos criptográficos SHA-256 para asegurar máxima protección perimetral.

2.1 Gestión Transparente de Ambientes (Sandbox y Producción)

Tanto el ambiente de pruebas (Sandbox) como el entorno productivo oficial operan sobre la misma infraestructura homogénea en https://saas.tks.com.pa/functions/v1/external-orders. El enrutamiento de la transacción hacia el ambiente correspondiente se realiza de forma automática según la firma del token provisto:

• Token de Sandbox (prefijo tks_sandbox_...): Enruta la información al espacio de pruebas y homologación de la agencia, permitiendo validar flujos sin impacto contable ni tributario.
• Token de Producción (prefijo tks_live_...): Direcciona la información al entorno contable activo para su auditoría y posterior facturación.

2.2 Solicitud, Asignación y Rotación de Tokens

Los Bearer Tokens son emitidos y administrados de forma centralizada por TKS Technology:

• Token de Pruebas (Sandbox): Con prefijo tks_sandbox_<hash>. Opera sobre bases de datos de homologación; permite simular transmisiones completas y pruebas en Postman sin alterar la contabilidad real.
• Token de Producción: Con prefijo tks_live_<hash>. Enruta directamente hacia la compañía contable activa en TKS Suite y Sage 50.
• Rotación Zero-Downtime: Para renovar credenciales periódicamente o ante incidentes de seguridad, el equipo de TI de la agencia solicita la rotación formal a la mesa técnica ([email protected]). TKS Technology habilita un token secundario activo en paralelo durante una ventana de transición de 72 horas para que Medsys Star aplique la nueva credencial sin corte ni interrupción transaccional.

3. Idempotencia, Concurrencia y Capacidad de Transmisión

La pasarela de TKS Suite incorpora mecanismos para absorber tráfico masivo continuo, asegurar idempotencia ante retransmisiones de red y resolver condiciones de carrera con total determinismo:

3.1 Garantía de Idempotencia y Detección de Cambios

• Control con Cabecera Explícita: Los clientes pueden incluir la cabecera Idempotency-Key: <clave_cliente>. Retransmisiones subsiguientes con la misma clave devolverán la respuesta original registrada con status: "duplicate".
• Generación Criptográfica Automática: Cuando la cabecera es omitida, TKS Suite construye una clave compuesta incorporando order_number, budget.rev, event y el hash SHA-256 del contenido íntegro del payload (payloadHash).
• Determinación de Duplicado vs. Actualización:
  • Contenido Idéntico: Si arriba una petición con el mismo número de orden y revisión cuyo hash de contenido coincide con el activo, se reconoce como entrega redundante y retorna HTTP 200 OK con status: "duplicate".
  • Contenido Modificado: Si los datos comerciales o financieros presentan cambios bajo el mismo rev, TKS Suite actualiza el espejo en base de datos, resguarda la nueva versión en el histórico inmutable y retorna HTTP 200 OK con status: "updated".
• Preservación Histórica de Revisiones: Si arriba una versión con número de revisión (budget.rev) inferior al activo en base de datos, el sistema salvaguarda la información registrándola en la bitácora histórica con la bandera applied: false y señalando needs_review: true, respondiendo HTTP 200 OK con status: "archived_historical_revision".

3.2 Resolución Determinista de Concurrencia

En transmisiones concurrentes o ráfagas paralelas que compartan el mismo número de revisión, TKS Suite resuelve la precedencia evaluando el timestamp provisto en order.updated_at (o sent_at):

• Timestamp Entrante Superior: La transacción actualiza el registro operativo activo en staging (applied: true, status: "updated").
• Timestamp Entrante Inferior o Igual: La transacción se preserva como registro de auditoría en el histórico (applied: false, status: "archived_historical_revision") sin sobreescribir el estado vigente.

Este mecanismo previene que variaciones de latencia en la red ocasionen inconsistencias durante procesos de migración o sincronizaciones masivas.

3.3 Capacidad de Transmisión y Soporte de Ráfaga (Burst Capacity)

La API opera con una ventana deslizante de 60 segundos con límite de 120 peticiones por minuto por compañía, con capacidad de ráfaga completa (full burst). La arquitectura tolera hasta 120 llamadas simultáneas o en paralelo dentro del minuto sin encolamiento forzado.

Esto permite a Medsys Star transferir lotes de más de 100 órdenes continuas con fluidez. El estado HTTP 429 se activa únicamente si la sumatoria de peticiones dentro de la ventana de 60 segundos excede el límite asignado.

3.4 Orden de Entrega de Eventos (Event Ordering)

En redes distribuidas, variaciones imprevistas de latencia pueden ocasionar que un evento ORDER_UPDATED arribe antes que el ORDER_CREATED original:

• Ingesta Tolerante sin Fricción: Si TKS Suite recibe un evento ORDER_UPDATED con un order_number que no existe previamente en la base de datos, el sistema crea la orden automáticamente en staging contable con status: "created" y applied: true.
• Cero Bloqueos Transaccionales: No se requiere retransmisión forzada del evento inicial ni se produce error 404 o 409, garantizando fluidez operativa y tolerancia ante entregas asíncronas desordenadas.

3.5 Política de Reintentos y Backoff Exponencial

Ante respuestas transitorias de red o capacidad (códigos HTTP 429, 500 o 503), el cliente de Medsys Star debe aplicar una política de reintentos con Backoff Exponencial y Jitter aleatorio:

• Intervalos Recomendados: 1s, 2s, 4s, 8s (máximo 5 reintentos).
• Respeto a Retry-After: Si la pasarela responde HTTP 429 Too Many Requests, el cliente debe esperar estrictamente los segundos indicados en la cabecera Retry-After antes del siguiente envío.
• Garantía de Idempotencia: Gracias a la capa de idempotencia (por cabecera Idempotency-Key o hash criptográfico del payload), los reintentos automáticos son completamente seguros y no generarán duplicados ni inconsistencias en base de datos.

Estructura de Respuesta ante Límite de Tasa (HTTP 429 Too Many Requests):

{
  "error": "Límite de tasa excedido. Se permite un máximo de 120 peticiones por minuto.",
  "retry_after_seconds": 35
}

4. Especificación de Endpoints

4.1 Consulta de Estado y Bloqueo Fiscal de Orden

GET https://saas.tks.com.pa/functions/v1/external-orders?order_number={numero}

Permite a Medsys Star consultar en tiempo real el ciclo de vida de una orden, su estado contable y verificar si ya fue emitida en Factura Electrónica (locked: true).

Ejemplo de Respuesta HTTP 200 OK:

{
  "order_number": "50230",
  "billing_status": "pending",
  "locked": false,
  "invoice_number": null,
  "cufe": null,
  "invoiced_at": null,
  "credit_status": "none",
  "credited_amount": 0,
  "stored_rev": 0,
  "needs_review": false,
  "review_reason": null
}

4.2 Ingesta y Actualización de Órdenes

POST https://saas.tks.com.pa/functions/v1/external-orders

Transmite la orden con sus datos de agencia, cliente, ítems de medios, finanzas y archivo PDF de respaldo. El único campo mandatorio para la ingesta es order.order_number.

Ejemplo de Payload JSON (Orden de Medios con Múltiples Servicios):

{
  "event": "ORDER_CREATED",
  "sent_at": "2026-10-20T18:00:00Z",
  "agency": {
    "code": "OMD",
    "name": "OMD Centroamérica"
  },
  "budget": {
    "code": "BUD-2026-OMD-009",
    "rev": 0,
    "date": "2026-10-20",
    "campaign": "Campaña Navideña McCafé 2026",
    "brand": "McCafé",
    "period": {
      "start": "2026-11-01",
      "end": "2026-12-31"
    }
  },
  "client": {
    "code": "CLI-MCD-01",
    "name": "Arcos Dorados Panamá S.A.",
    "ruc": "155667788-2-2020",
    "dv": "45",
    "email": "facturas.panama@arcosdorados.com",
    "payment_terms_days": 30
  },
  "order": {
    "order_number": "50230",
    "status": "ACTIVA",
    "updated_at": "2026-10-20T18:00:00Z",
    "concept": "Compra",
    "media_type": "TELEVISION",
    "submedia_type": "SPOT PRIME TIME",
    "provider": {
      "code": "PROV-MEDCOM",
      "name": "Corporación Medcom Panamá S.A.",
      "ruc": "45678-1-123456",
      "dv": "08",
      "email": "facturacion@medcom.com.pa"
    },
    "items": [
      {
        "service_description": "15 Spots Telemetro Prime Time 30s",
        "purchase_format": "ROTATIVO",
        "version": "Navidad V1",
        "ad_units": 15,
        "unit_cost": 200.00,
        "gross_cost": 3000.00,
        "itbms_pct": 7.00
      },
      {
        "service_description": "10 Spots RPC TV Rotativo 30s",
        "purchase_format": "ROTATIVO",
        "version": "Navidad V1",
        "ad_units": 10,
        "unit_cost": 200.00,
        "gross_cost": 2000.00,
        "itbms_pct": 7.00
      }
    ],
    "financials": {
      "currency": "USD",
      "gross_cost": 5000.00,
      "agency_fee": 0.00,
      "itbms_pct": 7.00,
      "itbms_amount": 350.00,
      "total": 5350.00
    },
    "personnel": {
      "planner": "Carlos Medina",
      "buyer": "Valeria Rios",
      "account_director": "Marissa Solano"
    },
    "custom_fields": {
      "product_code": "MCCAFE-NOV-DIC",
      "cost_center": "CC-PAN-MKT-01",
      "contract_ref": "MEDCOM-2026-998"
    },
    "replaces_order_number": null,
    "pdf": {
      "filename": "OC-50230-McCafe-OMD.pdf",
      "content_base64": "JVBERi0xLjQKJUZpbGUgY29udGVudCBkZW1v..."
    }
  }
}

Catálogo de Estados de Respuesta POST:

Estructura de Respuesta Exitosa (HTTP 201 Created / 200 OK):

{
  "status": "created",
  "id": "f5c696bf-54df-4edb-9bb6-0062209e5ea5",
  "revision_id": "dd874da8-1d98-44d7-9533-0a3bdf39eafe",
  "order_number": "50230",
  "rev": 0,
  "locked": false,
  "needs_review": false,
  "review_reason": null,
  "change_class": "none",
  "changed_fields": [],
  "pdf_stored": true,
  "idempotency_key": "50230-0-ORDER_CREATED-a1b2c3d4",
  "environment": "production"
}

Estructura de Error 400 Bad Request:

Emitida exclusivamente ante un cuerpo JSON con sintaxis no parseable o ante la ausencia del identificador obligatorio order.order_number. El atributo field es null en errores generales de sintaxis:

{
  "error": "El campo order.order_number es obligatorio para identificar la orden",
  "field": "order.order_number"
}

5. Ciclo de Facturación, Ajustes Contables y Cancelaciones

• Inmutabilidad del Registro Facturado: Ningún mensaje externo posterior sobreescribe directamente los montos o datos de una orden ya facturada.
• Custodia Transaccional en Órdenes Facturadas: Toda actualización enviada sobre una orden facturada es aceptada (HTTP 200 OK con status: "revision_recorded_order_locked"), resguardada en el histórico con applied = false y notificada al área contable (needs_review: true) para su correspondiente ajuste o gestión mediante Nota de Crédito.

5.1 Capa de Ajustes Contables (accounting_overrides)

Durante la auditoría previa a la facturación, los especialistas contables pueden incorporar ajustes (tales como RUC homologado, centro de costos o razón social formal). TKS Suite administra estos parámetros en una capa desacoplada (accounting_overrides).

• Independencia del Espejo: La recepción de eventos ORDER_UPDATED sincroniza los datos operativos de medios sin alterar ni sobreescribir los ajustes manuales definidos por contabilidad.
• Prevalencia en la Facturación: Al formalizar la factura, el sistema toma con prioridad autoritativa los valores presentes en accounting_overrides, garantizando que el documento contable concuerde con los catálogos validados.

5.2 Protocolo de Sustitución de Órdenes (replaces_order_number)

Cuando una orden emitida en Medsys Star tiene por objeto sustituir formalmente a una orden anterior que ya completó su ciclo de facturación, se indica mediante order.replaces_order_number:

• Integridad del Historial: La factura original previamente emitida en el sistema no se elimina ni se revierte de forma automática, preservando el histórico contable.
• Gestión en TKS Suite: La orden original es etiquetada automáticamente con needs_review: true y la observación "Reemplazada por orden {nueva_orden}", requiriendo la gestión de la Nota de Crédito correspondiente en Sage / TKS Suite.
• La nueva orden ingresa a staging contable como transacción activa para su correspondiente proceso de facturación.

5.3 Ciclo de Vida del Evento de Cancelación (ORDER_CANCELLED)

Al transmitirse una anulación mediante el evento ORDER_CANCELLED:

• Órdenes en Staging Contable (billing_status != 'invoiced'): La orden transiciona a estado comercial status: "ANULADA" y estado de facturación billing_status: "cancelled", retornando HTTP 200 OK con status: "updated".
• Órdenes Facturadas (locked: true, billing_status == 'invoiced'): Al existir una factura formalmente emitida, la solicitud se resguarda en el histórico (applied: false), señalando needs_review: true con el motivo "Solicitud de anulación recibida posterior a facturación. Requiere Nota de Crédito" y respondiendo HTTP 200 OK con status: "revision_recorded_order_locked".

6. Catálogo de Respuestas HTTP