Saltar al contenido principal

Introducción a la API Merchant

Bienvenido a la documentación oficial y guías de uso de la API Merchant de SPIDI.

Esta API está diseñada específicamente para permitir que aplicaciones externas —como tu propia aplicación comercial (Merchant App), sistemas ERP (Planificación de Recursos Empresariales), sistemas contables o cualquier otra plataforma de autogestión administrativa— se conecten y comuniquen bidireccionalmente con componentes de hardware físicos (Puntos de Venta o Terminales POS).

A través de esta integración, tu ecosistema corporativo puede centralizar el inicio de las operaciones de cobro de cara al público, delegando la confirmación de la tarjeta y transacción bancaria de forma segura al terminal físico.

Operaciones Disponibles​

Las funcionalidades principales que expone esta API, cuyos flujos están detallados en nuestras guías, incluyen:

  • Generación de Órdenes de Cobro: Iniciar una solicitud de pago desde el sistema administrativo o ERP para que aparezca lista de manera automática en la pantalla del Punto de Venta correspondiente.
  • Confirmación de Pagos: El proceso en el que el POS informa de vuelta al ecosistema API que la tarjeta o instrumento fue pasado exitosamente, cambiando el estado de la orden.
  • Descarte y Anulación de Operaciones:
    • Descarte (Discard) directo de una orden generada antes de que el pago llegara a ser confirmado por el POS.
    • Reverso o Anulación (Void) de un pago que ya fue procesado exitosamente en el POS.
  • Listado de Operaciones: Capacidad tanto para el sistema administrativo (Merchant) como para el terminal físico (POS) de consultar el historial de órdenes, permitiendo la sincronización de estados y la conciliación de pagos pendientes.
  • Cierre de Lotes (Settlements): Incluye tanto la generación del cierre de la jornada actual como el listado histórico de cierres anteriores procesados por el terminal, facilitando la conciliación operativa y administrativa.

Arquitectura de Seguridad (El Modelo Dual)​

Para garantizar la máxima seguridad en operaciones financieras distribuidas, la API Merchant de SPIDI implementa un mecanismo de seguridad dual, adaptado estrictamente según el actor que realiza la comunicación:

1. Para Sistemas Merchant (ERPs, Apps, Servidores)​

Las aplicaciones administrativas de tu comercio se comunican con la porción administrativa de la API utilizando Autenticación Virtual clásica. Este protocolo inicia con un inicio de sesión que intercambia credenciales por un Bearer Token (JWT) de corta duración. Este token debe incluirse en la cabecera Authorization de todas las peticiones que tu ERP envíe a SPIDI (como crear un cobro o consultar un ticket).

2. Para Puntos de Venta (Hardware POS)​

Dado que el hardware físico debe operar de forma automatizada y está naturalmente expuesto a intervención externa, SPIDI elimina el concepto de contraseñas en las terminales con una arquitectura de "Confianza Cero" (Zero Trust):

  • Pairing (Vinculación OTP): La vida de la terminal en el sistema inicia vinculándose con un código desechable OTP generado por tu administrador. Al validar este código, el servidor y la máquina negocian y almacenan internamente una Secret Key que jamás vuelve a circular por la red celular o WiFi.
  • Firma Criptográfica (HMAC-SHA256): En cada operación posterior (confirmar cobros, listar pagos, realizar cierres), el POS se autentica generando una firma digital inviolable en la cabecera HTTP. La firma es el resultado del cifrado criptográfico con HMAC combinando la Secret Key, el cuerpo de la petición (JSON), una marca de tiempo estricta y la URL exacta. Esto anula toda posibilidad de alteración de pagos (Man in the Middle) y ataques de repetición (Replay Attacks).

Índice de Contenidos​

Explora las guías de uso detalladas a continuación o consulta directamente la especificación técnica en formato OpenAPI:

  1. Registro y Autenticación de Merchant: Comprende cómo obtener el Token Bearer mediante el login virtual para tu ERP.
  2. Comunicación y Vinculación de POS: Detalles técnicos para la integración del Pairing OTP y cómo el firmware debe calcular la firma HMAC.
  3. Proceso de Pago: Ciclo completo sobre cómo solicitar una orden y esperar a que el POS envíe la confirmación.
  4. Proceso de Descarte y Anulación: Lógica administrativa para descartar órdenes no cobradas (DISCARDED) o revertir (VOID) pagos exitosos.
  5. Cierre de Lote (Settlement): Ejecución desde el terminal y consulta administrativa.