API

53 min

API utilizada por la aplicación de PC para operar con el dispositivo POS a través de SDConn.

Base URL: http://localhost:8484

Todas las respuestas son JSON con Content-Type: application/json.

Operaciones

POST /api/v1/read

Operación completa de lectura de tarjeta. Este es el endpoint principal que la aplicación de PC usa para procesar un pago.

Flujo estándar (sin intentToken):

Obtiene información del dispositivo (serial number, modelo, etc.)

Obtiene la ubicación GPS del dispositivo

Crea una operación en la API de Mobbex (/p/pos/operation)

Envía el token de lectura al dispositivo para que lea la tarjeta

Devuelve los datos de la tarjeta leída junto con el intentToken generado

Flujo con token externo (con intentToken):

Si se envía un intentToken en el cuerpo, se omite la llamada a la API de Mobbex y se usa ese token directamente para la lectura. En este caso la respuesta incluye además la geolocation del dispositivo.

Cuerpo:

{ "total": 15.00, "otherAmount": 0, "intent": "token_de_intento", "currency": "ARS", "hideAmount": false, "test": false, "intentToken": "", "source": "", "description": "", "reference": "", "async": false }

Campo	Tipo	Requerido	Descripción
total	number	Sí	Monto total como float (ej: 15.00)
otherAmount	number	No	Monto adicional (propina, etc.)
intent	string	No	Tipo de intento (por defecto: "payment.v2")
currency	string	No	Código de moneda (por defecto: "ARS")
hideAmount	boolean	No	Ocultar monto en la pantalla del dispositivo
test	boolean	No	Enviar operación en modo test a Mobbex
intentToken	string	No	Token externo. Si se envía, omite la llamada a la API de Mobbex
source	string	No	Fuente de pago (ej: "arg.qr"). Si se envía, activa el flujo QR en lugar de lectura de tarjeta
description	string	No	Descripción de la operación (se envía a la API de Mobbex)
reference	string	No	Referencia externa de la operación
async	boolean	No	Si es true, la lectura se ejecuta en segundo plano y se devuelve inmediatamente el intentToken. El resultado se consulta con GET /api/v1/read/:token

Respuesta exitosa — flujo tarjeta (estándar):

{ "result": true, "intentToken": "token_generado_por_mobbex", "sourceData": { "pin": "...", "emvData": "...", "cryptogram": "...", "ksn": "...", "track2": "..." } }

Respuesta exitosa — flujo tarjeta (con token externo):

{ "result": true, "intentToken": "token_externo_enviado", "geolocation": [-31.4201, -64.1888], "sourceData": { "pin": "...", "emvData": "...", "cryptogram": "...", "ksn": "...", "track2": "..." } }

Respuesta exitosa — flujo QR (con source):

{ "result": true, "intentToken": "token_generado_por_mobbex", "operationId": "kS6D18unD", "source": "arg.qr", "status": { "code": "100", "text": "Pendiente" }, "geolocation": [-31.4201, -64.1888] }

Cuando se envía source, SDConn:

Crea el intent token (o usa el intentToken externo).

Llama al endpoint de operación (/p/operations/{token}) con la fuente.

Descarga la imagen QR del resultado y la codifica en base64.

Envía la imagen al dispositivo POS para que la muestre en pantalla.

Retorna los datos de la operación (el pago queda pendiente hasta que el usuario escanee el QR).

Nota: En el flujo QR, la respuesta no contiene sourceData ya que no se lee una tarjeta. El campo operationId identifica la operación para consultar su estado. El campo status indica el estado actual de la operación (generalmente pendiente hasta que se escanee el QR).

Respuesta — modo asíncrono (async: true):

Cuando se envía async: true, SDConn ejecuta los pasos 1-3 (obtener info del dispositivo, ubicación y token) de forma síncrona y luego lanza la lectura de tarjeta o flujo QR en segundo plano. Responde inmediatamente con el intentToken para que el cliente pueda consultar el resultado cuando esté listo.

{ "result": true, "intentToken": "token_generado_o_externo", "async": true, "status": "pending" }

El resultado se consulta con GET /api/v1/read/:token (ver sección siguiente).

