@motor-tributario/pos-terminal

Complemento opcional del Motor Tributario para hablar con un terminal físico Transbank "POS Integrado" — Verifone VX520, Ingenico Desk 3500, etc. Paquete separado del SDK core (@motor-tributario/sdk) a propósito: el Motor emite documentos tributarios; esto mueve dinero por un terminal de pago físico. Son dos negocios distintos, y no todo integrador del Motor necesita el segundo — quien sólo emite DTE nunca se trae de arrastre dependencias de hardware de pago que no va a usar.

⚠️ Estado real

Ninguna de las 3 opciones de este paquete fue probada contra hardware real. No hay un terminal Verifone/Ingenico conectado en ningún entorno donde se desarrolló esto. El código sigue al pie de la letra las APIs públicas y oficiales de Transbank (verificadas contra los paquetes npm reales, sus .d.ts, y por reflexión contra las instancias reales de sus clases) — pero la primera vez que esto corra contra un terminal de verdad hay que probarlo con cuidado antes de confiar ciegamente en el mapeo de campos.

3 formas de conectar, 3 subrutas de este paquete

| Subruta | Dónde corre | Depende de | Requiere | |---|---|---|---| | @motor-tributario/pos-terminal | cualquiera | — | sólo tipos compartidos (RespuestaVentaPos, PosNoResponde, etc.) | | @motor-tributario/pos-terminal/node | Node.js (backend) | transbank-pos-sdk | puerto serial/USB del sistema operativo, driver del fabricante | | @motor-tributario/pos-terminal/web | navegador | transbank-pos-sdk-web | Agente Desktop de Transbank instalado y corriendo en el PC del punto de venta (websocket local, puerto 8090) | | @motor-tributario/pos-terminal/serial | navegador (Chrome/Edge) | — (Web Serial API nativa) | incompleta a propósito — ver más abajo |

transbank-pos-sdk/transbank-pos-sdk-web son peerDependencies opcionales: instalá sólo la que tu integración necesita.

npm install @motor-tributario/pos-terminal

# Backend con terminal conectado por serial/USB:
npm install transbank-pos-sdk

# Navegador con Agente Desktop de Transbank instalado en el punto de venta:
npm install transbank-pos-sdk-web

Node.js

import { venderConPosNode, anularEnPosNode } from "@motor-tributario/pos-terminal/node";
import { PosNoResponde } from "@motor-tributario/pos-terminal";

try {
  const resultado = await venderConPosNode(1500, "ticket-123");
  // resultado.responseCode === 0 → aprobado
} catch (err) {
  if (err instanceof PosNoResponde) {
    // el terminal no respondió — activar contingencia tributaria (Res. Ex. N°60/2020)
  }
}

Web (navegador + Agente Desktop)

import { venderConPosWeb, anularEnPosWeb } from "@motor-tributario/pos-terminal/web";

Misma firma que la opción Node — el terminal imprime su propio comprobante con su impresora integrada; esta opción nunca intenta abrir un diálogo de impresión del navegador.

Web Serial (navegador puro, sin instalar nada)

import { conectarPuertoSerial, venderConPosSerial } from "@motor-tributario/pos-terminal/serial";

conectarPuertoSerial() sí funciona — es Web Serial API genérica (elegir puerto, abrir, cerrar). venderConPosSerial()/anularEnPosSerial() lanzan un error explícito: el protocolo serial nativo de Transbank (framing, checksum LRC, códigos de comando) no está publicado en la documentación pública que se pudo revisar para construir este paquete — sólo se confirmó que existe una "Referencia" con el detalle, sin reproducirlo acá. Inventar esos bytes a ciegas contra un terminal real sería peor que no tener nada. Para "navegador puro sin instalar nada" que sí funciona hoy, la alternativa real es la herramienta que el propio Transbank construyó para esto: pos-serial.transbankdevelopers.cl.

Licencia y uso comercial

Este paquete usa transbank-pos-sdk/transbank-pos-sdk-web (BSD-3-Clause, oficiales de Transbank) — la licencia permite uso comercial, pero usar el SDK no es lo mismo que estar habilitado como comercio/integrador ante Transbank: para que un terminal cobre transacciones reales hace falta el proceso de afiliación/certificación propio de Transbank, independiente de este paquete.