Impresión en terminal SmartPOS

08 septiembre 2026

La Print API te da control total sobre la impresora térmica integrada en las terminales Kushki ONE. Imprime cualquier contenido desde tu sistema de caja —antes, durante o después de una transacción, o sin relación con ninguna— sin instalar drivers, SDK ni configurar hardware de tu lado.

Requisitos

Cómo funciona

El ciclo de impresión tiene dos partes: un request síncrono que encola el trabajo y una notificación asíncrona que te informa cuando terminó.

1. Tu sistema de caja construye un arreglo commands con el diseño del ticket.
2. Envías el request de creación del trabajo. La terminal responde 202 Accepted de inmediato.
3. La impresión se ejecuta de forma asíncrona en el hardware.
4. Conoces el resultado final por webhook o consultando el estado.

Los payloads y los headers son idénticos en todas las topologías. Las rutas no: el base URL termina en la terminal, y cada ruta lleva su propio prefijo.

Autenticación

La impresión usa el mismo mecanismo que las operaciones de pago — hash + cifrado, el único que tiene Kushki ONE:

El array commands que se muestra en esta página es el texto plano que se cifra, no lo que viaja por la red. El flujo completo está en Autenticación y cifrado de requests.

Casos de uso

La API no se limita a comprobantes de pago. Cualquier contenido que tu negocio necesite entregar en papel se dispara desde tu sistema de caja.

Anatomía de un ticket

Cada sección visual del recibo corresponde a un tipo de comando dentro del arreglo commands.

Estructura del request

Tipos de comandos

Ejemplo completo

Este request construye un recibo con logotipo, encabezado, ítems, total, código QR y corte automático.

{
  "printJobId": "TICKET-190209",
  "externalReference": "Mesa-14",
  "webhookUrl": "https://api.tunegocio.com/webhook/print-events",
  "skipIfBusy": false,
  "commands": [
    { "type": "image", "base64Image": "iVBORw0KGgoAAAANSUhEUg...", "align": "CENTER", "width": 300, "algorithm": "BINARIZATION" },
    { "type": "text", "text": "RESTAURANTE EL BUEN SABOR\n", "align": "CENTER", "size": 32, "bold": true },
    { "type": "text", "text": "NIT: 900.123.456-7\n", "align": "CENTER", "size": 22 },
    { "type": "divider", "dividerType": "DOTTED" },
    { "type": "columns", "columns": [
        { "text": "2x Combo Hamburguesa", "weight": 2, "align": "LEFT" },
        { "text": "30,000.00 COP", "weight": 1, "align": "RIGHT" } ] },
    { "type": "columns", "columns": [
        { "text": "1x Jugo Natural", "weight": 2, "align": "LEFT" },
        { "text": "8,000.00 COP", "weight": 1, "align": "RIGHT" } ] },
    { "type": "divider", "dividerType": "SOLID" },
    { "type": "columns", "columns": [
        { "text": "TOTAL", "weight": 2, "align": "LEFT" },
        { "text": "38,000.00 COP", "weight": 1, "align": "RIGHT" } ] },
    { "type": "qr", "content": "https://tunegocio.com/recibo/TICKET-190209", "dotSize": 6, "errorLevel": "M", "align": "CENTER" },
    { "type": "feed", "lines": 3 },
    { "type": "cut" }
  ]
}

Envía el request desde tu back-end:

const res = await fetch(`${BASE_URL}/print`, {
  method: "POST",
  headers: buildHeaders(payload),   // Authorization + timestamp
  body: JSON.stringify(payload),
});

const job = await res.json();
console.log(res.status, job.printJobId, job.status);
// 202  TICKET-190209  PENDING

import requests

res = requests.post(f"{BASE_URL}/print",
                    headers=build_headers(payload), json=payload)

job = res.json()
print(res.status_code, job["printJobId"], job["status"])
# 202  TICKET-190209  PENDING

La terminal responde de inmediato:

{
  "printJobId": "TICKET-190209",
  "status": "PENDING",
  "message": "Impresión encolada correctamente"
}

Resultado del trabajo

Tienes dos mecanismos para conocer el resultado final. Puedes usar uno o ambos en paralelo.

Opción A: webhook

Si enviaste webhookUrl al encolar, la terminal hace un POST hacia esa URL cuando el trabajo cambia a COMPLETED o FAILED.

Trabajo exitoso

{
  "printJobId": "TICKET-190209",
  "status": "COMPLETED",
  "externalReference": "Mesa-14"
}

Fallo de hardware

{
  "printJobId": "TICKET-190209",
  "status": "FAILED",
  "externalReference": "Mesa-14",
  "errorCode": "OUT_OF_PAPER",
  "errorMessage": "La impresora está sin papel."
}

Opción B: consulta el estado

Úsalo cuando tu sistema no puede recibir conexiones entrantes desde la terminal, o como respaldo del webhook.

Red Local

GET /terminal/v1/print_job?print_job_id=TICKET-190209

Nube

POST /terminal/v1/{terminalSerial}/sync/print_job

{
  "print_job_id": "TICKET-190209"
}

Consulta cada 2 o 3 segundos y detén el sondeo cuando status sea COMPLETED o FAILED.

{
  "printJobId": "TICKET-190209",
  "status": "COMPLETED"
}

Estados del trabajo

Códigos de error de hardware

Los valores posibles de errorCode son OUT_OF_PAPER, COVER_OPEN, COVER_INCOMPLETE, PAPER_JAM, PRINTER_HOT, MOTOR_HOT, CUTTER_ERROR, OFFLINE y UNKNOWN_ERROR. Llegan con type: TERMINAL-PRINTER en el cuerpo del error.

Una cola ocupada no es uno de ellos: llega como TER-004 con type: TERMINAL, y por HTTP como un 409.

Buenas prácticas

• Envía un printJobId propio para poder reimprimir el mismo ticket y para descartar duplicados en tu sistema.
• Usa externalReference para vincular el ticket con tu orden, mesa o factura.
• Responde 2xx al webhook antes de procesarlo. Un endpoint lento hace que pierdas la notificación.
• Trata FAILED como una condición operativa, no como un error de tu integración: muestra el errorMessage al operador para que resuelva el problema físico.
• Envía las imágenes ya binarizadas y del ancho correcto. Un logotipo pesado alarga el tiempo de impresión.