Error:

{ "result": false, "intentToken": "token_si_fue_generado", "error": "descripción del error" }

Posibles errores:

Error	Descripción
total is required and must be > 0	Falta el monto o es inválido
credentials not configured	No se configuraron credenciales (solo si no se envía intentToken). Cuando se usa un token externo, las credenciales no son necesarias
credentials required for source operations	Se envió source pero no hay credenciales (el flujo QR siempre requiere credenciales para llamar al endpoint de operación)
no device connected	No hay dispositivo conectado
device info not available	No se pudo obtener info del dispositivo
Card read failed	El dispositivo no pudo leer la tarjeta
TIMEOUT	Se agotó el tiempo de lectura (120s)
CANCELLED	La lectura fue cancelada
NOT_IN_PINPAD_MODE	El dispositivo no está en modo pinpad
Operate response did not contain a QR barcode	La respuesta del endpoint de operación no contiene el código QR esperado

GET /api/v1/read/:token

Consulta el resultado de una operación de lectura asíncrona iniciada con async: true.

Parámetro de ruta:

Parámetro	Tipo	Descripción
token	string	El intentToken devuelto por POST /api/v1/read

Respuesta — pendiente (la lectura aún está en progreso):

{ "result": false, "intentToken": "token", "status": "pending" }

Respuesta — completada (la lectura finalizó exitosamente):

{ "result": true, "intentToken": "token", "status": "completed", "sourceData": { "pin": "...", "emvData": "...", "cryptogram": "...", "ksn": "...", "track2": "..." } }

La respuesta contiene todos los campos que devolvería una lectura síncrona (sourceData, geolocation, etc.). El resultado se elimina del almacenamiento interno una vez consumido.

Respuesta — error (la lectura falló):

{ "result": false, "intentToken": "token", "status": "error", "error": "TIMEOUT" }

El resultado de error también se elimina una vez consumido.

Token no encontrado:

{ "result": false, "error": "no async operation found for this token" }

DELETE /api/v1/read

Cancela una lectura de tarjeta en progreso (tanto síncrona como asíncrona). Envía la señal de cancelación al dispositivo para que deje de esperar la tarjeta.

Respuesta:

{ "result": true }

Pantalla del dispositivo

Mostrar resultado — POST /api/v1/display

Muestra una pantalla de resultado con animación en el dispositivo POS. Es fire-and-forget: SDConn responde inmediatamente tras enviar el comando.

Cuerpo:

{ "status": "success", "title": "Pago Aprobado", "subtitle": "Visa **** 1234", "total": 15.00, "currency": "ARS", "text": "ID: 123456", "timeout": 10 }

Campo	Tipo	Requerido	Descripción
status	string o number	No	Estado del resultado (ver tablas abajo)
title	string	No	Título que se muestra en pantalla
subtitle	string	No	Subtítulo debajo del título
total	number	No	Monto como float (ej: 15.00)
currency	string	No	Código de moneda (ej: "ARS")
text	string	No	Texto adicional debajo del monto
timeout	number	No	Segundos antes de volver a pantalla de espera (defecto: 10). Usar 0 para desactivar.

Valores de status por nombre:

Valor	Animación
"success"	Círculo verde con check
"error"	Círculo rojo con X
"neutral"	Círculo naranja con reloj
"none"	Sin animación, fondo blanco

Valores de status por código numérico:

Se pueden enviar códigos numéricos directamente (por ejemplo, el status.code del procesador) y el dispositivo resuelve la animación automáticamente:

Códigos	Se resuelve a
3, 4, 200, 300-302, 605, 800	success
400-417, 500, 603, 604	error
1, 2, 100, 210, 600-602, 610	neutral
Otros	none

Respuesta:

{ "result": true }

Mostrar carga — POST /api/v1/display

Muestra una pantalla de carga con spinner en el dispositivo POS. Es fire-and-forget. Se usa para indicar que se está procesando una operación.

Cuerpo:

{ "view": "loading", "title": "Procesando pago...", "subtitle": "No retire la tarjeta", "timeout": 30 }

