API de integración Nankú
Nankú Ventas corre en la máquina POS y delega el cobro con tarjeta en la aplicación de pago del operador instalada en la misma máquina (integración inter-app de Android). Esta documentación describe cómo Nankú se comunica con la app de pago, para operadores y desarrolladores que quieran certificar su integración.
Introducción
En una venta con Nankú el flujo es un solo movimiento: el cajero arma el carrito, presiona Cobrar, la app de pago del operador procesa la tarjeta y Nankú emite la boleta electrónica del SII. El cliente pasa la tarjeta una vez y sale un solo papel.
La comunicación entre Nankú y la app de pago ocurre dentro de la misma máquina, mediante un Intent de Android con un mensaje JSON. No requiere internet para el intercambio entre apps (el operador sí puede requerirla para autorizar la transacción).
Flujo de un cobro
Si el cobro falla o se cancela, Nankú jamás duplica la venta: el reintento reutiliza la misma venta, el mismo stock y el mismo registro financiero.
Máquinas y operadores soportados
| Operador | App de pago | Máquinas | Estado |
|---|---|---|---|
| Tuu (Haulmer) | com.haulmer.paymentapp | Tuu Pro 2 S (KOZEN) | Disponible |
| Transbank | — | Por definir | Próximamente |
| GETNET | — | Por definir | Próximamente |
| Mercado Pago | — | Por definir | Próximamente |
Además, está en desarrollo la estación Tuu P17 (caja tipo supermercado: monitor con el módulo de ventas, pistola lectora de código de barras e impresora térmica, donde la máquina P17 se usa solo para el pago con tarjeta). Si eres un operador de pago y quieres certificar tu app con Nankú, escríbenos.
Requisitos Disponible
- Máquina POS Android con la app de pago del operador instalada (hoy: Tuu Pagos).
- Nankú Ventas instalado en la misma máquina.
- La app de pago debe aceptar un Intent
ACTION_SENDcon tipotext/jsony responder poronActivityResult.
Solicitud de cobro
Nankú lanza la app de pago con ACTION_SEND, tipo text/json, y el JSON de la transacción en EXTRA_TEXT:
"amount": 12990, // monto en pesos chilenos, sin decimales
"tip": -1, // -1 = sin propina
"cashback": -1, // -1 = sin retiro de efectivo
"method": 0, // 0 = el cliente elige crédito o débito
"installmentsQuantity": -1, // -1 = sin cuotas
"printVoucherOnApp": false, // Nankú imprime solo la boleta (sin voucher doble)
"dteTpe": 0, // tipo de documento tributario
"extraData": {
"sourceName": "Nankú Ventas",
"sourceVersion": "1.0.0",
"externalReferenceId": "venta_8231" // trazabilidad: vuelve en la respuesta
}
}
Campos
| Campo | Tipo | Descripción |
|---|---|---|
amount | entero | Monto total en CLP, sin decimales. Obligatorio. |
tip | entero | Propina. -1 para omitir. |
cashback | entero | Retiro de efectivo. -1 para omitir. |
method | entero | 0: el cliente elige crédito o débito en la máquina. |
installmentsQuantity | entero | Número de cuotas. -1 = sin cuotas. |
printVoucherOnApp | booleano | false: la app de pago no imprime su voucher; Nankú imprime solo la boleta electrónica. |
dteTpe | entero | Tipo de documento tributario electrónico a emitir. |
extraData.externalReferenceId | texto | Identificador de la venta en Nankú. La app de pago debe devolverlo intacto en la respuesta. |
Validación estricta: la app de pago valida el modelo exacto del JSON. Un campo desconocido o de tipo incorrecto cancela el cobro de inmediato. No agregues campos que el modelo no declare.
Respuesta
La app de pago devuelve el resultado a Nankú por onActivityResult, en el extra transactionResult (algunas versiones usan resultJson — Nankú lee ambos).
"transactionStatus": true,
"sequenceNumber": "000123", // número de operación del cobro
"extraData": { "externalReferenceId": "venta_8231" }
}
"errorCode": "05",
"errorMessage": "Transacción rechazada"
}
Si el cajero cancela antes de procesar la tarjeta, la app puede devolver RESULT_CANCELED sin extra. Nankú lo trata como cancelación simple: la venta queda pendiente de cobro y puede reintentarse.
Errores y cancelaciones
- Rechazo del emisor (fondos insuficientes, tarjeta bloqueada): Nankú muestra el mensaje y ofrece reintentar u otro medio de pago.
- Cancelación del cajero: la venta vuelve al carrito, sin registrar cobro.
- Sin respuesta / app cerrada: Nankú marca el cobro como no confirmado y nunca emite boleta sin confirmación del pago.
- Reintentos: siempre reutilizan la misma venta — no se duplica stock, ni boleta, ni registro financiero.
Seguridad
- Verificación de firma: antes de lanzar el cobro, Nankú calcula el SHA-256 del certificado firmante de la app de pago instalada y lo compara contra la lista de firmas confiables del operador. Una app impostora con el mismo nombre de paquete es rechazada.
- Sin datos de tarjeta: Nankú nunca ve, procesa ni almacena datos de tarjetas. El cobro completo ocurre dentro de la app certificada del operador.
- Trazabilidad: cada cobro viaja con el
externalReferenceIdde la venta, lo que permite conciliar ventas Nankú contra la liquidación del operador.
API REST y webhooks Próximamente
Estamos trabajando en una API REST para que integradores y sistemas externos puedan consultar ventas, stock y recibir notificaciones en tiempo real:
GET /v1/ventas— listado de ventas con filtros por fecha y sucursalGET /v1/productos— catálogo y stock actualPOST /v1/webhooks— notificaciones de venta, stock bajo y cierre de caja
Exportación de inventario (ICH)
El inventario levantado con Nankú ICH ya se puede llevar a otros sistemas: exportación a Excel, envío por correo, o integración directa a un ERP externo vía API. Si desarrollas un ERP y quieres recibir el catálogo de un cliente directamente desde ICH, escríbenos para coordinar el acceso.
Si quieres acceso anticipado a la API REST, escríbenos y te avisamos cuando abra la beta.
Soporte para integradores
¿Eres un operador de pago o desarrollador y quieres integrar tu app o sistema con Nankú? Conversemos: te acompañamos en la certificación de punta a punta.