Campo	Tipo	Requerido	Descripción
view	string	Sí	Debe ser "loading"
title	string	No	Título que se muestra en pantalla
subtitle	string	No	Subtítulo debajo del título
timeout	number	No	Segundos antes de volver a pantalla de espera (defecto: 10). Usar 0 para desactivar.

Respuesta:

{ "result": true }

Para quitar la pantalla de carga, enviar un DELETE /api/v1/display o mostrar otra vista.

Mostrar selección — POST /api/v1/display

Muestra una pantalla con opciones seleccionables en el dispositivo POS. Es bloqueante: la petición HTTP queda en espera hasta que el usuario selecciona una opción o se agota el timeout.

Cuerpo:

{ "view": "choose", "title": "Seleccione cuotas", "subtitle": "Visa **** 1234", "values": [ { "label": "1 Pago - $15.00", "value": "1" }, { "label": "3 Cuotas - $5.75 c/u", "value": "3" }, { "label": "6 Cuotas - $3.08 c/u", "value": "6" } ], "timeout": 60 }

Campo	Tipo	Requerido	Descripción
view	string	Sí	Debe ser "choose"
title	string	No	Título de la pantalla
subtitle	string	No	Subtítulo
values	array	Sí	Lista de opciones. Cada opción tiene label (texto visible) y value (valor de retorno)
timeout	number	No	Segundos de espera antes de timeout (defecto: 60)

Respuesta exitosa (usuario seleccionó una opción):

{ "result": true, "selected": { "label": "3 Cuotas - $5.75 c/u", "value": "3" } }

Respuesta — timeout:

{ "result": false, "error": "TIMEOUT" }

Ocultar pantalla — DELETE /api/v1/display

Oculta la pantalla del dispositivo antes de que expire el timeout. El dispositivo vuelve a la pantalla de espera de pinpad.

Respuesta:

{ "result": true }

Información de tarjeta

POST /api/v1/card/info

Analiza los datos de track de una tarjeta y extrae el código de servicio para determinar si la tarjeta tiene chip EMV o capacidad contactless (NFC). No requiere conexión con un dispositivo — es un utilitario de parsing local.

Cuerpo:

{ "track1": "%B4111111111111111^DOE/JOHN^2512101000000000?", "track2": ";4111111111111111=2512101000000000?" }

Campo	Tipo	Requerido	Descripción
track1	string	No	Datos de track 1 (actualmente no se parsea, reservado para uso futuro)
track2	string	Sí	Datos de track 2 (formato ISO 7813)

Formato de Track 2:

;PAN=YYMMSSSDDDDDDDDD? │ │ │ └─ Datos discrecionales │ │ └─── Código de servicio (3 dígitos) │ └────── Vencimiento (AAMM) └─────────── Número de tarjeta (PAN)

El separador puede ser = (texto) o D (hex).

Respuesta exitosa:

{ "result": true, "pan": "41111111****1111", "expiry": "2512", "serviceCode": { "code": "101", "hasChip": true, "chipRequired": true, "contactless": false, "international": true, "pinRequired": false, "cashAllowed": true } }

Campo	Tipo	Descripción
pan	string	PAN enmascarado (primeros 8 dígitos del BIN + últimos 4 dígitos)
expiry	string	Vencimiento en formato AAMM
serviceCode.code	string	Código de servicio de 3 dígitos
serviceCode.hasChip	boolean	La tarjeta tiene chip EMV (IC)
serviceCode.chipRequired	boolean	El chip es obligatorio (no se permite fallback a banda magnética)
serviceCode.contactless	boolean	La tarjeta soporta contactless (NFC/tap)
serviceCode.international	boolean	La tarjeta es de intercambio internacional
serviceCode.pinRequired	boolean	Se requiere PIN para la transacción
serviceCode.cashAllowed	boolean	Se permite retiro de efectivo

Referencia del primer dígito del código de servicio:

Dígito	Significado	hasChip	chipRequired	contactless
1	Internacional, chip obligatorio	✓	✓
2	Internacional, chip + contactless	✓		✓
5	Nacional, chip obligatorio	✓	✓
6	Nacional, chip + contactless	✓		✓
7	Privado, chip obligatorio	✓	✓
0	Solo banda magnética

Error:

{ "result": false, "error": "invalid track2: no separator found (expected '=' or 'D')" }

Proxy de procesamiento

POST /api/v1/p/operations/:token

Proxy directo a la API de Mobbex (POST {mobbexAPIBase}/p/operations/{token}). Reenvía el cuerpo tal cual, sin parsing ni validación. Útil cuando el intent token se genera externamente y se quiere procesar la operación sin pasar por el flujo de lectura.

Las credenciales de Mobbex (si están configuradas) se agregan automáticamente como headers x-api-key y x-access-token.

Parámetro de ruta:

Parámetro	Tipo	Descripción
token	string	Intent token a operar

Cuerpo: Se envía directamente a la API de Mobbex sin modificaciones.

Respuesta: Se reenvía directamente la respuesta de la API de Mobbex sin modificaciones.

Conexión al dispositivo por API

POST /api/v1/connect

Inicia una conexión al dispositivo de forma programática (alternativa al panel de administración).

Conexión serial:

{ "mode": "serial", "port": "COM3" }

Campo	Tipo	Requerido	Descripción
mode	string	Sí	Debe ser "serial"
port	string	Sí	Nombre del puerto serial (ej: "COM3", "/dev/cu.usbmodem1421")

Respuesta exitosa (serial):

{ "result": true, "mode": "serial", "port": "COM3", "connected": true }

La conexión serial se establece inmediatamente (handshake + modo pinpad). No requiere verificación adicional.

Conexión HTTP:

{ "mode": "http", "ip": "192.168.1.50", "port": "5000" }

Campo	Tipo	Requerido	Descripción
mode	string	Sí	Debe ser "http"
ip	string	Sí	IP del dispositivo
port	string	No	Puerto del dispositivo (defecto: 5000)

Respuesta exitosa (HTTP):

{ "result": true, "mode": "http", "ip": "192.168.1.50", "port": 5000, "verificationNeeded": true, "message": "Enter the PIN displayed on the device using POST /api/v1/connect/verify" }

El dispositivo mostrará un PIN en pantalla. Se debe verificar con POST /api/v1/connect/verify.

POST /api/v1/connect/verify

Verifica el PIN mostrado en el dispositivo para completar la conexión HTTP.

Cuerpo:

{ "ip": "192.168.1.50", "port": 5000, "pin": "123456" }

Campo	Tipo	Requerido	Descripción
ip	string	Sí	IP del dispositivo
port	number	No	Puerto del dispositivo (defecto: 5000)
pin	string	Sí	PIN mostrado en el dispositivo

Respuesta exitosa:

{ "result": true, "mode": "http", "device": { "ip": "192.168.1.50", "port": 5000, "name": "POS N62" }, "connected": true }

Error (PIN inválido):

{ "result": false, "error": "invalid PIN" }

Reconexión

POST /api/v1/reconnect

Intenta reconectarse al último dispositivo guardado usando el token de confianza. No requiere PIN.

Respuesta exitosa:

{ "result": true, "device": { "ip": "192.168.1.50", "port": 5000, "name": "POS N62" } }

Error:

{ "result": false, "error": "no saved device or device not reachable" }

Dispositivo

GET /api/v1/device/info

Obtiene información del hardware y software del dispositivo conectado.

Respuesta:

{ "type": "POS", "serialNumber": "SN12345", "deviceExtras": { "os": "Android", "osVersion": "11", "manufacturer": "nexgo", "model": "N62", "serialNumber": "SN12345", "bundleId": "com.sugaway.pos", "buildNumber": 42, "appVersion": "1.2.3", "romVersion": "N62-20230101", "kernelVersion": "4.14.116" } }

La información se cachea en memoria por 24 horas y se limpia al cambiar de modo de conexión o dispositivo.

GET /api/v1/device/location

Obtiene la ubicación GPS del dispositivo. Se cachea por 5 minutos. La consulta al dispositivo tiene un timeout de 1 segundo — si no responde a tiempo, se omite la ubicación (no se envía en la operación). Si no hay ubicación disponible (ni en caché ni del dispositivo), la operación continúa sin geolocalización.

Respuesta — ubicación disponible:

{ "latitude": -31.4201, "longitude": -64.1888, "accuracy": 12.5, "provider": "gps", "timestamp": 1741564800000 }

Respuesta — ubicación no disponible:

{ "error": "Location not available" }

GET /api/v1/devices

Lista los dispositivos conectados actualmente.

Respuesta:

{ "result": true, "devices": [ { "ip": "192.168.1.50", "port": 5000, "name": "POS N62" } ] }

Si no hay dispositivo conectado, devices es un array vacío.

DELETE /api/v1/devices/:id

Elimina un dispositivo de la lista de dispositivos activos.

Respuesta:

{ "result": true }

PATCH /api/v1/devices/:id/mode

Cambia el modo de operación del dispositivo.

Cuerpo:

{ "mode": "pinpad" }

Modo	Descripción
normal	Modo POS estándar con pantalla de ingreso de monto
slave	Modo cola. Recibe trabajos de pago desde una cola
transit	Lectura continua de tarjetas para peajes/transporte
pinpad	Modo pinpad. Espera comandos de lectura del controlador

POST /api/v1/pinpad-config

Personaliza la pantalla de espera del modo pinpad. Permite configurar título, subtítulo e imagen de fondo.

Todos los campos son opcionales — solo se envían al dispositivo los campos proporcionados. Los campos omitidos no se modifican.

Si background_image es una URL (http:// o https://), SDConn descarga la imagen, la redimensiona y optimiza automáticamente antes de enviarla al dispositivo:

Imágenes estáticas (PNG, JPEG): se redimensionan a máximo 480px de ancho (manteniendo proporción) y se re-codifican como JPEG calidad 80.

GIF animados: se redimensionan a máximo 480px de ancho, se limitan a 90 frames (eliminando frames de forma uniforme y acumulando los delays para mantener la velocidad de animación), y se re-codifican como GIF con dithering Floyd-Steinberg y paleta de 256 colores.

Nota: background_image solo está disponible en modo HTTP. Si se envía en modo serial, se retorna un error.

Cuerpo:

{ "title": "Mi Negocio", "subtitle": "Acerque o inserte su tarjeta", "background_image": "https://example.com/background.png" }

Campo	Tipo	Requerido	Descripción
title	string	No	Título mostrado en la pantalla de espera
subtitle	string	No	Subtítulo mostrado debajo del título
background_image	string	No	URL de la imagen de fondo (PNG, JPEG o GIF) o string base64. Si es URL, se descarga, optimiza y convierte a base64 automáticamente. Solo disponible en modo HTTP.

Comportamiento según modo de conexión:

Serial: Solo title y subtitle. Se envía como campo waiting dentro del mensaje SET_MODE ({ mode: "pinpad", waiting: { title, subtitle } }). Si se envía background_image, se retorna error.

HTTP: Se envía via POST /device/pinpad-config al dispositivo. Soporta los 3 campos.

Respuesta exitosa:

{ "result": true }

Errores:

{ "result": false, "error": "no device connected" }

{ "result": false, "error": "background_image is only available in HTTP mode" }

Flujo típico de uso

Sin token externo (flujo estándar)

App PC SDConn Dispositivo POS │ │ │ │ POST /api/v1/read │ │ │ { total: 15.00 } │ │ │ ─────────────────────────────>│ │ │ │ (obtiene info del dispositivo)│ │ │ ──────────────────────────────>│ │ │<──────────────────────────────│ │ │ │ │ │ (crea operación en Mobbex) │ │ │ ──────────> Mobbex API │ │ │<────────── { token } │ │ │ │ │ │ (lectura de tarjeta) │ │ │ ──────────────────────────────>│ │ │ (usuario pasa tarjeta)│ │ │<────────── { sourceData } │ │ │ │ │ { result: true, │ │ │ intentToken: "...", │ │ │ sourceData: {...} } │ │ │<─────────────────────────────│ │ │ │ │ │ POST /api/v1/display │ │ │ { status: "success" } │ │ │ ─────────────────────────────>│ │ │ │ ──────────────────────────────>│ │ │ (pantalla de resultado)│

Con token externo

App PC SDConn Dispositivo POS │ │ │ │ POST /api/v1/read │ │ │ { total: 15.00, │ │ │ intentToken: "ext_token" } │ │ │ ─────────────────────────────>│ │ │ │ (obtiene info del dispositivo)│ │ │ ──────────────────────────────>│ │ │<──────────────────────────────│ │ │ │ │ │ (omite llamada a Mobbex API) │ │ │ │ │ │ (lectura de tarjeta) │ │ │ ──────────────────────────────>│ │ │ (usuario pasa tarjeta)│ │ │<────────── { sourceData } │ │ │ │ │ { result: true, │ │ │ intentToken: "ext_token", │ │ │ geolocation: [lat, lng], │ │ │ sourceData: {...} } │ │ │<─────────────────────────────│ │

Flujo QR (con source)

App PC SDConn Dispositivo POS │ │ │ │ POST /api/v1/read │ │ │ { total: 15.00, │ │ │ source: "arg.qr" } │ │ │ ─────────────────────────────>│ │ │ │ (obtiene info del dispositivo)│ │ │ ──────────────────────────────>│ │ │<──────────────────────────────│ │ │ │ │ │ (crea operación en Mobbex) │ │ │ ──────────> Mobbex API │ │ │<────────── { token } │ │ │ │ │ │ (obtiene QR de Mobbex) │ │ │ ──────────> Mobbex API │ │ │<────────── { barcode } │ │ │ │ │ │ (muestra QR en dispositivo) │ │ │ ──────────────────────────────>│ │ │ (QR visible en pantalla)│ │ │ │ │ { result: true, │ │ │ intentToken: "...", │ │ │ operationId: "...", │ │ │ source: "arg.qr", │ │ │ status: { code, text }, │ │ │ geolocation: [lat, lng] } │ │ │<─────────────────────────────│ │ │ │ │ │ (espera a que el usuario │ │ │ escanee el QR — consultar │ │ │ estado externamente) │ │ │ │ │ │ DELETE /api/v1/read │ │ │ (cuando quiera cancelar) │ │ │ ─────────────────────────────>│ ──────────────────────────────>│ │ │ (quita QR) │

Flujo asíncrono

App PC SDConn Dispositivo POS │ │ │ │ POST /api/v1/read │ │ │ { total: 15.00, │ │ │ async: true } │ │ │ ─────────────────────────────>│ │ │ │ (obtiene info del dispositivo)│ │ │ ──────────────────────────────>│ │ │<──────────────────────────────│ │ │ │ │ │ (crea operación en Mobbex) │ │ │ ──────────> Mobbex API │ │ │<────────── { token } │ │ │ │ │ { result: true, │ (lanza lectura en background) │ │ intentToken: "...", │ ──────────────────────────────>│ │ async: true, │ │ │ status: "pending" } │ │ │<─────────────────────────────│ │ │ │ │ │ (polling) │ │ │ GET /api/v1/read/:token │ │ │ ─────────────────────────────>│ │ │ { status: "pending" } │ │ │<─────────────────────────────│ │ │ │ (usuario pasa tarjeta)│ │ ... │<────────── { sourceData } │ │ │ │ │ GET /api/v1/read/:token │ │ │ ─────────────────────────────>│ │ │ { result: true, │ │ │ status: "completed", │ │ │ intentToken: "...", │ │ │ sourceData: {...} } │ │ │<─────────────────────────────│ │

Flujo con vista choose (cuotas)

App PC SDConn Dispositivo POS │ │ │ │ POST /api/v1/display │ │ │ { view: "choose", │ │ │ title: "Cuotas", │ │ │ values: [...] } │ │ │ ─────────────────────────────>│ │ │ │ ──────────────────────────────>│ │ │ (usuario toca una opción)│ │ │<────────────────────────────── │ │ │ │ │ { result: true, │ │ │ selected: { │ │ │ label: "3 Cuotas", │ │ │ value: "3" } } │ │ │<─────────────────────────────│ │